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

package/dist/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",
@@ -784,6 +788,237 @@ function networkDiscoveryKey(name) {
 var ENCRYPTION_NETWORK_URN_PREFIX = URN_PREFIX;
 var NETWORK_NAME_PATTERN = NETWORK_NAME_RE;
 
+// src/resourceRouting.ts
+async function verifyResourceDestination(target, fetchFn) {
+  if (!target.nodeDid) return;
+  let info;
+  let keys;
+  try {
+    const signal = AbortSignal.timeout(5e3);
+    const responses = await Promise.all([
+      fetchFn(`${target.url}/info`, { signal, redirect: "error" }),
+      fetchFn(`${target.url}/.well-known/tinycloud/node-keys`, { signal, redirect: "error" })
+    ]);
+    if (responses.some((response) => response.status >= 500)) throw new NodeNotRespondingError([target.url]);
+    if (responses.some((response) => !response.ok)) throw new NodeIdentityMismatchError(target.url, target.nodeDid);
+    try {
+      [info, keys] = await Promise.all(responses.map((response) => response.json()));
+    } catch {
+      throw new NodeIdentityMismatchError(target.url, target.nodeDid);
+    }
+  } catch (error) {
+    if (error instanceof NodeIdentityMismatchError || error instanceof NodeNotRespondingError) throw error;
+    throw new NodeNotRespondingError([target.url], error);
+  }
+  const infoDid = typeof info === "object" && info !== null && "nodeId" in info && typeof info.nodeId === "string" ? info.nodeId : void 0;
+  const keysDid = typeof keys === "object" && keys !== null && "nodeDid" in keys && typeof keys.nodeDid === "string" ? keys.nodeDid : void 0;
+  if (infoDid !== target.nodeDid || keysDid !== target.nodeDid) {
+    throw new NodeIdentityMismatchError(target.url, target.nodeDid, infoDid !== target.nodeDid ? infoDid : keysDid);
+  }
+  return info;
+}
+var NodeNotRespondingError = class extends Error {
+  constructor(hosts, cause) {
+    super("The place your data is stored isn't responding right now. Please try again.");
+    this.hosts = hosts;
+    this.cause = cause;
+    this.code = "NODE_NOT_RESPONDING";
+    this.name = "NodeNotRespondingError";
+  }
+};
+var NodeIdentityMismatchError = class extends Error {
+  constructor(url, expectedDid, actualDid) {
+    super(`TinyCloud node identity does not match the registry at ${url}`);
+    this.url = url;
+    this.expectedDid = expectedDid;
+    this.actualDid = actualDid;
+    this.code = "NODE_IDENTITY_MISMATCH";
+    this.name = "NodeIdentityMismatchError";
+  }
+};
+var ResourceNotRoutedError = class extends Error {
+  constructor(resource) {
+    super(`No registered destination can serve ${resource}`);
+    this.resource = resource;
+    this.code = "RESOURCE_NOT_ROUTED";
+    this.name = "ResourceNotRoutedError";
+  }
+};
+var PartialNodeWriteError = class extends Error {
+  constructor(succeeded, failed) {
+    super("The write did not complete on every registered writable node.");
+    this.succeeded = succeeded;
+    this.failed = failed;
+    this.code = "PARTIAL_NODE_WRITE";
+    this.name = "PartialNodeWriteError";
+  }
+};
+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;
+}
+function authorizationOf(headers) {
+  if (headers === void 0) return void 0;
+  return (Array.isArray(headers) ? headers : Object.entries(headers)).find(([name]) => name.toLowerCase() === "authorization")?.[1];
+}
+function routingResourceOf(uri) {
+  if (uri.startsWith("tinycloud://")) {
+    const resource = uri.slice("tinycloud://".length).split("/", 1)[0];
+    if (resource) return resource;
+  } else if (uri.startsWith("urn:tinycloud:encryption:")) {
+    return uri;
+  } else if (uri.startsWith("tinycloud:")) {
+    return uri.split("/", 1)[0];
+  }
+  throw new ResourceNotRoutedError(uri);
+}
+function invocationResources(authorization) {
+  const encoded = authorization.split(".")[1];
+  if (!encoded) throw new ResourceNotRoutedError("invalid invocation");
+  const payload = JSON.parse(atob(encoded.replace(/-/g, "+").replace(/_/g, "/")));
+  if (typeof payload !== "object" || payload === null || !("att" in payload) || typeof payload.att !== "object" || payload.att === null || Array.isArray(payload.att)) {
+    throw new ResourceNotRoutedError("invalid invocation attenuation");
+  }
+  const resources = [];
+  for (const [uri, abilities] of Object.entries(payload.att)) {
+    if (typeof abilities !== "object" || abilities === null || Array.isArray(abilities)) throw new ResourceNotRoutedError(uri);
+    for (const action of Object.keys(abilities)) {
+      const resource = routingResourceOf(uri);
+      const read2 = /^(tinycloud\.(kv\/(get|list|metadata|head|sync)|sql\/(read|export)|duckdb\/(read|describe|export)|capabilities\/read|space\/(list|info)|hooks\/list))$/.test(action);
+      const access = resource.startsWith("urn:tinycloud:encryption:") ? "encryption" : action === "tinycloud.space/host" ? "host" : read2 ? "read" : "write";
+      if (!resources.some((entry) => entry.resource === resource && entry.access === access)) resources.push({ resource, access });
+    }
+  }
+  if (resources.length === 0) throw new ResourceNotRoutedError("empty invocation");
+  return resources;
+}
+async function routeResourceRequest(resources, routing, send, options) {
+  if (resources.length === 0) throw new ResourceNotRoutedError("empty request");
+  const routes = await Promise.all(resources.map(({ resource, access }) => routing.resolveResource(resource, access)));
+  if (routes.some((route) => route.length === 0)) throw new ResourceNotRoutedError(resources[routes.findIndex((route) => route.length === 0)].resource);
+  const write = options?.independentResources === true || resources.some(({ access }) => access === "write" || access === "host");
+  let targets;
+  if (options?.independentResources) {
+    targets = routes.flat();
+    const identities = /* @__PURE__ */ new Map();
+    for (const target of targets) {
+      if (identities.has(target.url) && identities.get(target.url) !== target.nodeDid) throw new ResourceNotRoutedError(target.url);
+      identities.set(target.url, target.nodeDid);
+    }
+  } else {
+    targets = routes[0].filter((target) => routes.every((route) => route.some((other) => other.url === target.url && other.nodeDid === target.nodeDid)));
+    if (targets.length === 0 || write && routes.some((route) => route.length !== targets.length)) throw new ResourceNotRoutedError(resources.map(({ resource }) => resource).join(", "));
+  }
+  targets = targets.filter((target, index) => targets.findIndex((other) => other.url === target.url) === index);
+  if (options?.nodeDid) targets = targets.filter((target) => target.nodeDid === options.nodeDid || target.nodeDid === void 0);
+  if (targets.length === 0 || options?.nodeLocal && targets.length !== 1) throw new ResourceNotRoutedError(resources.map(({ resource }) => resource).join(", "));
+  if (!write) {
+    let response2;
+    let failure;
+    for (const target of targets) {
+      try {
+        response2 = await send(target);
+        if (response2.ok || response2.status !== 404) return response2;
+      } catch (error) {
+        if (!(error instanceof NodeNotRespondingError)) throw error;
+        failure = error;
+      }
+    }
+    if (failure) throw new NodeNotRespondingError(targets.map(({ url }) => url), failure);
+    if (response2) return response2;
+    throw new NodeNotRespondingError(targets.map(({ url }) => url), failure);
+  }
+  const succeeded = [];
+  const failed = [];
+  let response;
+  let failureResponse;
+  for (const target of targets) {
+    try {
+      const result = await send(target);
+      if (result.ok) {
+        succeeded.push(target.url);
+        response ?? (response = result);
+      } else {
+        failed.push({ url: target.url, status: result.status });
+        failureResponse ?? (failureResponse = result);
+      }
+    } catch (error) {
+      if (!routingFailure(error) && succeeded.length === 0) throw error;
+      failed.push({ url: target.url, cause: error });
+    }
+  }
+  if (failed.length > 0) {
+    if (succeeded.length > 0 || targets.length > 1) throw new PartialNodeWriteError(succeeded, failed);
+    if (failureResponse) return failureResponse;
+    if (failed[0]?.cause && !(failed[0].cause instanceof NodeNotRespondingError)) throw failed[0].cause;
+    throw new NodeNotRespondingError(targets.map(({ url }) => url), failed[0]?.cause);
+  }
+  return response;
+}
+function createResourceTransportInvocationFetch(transport, session) {
+  return async (url, init) => {
+    const parsed = new URL(url);
+    if (parsed.pathname !== "/invoke") throw new ResourceNotRoutedError(parsed.pathname);
+    const authorization = authorizationOf(init?.headers);
+    if (!authorization) throw new ResourceNotRoutedError("unsigned invocation");
+    return transport(invocationResources(authorization), async (target) => {
+      const signed = await target.bindAudience(authorization);
+      const headers = (Array.isArray(init?.headers) ? init.headers : Object.entries(init?.headers ?? {})).filter(([name]) => name.toLowerCase() !== "authorization");
+      headers.push(["Authorization", signed]);
+      return target.fetch(`${target.url}${parsed.pathname}${parsed.search}`, { ...init, headers });
+    }, { invocationSession: session });
+  };
+}
+function createResourceRoutingFetch(fetchFn, routing) {
+  return async (url, init) => {
+    const parsed = new URL(url);
+    if (parsed.pathname !== "/invoke") return fetchFn(url, init);
+    const authorization = authorizationOf(init?.headers);
+    if (!authorization) throw new ResourceNotRoutedError("unsigned invocation");
+    const resources = invocationResources(authorization);
+    const send = async (target) => {
+      init?.signal?.throwIfAborted();
+      if (routing.verifyDestination) await routing.verifyDestination(target);
+      else await verifyResourceDestination(target, fetchFn);
+      const signed = target.nodeDid ? await routing.bindAudience(authorization, target.nodeDid) : authorization;
+      const headers = (Array.isArray(init?.headers) ? init.headers : Object.entries(init?.headers ?? {})).filter(([name]) => name.toLowerCase() !== "authorization");
+      headers.push(["Authorization", signed]);
+      const timeout = AbortSignal.timeout(5e3);
+      const signal = init?.signal ? AbortSignal.any([init.signal, timeout]) : timeout;
+      try {
+        return await fetchFn(`${target.url}${parsed.pathname}${parsed.search}`, { ...init, headers, signal, redirect: "error" });
+      } catch (error) {
+        if (init?.signal?.aborted) throw error;
+        if (routingFailure(error)) throw error;
+        throw new NodeNotRespondingError([target.url], error);
+      }
+    };
+    return routeResourceRequest(resources, routing, send);
+  };
+}
+
 // src/errors.ts
 function parsePermissionHint(value) {
   if (typeof value !== "object" || value === null || Array.isArray(value)) return void 0;
@@ -1089,6 +1324,8 @@ function isStorageFullError(error) {
   return error?.code === ErrorCodes.STORAGE_QUOTA_EXCEEDED || error?.code === ErrorCodes.STORAGE_LIMIT_REACHED;
 }
 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);
@@ -5786,9 +6023,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/vault/types.ts
@@ -6030,6 +6267,8 @@ function defaultVaultMessage(input) {
     case "STORAGE_QUOTA_EXCEEDED":
     case "STORAGE_LIMIT_REACHED":
       return input.message;
+    default:
+      return input.message ?? input.code;
   }
 }
 function vaultError(input) {
@@ -6081,6 +6320,8 @@ function ifMatchWriteError(key, error) {
   });
 }
 function kvWriteError(context, error) {
+  const routing = routingFailure(error);
+  if (routing) return vaultError(routing);
   if (error.code === ErrorCodes.STORAGE_QUOTA_EXCEEDED || error.code === ErrorCodes.STORAGE_LIMIT_REACHED) {
     return vaultError({ code: error.code, message: error.message, meta: error.meta });
   }
@@ -6387,6 +6628,8 @@ var DataVaultService = class extends BaseService {
         { aad, metadata }
       );
       if (!envelopeResult.ok) {
+        const routing = routingFailure(envelopeResult.error);
+        if (routing) return vaultError(routing);
         return vaultError({
           code: "STORAGE_ERROR",
           cause: new Error(envelopeResult.error.message)
@@ -6413,6 +6656,8 @@ var DataVaultService = class extends BaseService {
       }
       return { ok: true, data: void 0 };
     } catch (error) {
+      const routing = routingFailure(error);
+      if (routing) return vaultError(routing);
       return vaultError({
         code: "STORAGE_ERROR",
         cause: toError(error)
@@ -6439,6 +6684,8 @@ var DataVaultService = class extends BaseService {
         ...options?.source === void 0 ? {} : { source: options.source }
       });
       if (!valueResult.ok) {
+        const routing = routingFailure(valueResult.error);
+        if (routing) return vaultError(routing);
         return vaultError({ code: "KEY_NOT_FOUND", key });
       }
       const rawEnvelope = unwrapKVData(valueResult.data);
@@ -6459,6 +6706,8 @@ var DataVaultService = class extends BaseService {
       const proof = await this.decryptCapabilityProof();
       const plaintextResult = await config.service.decryptEnvelope(envelope, proof);
       if (!plaintextResult.ok) {
+        const routing = routingFailure(plaintextResult.error);
+        if (routing) return vaultError(routing);
         return vaultError({
           code: "DECRYPTION_FAILED",
           message: plaintextResult.error.message
@@ -6478,6 +6727,8 @@ var DataVaultService = class extends BaseService {
         data: { value, metadata, keyId, ...etag === void 0 ? {} : { etag } }
       };
     } catch (error) {
+      const routing = routingFailure(error);
+      if (routing) return vaultError(routing);
       return vaultError({
         code: "STORAGE_ERROR",
         cause: toError(error)
@@ -6490,6 +6741,8 @@ var DataVaultService = class extends BaseService {
    * Unlike {@link getNetworkEncrypted}, this is intentionally message-free so
    * an operation layer can distinguish an authorized absence from a failed
    * read without receiving node, envelope, plaintext, or key material.
+   * Typed routing failures reject unchanged rather than becoming an ordinary
+   * read/decrypt failure; the operation boundary projects their safe code.
    */
   async readNetworkEncrypted(key, options) {
     const config = this.networkEncryption;
@@ -6499,10 +6752,12 @@ var DataVaultService = class extends BaseService {
     let valueResult;
     try {
       valueResult = await this.tc.kv.get(`vault/${key}`, { raw: true, source: "network" });
-    } catch {
+    } catch (error) {
+      if (routingFailure(error)) throw error;
       return { status: "node_unreachable" };
     }
     if (!valueResult.ok) {
+      if (routingFailure(valueResult.error)) throw valueResult.error;
       const permissionHint = parsePermissionHint(valueResult.error.meta?.permissionHint);
       if (valueResult.error.code === "AUTH_UNAUTHORIZED" && permissionHint !== void 0) {
         return { status: "permission_required", hint: permissionHint };
@@ -6510,7 +6765,7 @@ var DataVaultService = class extends BaseService {
       if ((valueResult.error.code === "NOT_FOUND" || valueResult.error.code === "KV_NOT_FOUND") && !hasHttpResponse(valueResult.error)) {
         return { status: "not_found" };
       }
-      if (valueResult.error.code === "NETWORK_ERROR" || valueResult.error.code === "TIMEOUT" || valueResult.error.code === "ABORTED") {
+      if (valueResult.error.code === "NODE_NOT_RESPONDING" || valueResult.error.code === "NETWORK_ERROR" || valueResult.error.code === "TIMEOUT" || valueResult.error.code === "ABORTED") {
         return hasHttpResponse(valueResult.error) ? { status: "read_failed" } : { status: "node_unreachable" };
       }
       return { status: "read_failed" };
@@ -6532,10 +6787,12 @@ var DataVaultService = class extends BaseService {
     try {
       const proof = await this.decryptCapabilityProof();
       plaintextResult = await config.service.decryptEnvelope(envelope, proof);
-    } catch {
+    } catch (error) {
+      if (routingFailure(error)) throw error;
       return { status: "decrypt_failed" };
     }
     if (!plaintextResult.ok) {
+      if (routingFailure(plaintextResult.error)) throw plaintextResult.error;
       const permissionHint = parsePermissionHint(
         plaintextResult.error.permissionHint
       );
@@ -6545,7 +6802,7 @@ var DataVaultService = class extends BaseService {
       if (plaintextResult.error.code === "INVALID_ENVELOPE") {
         return { status: "corrupt_envelope" };
       }
-      if (plaintextResult.error.code === "TRANSPORT_ERROR") {
+      if (plaintextResult.error.code === "NODE_NOT_RESPONDING" || plaintextResult.error.code === "TRANSPORT_ERROR") {
         return { status: "node_unreachable" };
       }
       return { status: "decrypt_failed" };
@@ -6797,6 +7054,8 @@ var DataVaultService = class extends BaseService {
         if (this.usesNetworkEncryption) {
           const valueDelResult2 = await this.tc.kv.delete(`vault/${key}`);
           if (!valueDelResult2.ok) {
+            const routing = routingFailure(valueDelResult2.error);
+            if (routing) return vaultError(routing);
             return vaultError({ code: "KEY_NOT_FOUND", key });
           }
           return ok(void 0);
@@ -6806,10 +7065,14 @@ var DataVaultService = class extends BaseService {
           this.tc.kv.delete(`vault/${key}`)
         ]);
         if (!keyDelResult.ok && !valueDelResult.ok) {
+          const routing = routingFailure(keyDelResult.error) ?? routingFailure(valueDelResult.error);
+          if (routing) return vaultError(routing);
           return vaultError({ code: "KEY_NOT_FOUND", key });
         }
         return ok(void 0);
       } catch (error) {
+        const routing = routingFailure(error);
+        if (routing) return vaultError(routing);
         return vaultError({
           code: "STORAGE_ERROR",
           cause: toError(error)
@@ -6851,6 +7114,8 @@ var DataVaultService = class extends BaseService {
           ...options?.cursor === void 0 ? {} : { cursor: options.cursor }
         });
         if (!listResult.ok) {
+          const routing = routingFailure(listResult.error);
+          if (routing) return vaultError(routing);
           return vaultError({
             code: "STORAGE_ERROR",
             cause: new Error(
@@ -6871,6 +7136,8 @@ var DataVaultService = class extends BaseService {
           ...listResult.data.nextCursor === void 0 ? {} : { nextCursor: listResult.data.nextCursor }
         });
       } catch (error) {
+        const routing = routingFailure(error);
+        if (routing) return vaultError(routing);
         return vaultError({
           code: "STORAGE_ERROR",
           cause: toError(error)
@@ -7702,6 +7969,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) {
@@ -7766,6 +8035,8 @@ async function discoverNetwork(input) {
         return { ok: true, data: { descriptor: validated.data, source: "node" } };
       }
     } catch (err3) {
+      const routing = routingFailure(err3);
+      if (routing) return { ok: false, error: encryptionError(routing) };
     }
   }
   if (input.wellKnown !== void 0) {
@@ -7783,6 +8054,8 @@ async function discoverNetwork(input) {
         };
       }
     } catch (err3) {
+      const routing = routingFailure(err3);
+      if (routing) return { ok: false, error: encryptionError(routing) };
     }
   }
   return {
@@ -7872,6 +8145,152 @@ 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);
+}
+
 // src/encryption/envelope.ts
 function encryptToNetwork(crypto2, input) {
   const parsedResource = parseEncryptionResource(
@@ -7880,11 +8299,20 @@ function encryptToNetwork(crypto2, 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 = crypto2.randomBytes(32);
   const ciphertext = crypto2.authEncrypt(symmetricKey, input.plaintext, input.aad);
-  const wrapped = crypto2.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 ?? {}
+  }) : crypto2.sealToNetworkKey(input.networkPublicKey, symmetricKey);
   const encryptedSymmetricKey = base64Encode(wrapped);
   const encryptedSymmetricKeyHash = canonicalHashHex(
     crypto2.sha256,
@@ -7904,7 +8332,7 @@ function encryptToNetwork(crypto2, input) {
   };
   return { envelope, symmetricKey };
 }
-function validateEnvelope(crypto2, envelope) {
+function validateEnvelope(crypto2, envelope, requireKeyWrapV2 = false) {
   if (envelope === null || typeof envelope !== "object") {
     return {
       ok: false,
@@ -7981,9 +8409,28 @@ function validateEnvelope(crypto2, 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(crypto2, envelope, symmetricKey) {
+  validateEnvelopeKeyWrap(envelope);
   const ciphertext = base64Decode(envelope.ciphertext);
   const aad = envelope.aad !== void 0 ? base64Decode(envelope.aad) : void 0;
   return crypto2.authDecrypt(symmetricKey, ciphertext, aad);
@@ -8273,7 +8720,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({
@@ -8330,7 +8777,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({
@@ -8353,8 +8800,13 @@ function verifyDecryptResponse(input) {
   }
   return { ok: true, data: response };
 }
-function openWrappedKey(crypto2, receiverPrivateKey, response) {
+function openWrappedKey(crypto2, 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 crypto2.openWithReceiverKey(receiverPrivateKey, wrapped);
 }
 
@@ -8367,6 +8819,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();
@@ -8408,12 +8868,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",
@@ -8425,7 +8888,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(
@@ -8440,12 +8903,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({
@@ -8454,6 +8917,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(
@@ -8512,6 +8978,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(
@@ -8528,7 +8996,7 @@ var EncryptionService = class extends BaseService {
           );
         }
         return encErr(
-          encryptionError({
+          decryptionError({
             code: "TRANSPORT_ERROR",
             cause: toError2(error)
           })
@@ -8546,7 +9014,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,
@@ -8555,6 +9024,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",
@@ -8603,7 +9074,11 @@ export {
   MAX_SECRET_SCOPE_LENGTH,
   NETWORK_NAME_PATTERN,
   NetworkIdError,
+  NodeIdentityMismatchError,
+  NodeNotRespondingError,
+  PartialNodeWriteError,
   PrefixedKVService,
+  ResourceNotRoutedError,
   RetryPolicySchema,
   SECRET_NAME_RE,
   SECRET_SCOPE_RE,
@@ -8651,6 +9126,8 @@ export {
   checkDecryptInvocationInput,
   clearTinyCloudDebugLogs,
   createKVResponseSchema,
+  createResourceRoutingFetch,
+  createResourceTransportInvocationFetch,
   createResultSchema,
   createVaultCrypto,
   decryptEnvelopeWithKey,
@@ -8693,6 +9170,9 @@ export {
   requiresSecretsOptIn,
   resolveSecretListPrefix,
   resolveSecretPath,
+  routeResourceRequest,
+  routingFailure,
+  routingResourceOf,
   serviceError,
   storageLimitReachedError,
   storageQuotaExceededError,
@@ -8713,6 +9193,7 @@ export {
   validateTelemetrySpanEvent,
   validatedCapabilityOf,
   verifyDecryptResponse,
+  verifyResourceDestination,
   wrapError
 };
 //# sourceMappingURL=index.js.map