@tinycloud/sdk-services 3.2.6-beta.2 → 3.3.0-beta.11

package/dist/index.js

@@ -14,6 +14,14 @@ var ErrorCodes = {
   ABORTED: "ABORTED",
   INVALID_INPUT: "INVALID_INPUT",
   PERMISSION_DENIED: "PERMISSION_DENIED",
+  // Node retry signals (tinycloud-node #347). `meta.retryable` says whether a
+  // retry is safe; `meta.retryAfterMs` carries the node's Retry-After.
+  /** HTTP 503 `sql_busy:<stage>` / `unavailable_retryable`: nothing was applied; retry after `meta.retryAfterMs`. */
+  NODE_BUSY: "NODE_BUSY",
+  /** HTTP 503 `request_timeout`: the node's deadline passed before any write began; nothing was applied. */
+  REQUEST_TIMEOUT: "REQUEST_TIMEOUT",
+  /** HTTP 500 `outcome_unknown`: a write may have been applied; read back before retrying a non-idempotent operation. */
+  OUTCOME_UNKNOWN: "OUTCOME_UNKNOWN",
   // KV-specific errors
   KV_NOT_FOUND: "KV_NOT_FOUND",
   KV_WRITE_FAILED: "KV_WRITE_FAILED",
@@ -68,6 +76,8 @@ var TelemetryEvents = {
   REPLICATION_SYNC: "replication.sync",
   REPLICATION_STATE: "replication.state",
   REPLICATION_DIVERGENCE: "replication.divergence",
+  REPLICATION_GRANT: "replication.grant",
+  REPLICATION_LIFECYCLE: "replication.lifecycle",
   /** Emitted once, on the first write rejected because storage is full. */
   STORAGE_FULL: "storage.full"
 };
@@ -104,21 +114,27 @@ var SAFE_NUMBER_FIELDS = /* @__PURE__ */ new Set([
   "fetched",
   "pages",
   "lagMs",
-  "pendingCleared"
+  "pendingCleared",
+  "partitions",
+  "remaining",
+  "expiryMs"
 ]);
-var SAFE_BOOLEAN_FIELDS = /* @__PURE__ */ new Set(["authenticated", "ok", "persisted"]);
+var SAFE_BOOLEAN_FIELDS = /* @__PURE__ */ new Set(["authenticated", "ok", "persisted", "purgePending"]);
 var SAFE_REPLICATION_FIELDS = {
   source: ["replica", "network", "none"],
-  reason: ["hit", "absent", "deleted", "content_missing", "coverage_incomplete", "not_covered", "pending_write", "grant_missing", "grant_expired", "grant_revoked", "grant_not_yet_valid", "stale", "replica_error", "runtime_unsupported", "replica_unavailable", "unsupported_option", "network_cursor", "cursor_restart", "aborted", "REPLICA_BEHIND_OWN_WRITES", "REPLICA_UNPROVEN_SINCE_START", "NETWORK_REQUESTED"],
+  reason: ["hit", "absent", "deleted", "content_missing", "coverage_incomplete", "not_covered", "pending_write", "grant_missing", "grant_expired", "grant_revoked", "grant_not_yet_valid", "stale", "replica_error", "runtime_unsupported", "replica_unavailable", "unsupported_option", "network_cursor", "cursor_restart", "aborted", "REPLICA_BEHIND_OWN_WRITES", "REPLICA_UNPROVEN_SINCE_START", "NETWORK_REQUESTED", "replica_gated", "sign_out", "account_switch", "consent_expired", "startup"],
   op: ["get", "list", "put", "delete", "batchPut"],
-  trigger: ["start", "interval", "stale_read", "manual"],
+  trigger: ["start", "interval", "stale_read", "manual", "peer"],
+  origin: ["peer"],
   outcome: ["found", "not_found", "error", "committed", "failed", "ambiguous", "ok", "busy", "aborted"],
-  class: ["offline", "authority", "storage", "node"],
-  state: ["opened", "grant_installed", "grant_missing", "runtime_unsupported", "unavailable", "revoked", "recreated", "purged", "purge_failed", "pending_store_error", "pinned", "pending_cleared", "closed", "idle", "ready"],
+  class: ["offline", "authority", "storage", "node", "lifecycle"],
+  state: ["opened", "grant_installed", "grant_missing", "runtime_unsupported", "unavailable", "revoked", "recreated", "purged", "purge_failed", "pending_store_error", "pinned", "pending_cleared", "closed", "idle", "ready", "gated"],
+  action: ["minted", "renewed", "renewal_refused", "renewal_deferred", "capped", "expired", "consent_deadline_reached", "denied", "deny_stale", "deny_failed", "database_deleted", "marker_set", "marker_cleared", "unguarded", "drained", "erased", "erase_failed", "activation_blocked", "activated", "recovered"],
+  gate: ["not_established", "stamp_stale", "principal_mismatch", "purge_pending", "logout_pending", "gate_unavailable"],
   kind: ["value", "missing_local", "extra_local", "keys", "order"],
   coverage: ["empty", "bootstrapping", "complete"],
   authority: ["valid", "expired", "revoked", "not-yet-valid"],
-  code: ["NETWORK_ERROR", "TIMEOUT", "ABORTED", "REPLICA_BUSY", "REPLICA_BEHIND_OWN_WRITES", "REPLICA_UNPROVEN_SINCE_START", "NETWORK_REQUESTED", "INTEGRITY_ERROR", "STORAGE_ERROR", "REPLICA_CLOSED", "RUNTIME_UNSUPPORTED", "GRANT_EXPIRED", "GRANT_REVOKED", "GRANT_NOT_YET_VALID", "GRANT_MISSING", "GRANT_INVALID", "SOURCE_CHANGED", "PROTOCOL_ERROR", "SCOPE_VIOLATION", "NODE_ERROR", "CONTENT_MISMATCH", "STORAGE_FULL"],
+  code: ["NETWORK_ERROR", "TIMEOUT", "ABORTED", "REPLICA_BUSY", "REPLICA_BEHIND_OWN_WRITES", "REPLICA_UNPROVEN_SINCE_START", "NETWORK_REQUESTED", "INTEGRITY_ERROR", "STORAGE_ERROR", "REPLICA_CLOSED", "RUNTIME_UNSUPPORTED", "GRANT_EXPIRED", "GRANT_REVOKED", "GRANT_NOT_YET_VALID", "GRANT_MISSING", "GRANT_INVALID", "SOURCE_CHANGED", "PROTOCOL_ERROR", "SCOPE_VIOLATION", "NODE_ERROR", "CONTENT_MISMATCH", "STORAGE_FULL", "REPLICA_GATED", "RESET_REQUIRED", "STORAGE_BUDGET", "CONSENT_EXPIRED"],
   pendingState: ["in_flight", "committed", "ambiguous"],
   strategy: ["session", "minted", "installed"],
   verify: ["match", "diverged", "error", "aborted"]
@@ -950,6 +966,42 @@ var ServiceContext = class {
   }
 };
 
+// src/responseErrors.ts
+function parseServiceErrorBody(errorText) {
+  try {
+    return JSON.parse(errorText);
+  } catch {
+    return {};
+  }
+}
+function formatServiceResponseError(serviceLabel, operation, status, errorText, parsed) {
+  if (parsed.message) {
+    return compactMessage(parsed.message);
+  }
+  if (looksLikeHtml(errorText)) {
+    if (status === 524 || /524\s*[:-]/i.test(errorText) || /a timeout occurred/i.test(errorText)) {
+      return `${serviceLabel} ${operation} failed: upstream request timed out. Please retry.`;
+    }
+    return `${serviceLabel} ${operation} failed: upstream service returned an HTML error page (${status}).`;
+  }
+  return `${serviceLabel} ${operation} failed: ${status} - ${compactMessage(errorText)}`;
+}
+function responseErrorMeta(status, statusText, errorText) {
+  const meta = { status, statusText };
+  const snippet = compactMessage(errorText);
+  if (snippet) {
+    meta.responseSnippet = snippet.slice(0, 300);
+  }
+  return meta;
+}
+function looksLikeHtml(text) {
+  return /<!doctype html/i.test(text) || /<html[\s>]/i.test(text);
+}
+function compactMessage(message) {
+  const compact = message.replace(/\s+/g, " ").trim();
+  return compact.length > 500 ? `${compact.slice(0, 500)}...` : compact;
+}
+
 // src/errors.ts
 import { CAPABILITY_REGISTRY } from "@tinycloud/bootstrap";
 
@@ -1109,6 +1161,30 @@ function networkError(service, message, cause) {
     cause
   };
 }
+function nodeRetryError(service, message, response, errorText) {
+  const body = errorText.trim();
+  const [, token, stage] = /^([a-z_]+)(?::\s*([a-z_]+):)?/.exec(body) ?? [];
+  let code;
+  if (response.status === 503 && (token === "sql_busy" || token === "unavailable_retryable")) {
+    code = ErrorCodes.NODE_BUSY;
+  } else if (response.status === 503 && token === "request_timeout") {
+    code = ErrorCodes.REQUEST_TIMEOUT;
+  } else if (response.status === 500 && token === "outcome_unknown") {
+    code = ErrorCodes.OUTCOME_UNKNOWN;
+  } else {
+    return void 0;
+  }
+  const retryable = code !== ErrorCodes.OUTCOME_UNKNOWN;
+  const retryAfter = response.headers.get("retry-after")?.trim();
+  return serviceError(code, message, service, {
+    meta: {
+      ...responseErrorMeta(response.status, response.statusText, errorText),
+      retryable,
+      ...token === "sql_busy" && stage ? { stage } : {},
+      ...retryable && retryAfter && /^\d{1,9}$/.test(retryAfter) ? { retryAfterMs: Number(retryAfter) * 1e3 } : {}
+    }
+  });
+}
 var RequestTimeoutError = class extends Error {
   constructor(timeoutMs) {
     super(`Request timed out after ${timeoutMs}ms.`);
@@ -2447,9 +2523,12 @@ var KVService = class extends BaseService {
           { meta: { status: response.status, statusText: response.statusText } }
         ));
       }
+      const message = `Failed to get key ${JSON.stringify(key)}: ${response.status} - ${errorText}`;
+      const retryError = nodeRetryError("kv", message, response, errorText);
+      if (retryError) return err(retryError);
       return err(serviceError(
         ErrorCodes.NETWORK_ERROR,
-        `Failed to get key ${JSON.stringify(key)}: ${response.status} - ${errorText}`,
+        message,
         "kv",
         { meta: { status: response.status, statusText: response.statusText } }
       ));
@@ -2531,19 +2610,14 @@ var KVService = class extends BaseService {
           { meta: { status: response.status, statusText: response.statusText } }
         ));
       }
-      if (response.status === 503 && (options?.ifMatch !== void 0 || options?.ifNoneMatch !== void 0)) {
-        return err(serviceError(
-          ErrorCodes.KV_CONFLICT,
-          `Concurrent KV update conflicted for key ${JSON.stringify(key)}`,
-          "kv",
-          { meta: { status: response.status, statusText: response.statusText } }
-        ));
-      }
+      const message = `Failed to put key ${JSON.stringify(key)}: ${response.status} - ${errorText}`;
+      const retryError = nodeRetryError("kv", message, response, errorText);
+      if (retryError) return err(retryError);
       const quotaError = this.handleQuotaErrorResponse(response, errorText, key);
       if (quotaError) return quotaError;
       return err(serviceError(
         ErrorCodes.KV_WRITE_FAILED,
-        `Failed to put key ${JSON.stringify(key)}: ${response.status} - ${errorText}`,
+        message,
         "kv",
         { meta: { status: response.status, statusText: response.statusText } }
       ));
@@ -2843,9 +2917,12 @@ var KVService = class extends BaseService {
         );
       }
       const errorText = await response.text();
+      const message = `Failed to list keys: ${response.status} - ${errorText}`;
+      const retryError = nodeRetryError("kv", message, response, errorText);
+      if (retryError) return err(retryError);
       return err(serviceError(
         ErrorCodes.NETWORK_ERROR,
-        `Failed to list keys: ${response.status} - ${errorText}`,
+        message,
         "kv",
         { meta: { status: response.status, statusText: response.statusText } }
       ));
@@ -3096,17 +3173,12 @@ var KVService = class extends BaseService {
           { meta: { status: response.status, statusText: response.statusText } }
         ));
       }
-      if (response.status === 503 && options?.ifMatch !== void 0) {
-        return err(serviceError(
-          ErrorCodes.KV_CONFLICT,
-          `Concurrent KV delete conflicted for key ${JSON.stringify(key)}`,
-          "kv",
-          { meta: { status: response.status, statusText: response.statusText } }
-        ));
-      }
+      const message = `Failed to delete key ${JSON.stringify(key)}: ${response.status} - ${errorText}`;
+      const retryError = nodeRetryError("kv", message, response, errorText);
+      if (retryError) return err(retryError);
       return err(serviceError(
         ErrorCodes.NETWORK_ERROR,
-        `Failed to delete key ${JSON.stringify(key)}: ${response.status} - ${errorText}`,
+        message,
         "kv",
         { meta: { status: response.status, statusText: response.statusText } }
       ));
@@ -3147,10 +3219,13 @@ var KVService = class extends BaseService {
             return await this.classifyNotFound(response, key);
           }
           const errorText = await response.text();
+          const message = `Failed to get metadata for key ${JSON.stringify(key)}: ${response.status} - ${errorText}`;
+          const retryError = nodeRetryError("kv", message, response, errorText);
+          if (retryError) return err(retryError);
           return err(
             serviceError(
               ErrorCodes.NETWORK_ERROR,
-              `Failed to get metadata for key ${JSON.stringify(key)}: ${response.status} - ${errorText}`,
+              message,
               "kv",
               { meta: { status: response.status, statusText: response.statusText } }
             )
@@ -3342,42 +3417,6 @@ function requiresSecretsOptIn(space, prefix) {
   return prefix.split("/", 1)[0] === "vault";
 }
 
-// src/responseErrors.ts
-function parseServiceErrorBody(errorText) {
-  try {
-    return JSON.parse(errorText);
-  } catch {
-    return {};
-  }
-}
-function formatServiceResponseError(serviceLabel, operation, status, errorText, parsed) {
-  if (parsed.message) {
-    return compactMessage(parsed.message);
-  }
-  if (looksLikeHtml(errorText)) {
-    if (status === 524 || /524\s*[:-]/i.test(errorText) || /a timeout occurred/i.test(errorText)) {
-      return `${serviceLabel} ${operation} failed: upstream request timed out. Please retry.`;
-    }
-    return `${serviceLabel} ${operation} failed: upstream service returned an HTML error page (${status}).`;
-  }
-  return `${serviceLabel} ${operation} failed: ${status} - ${compactMessage(errorText)}`;
-}
-function responseErrorMeta(status, statusText, errorText) {
-  const meta = { status, statusText };
-  const snippet = compactMessage(errorText);
-  if (snippet) {
-    meta.responseSnippet = snippet.slice(0, 300);
-  }
-  return meta;
-}
-function looksLikeHtml(text) {
-  return /<!doctype html/i.test(text) || /<html[\s>]/i.test(text);
-}
-function compactMessage(message) {
-  const compact = message.replace(/\s+/g, " ").trim();
-  return compact.length > 500 ? `${compact.slice(0, 500)}...` : compact;
-}
-
 // src/sql/SQLMigrations.ts
 var SQLMigrations = class {
   constructor(service, dbName) {
@@ -3793,6 +3832,8 @@ var SQLService = class extends BaseService {
     if (response.status === 413 && parseStorageRejection(errorText)) {
       return err(storageRejectionError("sql", 413, meta, errorText));
     }
+    const retryError = nodeRetryError("sql", `SQL ${operation} failed: ${response.status} - ${errorText}`, response, errorText);
+    if (retryError) return err(retryError);
     const errorBody = parseServiceErrorBody(errorText);
     const errorCode = this.mapHttpStatusToErrorCode(
       response.status,
@@ -4262,6 +4303,8 @@ var DuckDbService = class extends BaseService {
     if (response.status === 413 && parseStorageRejection(errorText)) {
       return err(storageRejectionError("duckdb", 413, meta, errorText));
     }
+    const retryError = nodeRetryError("duckdb", `DuckDB ${operation} failed: ${response.status} - ${errorText}`, response, errorText);
+    if (retryError) return err(retryError);
     const errorBody = parseServiceErrorBody(errorText);
     const errorCode = this.mapHttpStatusToErrorCode(
       response.status,
@@ -5469,6 +5512,116 @@ var TinyCloudQuota = class {
   }
 };
 
+// src/encryption/canonical.ts
+function canonicalize(value) {
+  if (value === void 0) {
+    return "";
+  }
+  return stringify(value);
+}
+function stringify(value) {
+  if (value === null) return "null";
+  switch (typeof value) {
+    case "boolean":
+    case "number":
+      return JSON.stringify(value);
+    case "string":
+      return JSON.stringify(value);
+    case "object": {
+      if (Array.isArray(value)) {
+        return `[${value.map(stringify).join(",")}]`;
+      }
+      const keys = Object.keys(value).sort();
+      const parts = [];
+      for (const k of keys) {
+        const v = value[k];
+        if (v === void 0) continue;
+        parts.push(`${JSON.stringify(k)}:${stringify(v)}`);
+      }
+      return `{${parts.join(",")}}`;
+    }
+    default:
+      throw new TypeError(
+        `canonicalize: unsupported value type ${typeof value}`
+      );
+  }
+}
+var HEX = "0123456789abcdef";
+function hexEncode(bytes) {
+  let out = "";
+  for (let i = 0; i < bytes.length; i++) {
+    const b = bytes[i];
+    out += HEX[b >> 4 & 15] + HEX[b & 15];
+  }
+  return out;
+}
+function hexDecode(hex) {
+  if (hex.length % 2 !== 0) {
+    throw new Error("hex string must have even length");
+  }
+  const out = new Uint8Array(hex.length / 2);
+  for (let i = 0; i < out.length; i++) {
+    const hi = parseInt(hex[i * 2], 16);
+    const lo = parseInt(hex[i * 2 + 1], 16);
+    if (Number.isNaN(hi) || Number.isNaN(lo)) {
+      throw new Error("invalid hex character");
+    }
+    out[i] = hi << 4 | lo;
+  }
+  return out;
+}
+function base64Encode(bytes) {
+  const chars = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/";
+  let out = "";
+  for (let i = 0; i < bytes.length; i += 3) {
+    const b0 = bytes[i];
+    const b1 = i + 1 < bytes.length ? bytes[i + 1] : 0;
+    const b2 = i + 2 < bytes.length ? bytes[i + 2] : 0;
+    out += chars[b0 >> 2 & 63];
+    out += chars[(b0 << 4 | b1 >> 4) & 63];
+    out += i + 1 < bytes.length ? chars[(b1 << 2 | b2 >> 6) & 63] : "=";
+    out += i + 2 < bytes.length ? chars[b2 & 63] : "=";
+  }
+  return out;
+}
+function base64Decode(s) {
+  const clean = s.replace(/[^A-Za-z0-9+/=]/g, "");
+  const len = clean.length;
+  if (len % 4 !== 0) {
+    throw new Error("invalid base64 input");
+  }
+  const padding = clean.endsWith("==") ? 2 : clean.endsWith("=") ? 1 : 0;
+  const outLen = len / 4 * 3 - padding;
+  const out = new Uint8Array(outLen);
+  const lookup = {};
+  const chars = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/";
+  for (let i = 0; i < chars.length; i++) lookup[chars[i]] = i;
+  let outIdx = 0;
+  for (let i = 0; i < len; i += 4) {
+    const v0 = lookup[clean[i]] ?? 0;
+    const v1 = lookup[clean[i + 1]] ?? 0;
+    const v2 = clean[i + 2] === "=" ? 0 : lookup[clean[i + 2]] ?? 0;
+    const v3 = clean[i + 3] === "=" ? 0 : lookup[clean[i + 3]] ?? 0;
+    const b0 = v0 << 2 | v1 >> 4;
+    const b1 = (v1 & 15) << 4 | v2 >> 2;
+    const b2 = (v2 & 3) << 6 | v3;
+    if (outIdx < outLen) out[outIdx++] = b0;
+    if (outIdx < outLen) out[outIdx++] = b1;
+    if (outIdx < outLen) out[outIdx++] = b2;
+  }
+  return out;
+}
+function utf8Encode(s) {
+  return new TextEncoder().encode(s);
+}
+function utf8Decode(b) {
+  return new TextDecoder().decode(b);
+}
+function canonicalHashHex(sha256, value) {
+  const canonical = canonicalize(value);
+  return hexEncode(sha256(utf8Encode(canonical)));
+}
+
 // src/vault/types.ts
 var VaultPublicSpaceKVActions = [
   "tinycloud.kv/get",
@@ -5638,7 +5791,7 @@ function toBytes(str) {
 function fromBytes(bytes) {
   return new TextDecoder().decode(bytes);
 }
-function hexEncode(bytes) {
+function hexEncode2(bytes) {
   return Array.from(bytes).map((b) => b.toString(16).padStart(2, "0")).join("");
 }
 function concatBytes(...arrays) {
@@ -5651,14 +5804,14 @@ function concatBytes(...arrays) {
   }
   return result;
 }
-function base64Encode(bytes) {
+function base64Encode2(bytes) {
   let binary = "";
   for (let i = 0; i < bytes.length; i++) {
     binary += String.fromCharCode(bytes[i]);
   }
   return btoa(binary);
 }
-function base64Decode(str) {
+function base64Decode2(str) {
   const binary = atob(str);
   const bytes = new Uint8Array(binary.length);
   for (let i = 0; i < binary.length; i++) {
@@ -5700,6 +5853,11 @@ function defaultVaultMessage(input) {
       return input.message;
     case "PERMISSION_DENIED":
       return input.message;
+    case "AAD_MISMATCH":
+    case "ETAG_MISMATCH":
+    case "INVALID_ETAG":
+    case "OUTCOME_UNKNOWN":
+    case "NODE_BUSY":
     case "STORAGE_QUOTA_EXCEEDED":
     case "STORAGE_LIMIT_REACHED":
       return input.message;
@@ -5722,6 +5880,37 @@ function typedKvCause(error) {
     ...error.cause !== void 0 ? { cause: error.cause } : {}
   });
 }
+function canonicalAadSpaceId(spaceId) {
+  return spaceId.replace(/0x[0-9a-fA-F]{40}/g, (address) => address.toLowerCase());
+}
+function checkEnvelopeAad(value, spaceId, key) {
+  const e = value;
+  if (typeof e !== "object" || e === null || Array.isArray(e) || !["networkId", "alg", "encryptedSymmetricKey", "encryptedSymmetricKeyHash", "ciphertext"].every(
+    (field) => typeof e[field] === "string" && e[field] !== ""
+  ) || !Number.isInteger(e.keyVersion) || e.aad !== void 0 && typeof e.aad !== "string") {
+    return "corrupt";
+  }
+  let aad = "";
+  try {
+    if (typeof e.aad === "string") aad = fromBytes(base64Decode(e.aad));
+  } catch {
+  }
+  const suffix = `:${key}`;
+  return aad.endsWith(suffix) && canonicalAadSpaceId(aad.slice(0, -suffix.length)) === canonicalAadSpaceId(`tinycloud.vault:${spaceId}`) ? "ok" : "mismatch";
+}
+var AMBIGUOUS_WRITE_STATUSES = [500, 502, 503, 504, 520, 522, 524];
+function ifMatchWriteError(key, error) {
+  const status = error.meta?.status;
+  const code = error.code === ErrorCodes.KV_PRECONDITION_FAILED ? "ETAG_MISMATCH" : error.code === ErrorCodes.KV_WRITE_FAILED && status === 400 ? "INVALID_ETAG" : error.code === ErrorCodes.OUTCOME_UNKNOWN || error.code === ErrorCodes.KV_WRITE_FAILED && typeof status === "number" && AMBIGUOUS_WRITE_STATUSES.includes(status) || (error.code === ErrorCodes.NETWORK_ERROR || error.code === ErrorCodes.TIMEOUT) && status === void 0 && error.meta?.requestMayHaveDispatched !== false ? "OUTCOME_UNKNOWN" : error.code === ErrorCodes.NODE_BUSY || error.code === ErrorCodes.REQUEST_TIMEOUT ? "NODE_BUSY" : void 0;
+  if (code === void 0) return void 0;
+  return vaultError({
+    code,
+    key,
+    message: error.message,
+    ...error.meta !== void 0 ? { meta: error.meta } : {},
+    cause: typedKvCause(error)
+  });
+}
 function kvWriteError(context, error) {
   if (error.code === ErrorCodes.STORAGE_QUOTA_EXCEEDED || error.code === ErrorCodes.STORAGE_LIMIT_REACHED) {
     return vaultError({ code: error.code, message: error.message, meta: error.meta });
@@ -5908,7 +6097,7 @@ var DataVaultService = class extends BaseService {
         }
         if (existingPubKey) {
           this.encryptionIdentity = {
-            publicKey: base64Decode(existingPubKey),
+            publicKey: base64Decode2(existingPubKey),
             privateKey: new Uint8Array(0)
             // private key not available without signing
           };
@@ -5933,7 +6122,7 @@ var DataVaultService = class extends BaseService {
           );
           this.encryptionIdentity = this.crypto.x25519FromSeed(seed);
           try {
-            const pubKeyB64 = base64Encode(this.encryptionIdentity.publicKey);
+            const pubKeyB64 = base64Encode2(this.encryptionIdentity.publicKey);
             await this.tc.ensurePublicSpace();
             await this.tc.publicKV.put(".well-known/vault-pubkey", pubKeyB64);
             await this.tc.publicKV.put(".well-known/vault-version", CURRENT_VAULT_VERSION);
@@ -5999,6 +6188,21 @@ var DataVaultService = class extends BaseService {
         message: "Authentication required"
       });
     }
+    if (options?.ifMatch !== void 0) {
+      if (options.ifNoneMatch !== void 0) {
+        return vaultError({
+          code: "STORAGE_ERROR",
+          cause: new Error("ifMatch cannot be combined with ifNoneMatch")
+        });
+      }
+      if (!/^"[^"\s]+"$/.test(options.ifMatch)) {
+        return vaultError({
+          code: "INVALID_ETAG",
+          key,
+          message: options.ifMatch.startsWith("W/") ? 'ifMatch is a weak etag (W/"..."): the node only issues strong etags, so the etag was weakened in transit (a proxy or CDN rewrote it). Read it from a connection that preserves strong ETags' : "ifMatch must be the strong, quoted ETag returned by a network read (VaultEntry.etag), passed exactly as returned"
+        });
+      }
+    }
     try {
       const { plaintext, contentType } = this.serializeValue(value, options);
       const metadata = {
@@ -6021,7 +6225,8 @@ var DataVaultService = class extends BaseService {
       }
       const valuePath = `vault/${key}`;
       const valueBody = JSON.stringify(envelopeResult.data);
-      const valuePutResult = options?.ifNoneMatch !== void 0 ? await this.tc.kv.put(valuePath, valueBody, { ifNoneMatch: options.ifNoneMatch }) : await this.tc.kv.put(valuePath, valueBody);
+      const putOptions = options?.ifMatch !== void 0 ? { ifMatch: options.ifMatch } : options?.ifNoneMatch !== void 0 ? { ifNoneMatch: options.ifNoneMatch } : void 0;
+      const valuePutResult = putOptions !== void 0 ? await this.tc.kv.put(valuePath, valueBody, putOptions) : await this.tc.kv.put(valuePath, valueBody);
       if (!valuePutResult.ok) {
         if (options?.ifNoneMatch !== void 0 && valuePutResult.error.code === ErrorCodes.KV_PRECONDITION_FAILED) {
           return vaultError({
@@ -6031,6 +6236,10 @@ var DataVaultService = class extends BaseService {
             cause: typedKvCause(valuePutResult.error)
           });
         }
+        if (options?.ifMatch !== void 0) {
+          const classified = ifMatchWriteError(key, valuePutResult.error);
+          if (classified !== void 0) return classified;
+        }
         return kvWriteError("Failed to store encrypted value", valuePutResult.error);
       }
       return { ok: true, data: void 0 };
@@ -6065,6 +6274,19 @@ var DataVaultService = class extends BaseService {
       }
       const rawEnvelope = unwrapKVData(valueResult.data);
       const envelope = typeof rawEnvelope === "string" ? JSON.parse(rawEnvelope) : rawEnvelope;
+      if (options?.expectAad === true) {
+        const verdict = checkEnvelopeAad(envelope, this.vaultConfig.spaceId, key);
+        if (verdict === "corrupt") {
+          return vaultError({ code: "DECRYPTION_FAILED", message: "envelope is malformed" });
+        }
+        if (verdict === "mismatch") {
+          return vaultError({
+            code: "AAD_MISMATCH",
+            key,
+            message: `Envelope at ${key} is not bound to this space and key`
+          });
+        }
+      }
       const proof = await this.decryptCapabilityProof();
       const plaintextResult = await config.service.decryptEnvelope(envelope, proof);
       if (!plaintextResult.ok) {
@@ -6081,7 +6303,11 @@ var DataVaultService = class extends BaseService {
         contentType,
         options
       );
-      return { ok: true, data: { value, metadata, keyId } };
+      const etag = options?.source === "network" ? valueResult.data.headers?.etag : void 0;
+      return {
+        ok: true,
+        data: { value, metadata, keyId, ...etag === void 0 ? {} : { etag } }
+      };
     } catch (error) {
       return vaultError({
         code: "STORAGE_ERROR",
@@ -6127,6 +6353,12 @@ var DataVaultService = class extends BaseService {
     } catch {
       return { status: "corrupt_envelope" };
     }
+    if (options?.expectAad === true) {
+      const verdict = checkEnvelopeAad(envelope, this.vaultConfig.spaceId, key);
+      if (verdict !== "ok") {
+        return { status: verdict === "corrupt" ? "corrupt_envelope" : "aad_mismatch" };
+      }
+    }
     let plaintextResult;
     try {
       const proof = await this.decryptCapabilityProof();
@@ -6158,7 +6390,11 @@ var DataVaultService = class extends BaseService {
         contentType,
         options
       );
-      return { status: "ok", entry: { value, metadata, keyId } };
+      const etag = valueResult.data.headers?.etag;
+      return {
+        status: "ok",
+        entry: { value, metadata, keyId, ...etag === void 0 ? {} : { etag } }
+      };
     } catch {
       return { status: "invalid_payload" };
     }
@@ -6208,6 +6444,14 @@ var DataVaultService = class extends BaseService {
           )
         });
       }
+      if (options?.ifMatch !== void 0) {
+        return vaultError({
+          code: "STORAGE_ERROR",
+          cause: new Error(
+            "ifMatch is only supported by network-encrypted vaults"
+          )
+        });
+      }
       if (!this._isUnlocked || !this.masterKey) {
         return vaultError({
           code: "VAULT_LOCKED",
@@ -6233,7 +6477,7 @@ var DataVaultService = class extends BaseService {
         }
         const contentType = options?.contentType ?? (value instanceof Uint8Array ? "application/octet-stream" : "application/json");
         const entryKey = this.crypto.randomBytes(32);
-        const keyId = hexEncode(this.crypto.sha256(entryKey)).slice(0, 16);
+        const keyId = hexEncode2(this.crypto.sha256(entryKey)).slice(0, 16);
         const encrypted = this.crypto.encrypt(entryKey, plaintext);
         const keyBlob = this.crypto.encrypt(this.masterKey, entryKey);
         const metadata = {
@@ -6251,7 +6495,7 @@ var DataVaultService = class extends BaseService {
           ...metadata
         });
         const keyPayload = JSON.stringify({
-          key: base64Encode(keyBlob),
+          key: base64Encode2(keyBlob),
           metadata: keyMetadata
         });
         const keyPutResult = await this.tc.kv.put(
@@ -6262,7 +6506,7 @@ var DataVaultService = class extends BaseService {
           return kvWriteError("Failed to store key blob", keyPutResult.error);
         }
         const valuePayload = JSON.stringify({
-          data: base64Encode(encrypted),
+          data: base64Encode2(encrypted),
           metadata
         });
         const valuePutResult = await this.tc.kv.put(
@@ -6293,6 +6537,12 @@ var DataVaultService = class extends BaseService {
       if (this.usesNetworkEncryption) {
         return this.getNetworkEncrypted(key, options);
       }
+      if (options?.expectAad === true) {
+        return vaultError({
+          code: "STORAGE_ERROR",
+          cause: new Error("expectAad is only supported by network-encrypted vaults")
+        });
+      }
       if (!this._isUnlocked || !this.masterKey) {
         return vaultError({
           code: "VAULT_LOCKED",
@@ -6314,7 +6564,7 @@ var DataVaultService = class extends BaseService {
           return vaultError({ code: "KEY_NOT_FOUND", key });
         }
         const keyEnvelope = JSON.parse(keyResult.data.data);
-        const keyBlobBytes = base64Decode(keyEnvelope.key);
+        const keyBlobBytes = base64Decode2(keyEnvelope.key);
         const entryKey = this.crypto.decrypt(this.masterKey, keyBlobBytes);
         const valueResult = await this.tc.kv.get(`vault/${key}`, {
           raw: true,
@@ -6324,7 +6574,7 @@ var DataVaultService = class extends BaseService {
           return vaultError({ code: "KEY_NOT_FOUND", key });
         }
         const valueEnvelope = JSON.parse(valueResult.data.data);
-        const encryptedBytes = base64Decode(valueEnvelope.data);
+        const encryptedBytes = base64Decode2(valueEnvelope.data);
         const plaintext = this.crypto.decrypt(entryKey, encryptedBytes);
         const metadata = valueEnvelope.metadata ?? {};
         const contentType = metadata[VaultHeaders.CONTENT_TYPE] ?? "application/json";
@@ -6572,7 +6822,7 @@ var DataVaultService = class extends BaseService {
           return vaultError({ code: "KEY_NOT_FOUND", key });
         }
         const keyEnvelope = JSON.parse(keyResult.data.data);
-        const keyBlobBytes = base64Decode(keyEnvelope.key);
+        const keyBlobBytes = base64Decode2(keyEnvelope.key);
         const entryKey = this.crypto.decrypt(this.masterKey, keyBlobBytes);
         const ephemeralSeed = this.crypto.randomBytes(32);
         const ephemeralKeyPair = this.crypto.x25519FromSeed(ephemeralSeed);
@@ -6591,7 +6841,7 @@ var DataVaultService = class extends BaseService {
           encryptedGrant
         );
         const grantPayload = JSON.stringify({
-          grant: base64Encode(grantBlob),
+          grant: base64Encode2(grantBlob),
           spaceId: this.vaultConfig.spaceId,
           metadata: {
             [VaultHeaders.GRANT_VERSION]: "1",
@@ -6631,6 +6881,14 @@ var DataVaultService = class extends BaseService {
    */
   async getShared(grantorDID, key, options) {
     return this.withTelemetry("getShared", key, async () => {
+      if (options?.expectAad === true) {
+        return vaultError({
+          code: "STORAGE_ERROR",
+          cause: new Error(
+            "expectAad is not supported by getShared: the AAD binds the grantor's space, which this vault does not know"
+          )
+        });
+      }
       if (this.usesNetworkEncryption) {
         const grantorKV = options?.kv;
         if (!grantorKV) {
@@ -6725,7 +6983,7 @@ var DataVaultService = class extends BaseService {
           });
         }
         const grantEnvelope = typeof grantResult.data?.data === "string" ? JSON.parse(grantResult.data.data) : grantResult.data?.data;
-        const grantBlobBytes = base64Decode(grantEnvelope.grant);
+        const grantBlobBytes = base64Decode2(grantEnvelope.grant);
         const ephemeralPubKey = grantBlobBytes.slice(0, 32);
         const encryptedGrant = grantBlobBytes.slice(32);
         const sharedSecret = this.crypto.x25519Dh(
@@ -6748,7 +7006,7 @@ var DataVaultService = class extends BaseService {
           });
         }
         const valueEnvelope = typeof valueResult.data?.data === "string" ? JSON.parse(valueResult.data.data) : valueResult.data?.data;
-        const encryptedBytes = base64Decode(valueEnvelope.data);
+        const encryptedBytes = base64Decode2(valueEnvelope.data);
         const plaintext = this.crypto.decrypt(entryKey, encryptedBytes);
         const metadata = valueEnvelope.metadata ?? {};
         const contentType = metadata[VaultHeaders.CONTENT_TYPE] ?? "application/json";
@@ -6802,7 +7060,7 @@ var DataVaultService = class extends BaseService {
       if (!result.ok) {
         return vaultError({ code: "PUBLIC_KEY_NOT_FOUND", did });
       }
-      const pubKeyBytes = base64Decode(result.data);
+      const pubKeyBytes = base64Decode2(result.data);
       return { ok: true, data: pubKeyBytes };
     } catch (error) {
       return vaultError({ code: "PUBLIC_KEY_NOT_FOUND", did });
@@ -6921,7 +7179,7 @@ var DataVaultService = class extends BaseService {
         }
         const currentEntry = getResult.data;
         const newEntryKey = this.crypto.randomBytes(32);
-        const newKeyId = hexEncode(this.crypto.sha256(newEntryKey)).slice(
+        const newKeyId = hexEncode2(this.crypto.sha256(newEntryKey)).slice(
           0,
           16
         );
@@ -6938,7 +7196,7 @@ var DataVaultService = class extends BaseService {
           [VaultHeaders.KEY_ID]: newKeyId
         };
         const keyPayload = JSON.stringify({
-          key: base64Encode(newKeyBlob),
+          key: base64Encode2(newKeyBlob),
           metadata: JSON.stringify({
             keyId: newKeyId,
             ...metadata
@@ -6952,7 +7210,7 @@ var DataVaultService = class extends BaseService {
           return kvWriteError("Failed to store rotated key blob", keyPutResult.error);
         }
         const valuePayload = JSON.stringify({
-          data: base64Encode(encrypted),
+          data: base64Encode2(encrypted),
           metadata
         });
         const valuePutResult = await this.tc.kv.put(
@@ -7244,116 +7502,6 @@ var SecretsService = class {
   }
 };
 
-// src/encryption/canonical.ts
-function canonicalize(value) {
-  if (value === void 0) {
-    return "";
-  }
-  return stringify(value);
-}
-function stringify(value) {
-  if (value === null) return "null";
-  switch (typeof value) {
-    case "boolean":
-    case "number":
-      return JSON.stringify(value);
-    case "string":
-      return JSON.stringify(value);
-    case "object": {
-      if (Array.isArray(value)) {
-        return `[${value.map(stringify).join(",")}]`;
-      }
-      const keys = Object.keys(value).sort();
-      const parts = [];
-      for (const k of keys) {
-        const v = value[k];
-        if (v === void 0) continue;
-        parts.push(`${JSON.stringify(k)}:${stringify(v)}`);
-      }
-      return `{${parts.join(",")}}`;
-    }
-    default:
-      throw new TypeError(
-        `canonicalize: unsupported value type ${typeof value}`
-      );
-  }
-}
-var HEX = "0123456789abcdef";
-function hexEncode2(bytes) {
-  let out = "";
-  for (let i = 0; i < bytes.length; i++) {
-    const b = bytes[i];
-    out += HEX[b >> 4 & 15] + HEX[b & 15];
-  }
-  return out;
-}
-function hexDecode(hex) {
-  if (hex.length % 2 !== 0) {
-    throw new Error("hex string must have even length");
-  }
-  const out = new Uint8Array(hex.length / 2);
-  for (let i = 0; i < out.length; i++) {
-    const hi = parseInt(hex[i * 2], 16);
-    const lo = parseInt(hex[i * 2 + 1], 16);
-    if (Number.isNaN(hi) || Number.isNaN(lo)) {
-      throw new Error("invalid hex character");
-    }
-    out[i] = hi << 4 | lo;
-  }
-  return out;
-}
-function base64Encode2(bytes) {
-  const chars = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/";
-  let out = "";
-  for (let i = 0; i < bytes.length; i += 3) {
-    const b0 = bytes[i];
-    const b1 = i + 1 < bytes.length ? bytes[i + 1] : 0;
-    const b2 = i + 2 < bytes.length ? bytes[i + 2] : 0;
-    out += chars[b0 >> 2 & 63];
-    out += chars[(b0 << 4 | b1 >> 4) & 63];
-    out += i + 1 < bytes.length ? chars[(b1 << 2 | b2 >> 6) & 63] : "=";
-    out += i + 2 < bytes.length ? chars[b2 & 63] : "=";
-  }
-  return out;
-}
-function base64Decode2(s) {
-  const clean = s.replace(/[^A-Za-z0-9+/=]/g, "");
-  const len = clean.length;
-  if (len % 4 !== 0) {
-    throw new Error("invalid base64 input");
-  }
-  const padding = clean.endsWith("==") ? 2 : clean.endsWith("=") ? 1 : 0;
-  const outLen = len / 4 * 3 - padding;
-  const out = new Uint8Array(outLen);
-  const lookup = {};
-  const chars = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/";
-  for (let i = 0; i < chars.length; i++) lookup[chars[i]] = i;
-  let outIdx = 0;
-  for (let i = 0; i < len; i += 4) {
-    const v0 = lookup[clean[i]] ?? 0;
-    const v1 = lookup[clean[i + 1]] ?? 0;
-    const v2 = clean[i + 2] === "=" ? 0 : lookup[clean[i + 2]] ?? 0;
-    const v3 = clean[i + 3] === "=" ? 0 : lookup[clean[i + 3]] ?? 0;
-    const b0 = v0 << 2 | v1 >> 4;
-    const b1 = (v1 & 15) << 4 | v2 >> 2;
-    const b2 = (v2 & 3) << 6 | v3;
-    if (outIdx < outLen) out[outIdx++] = b0;
-    if (outIdx < outLen) out[outIdx++] = b1;
-    if (outIdx < outLen) out[outIdx++] = b2;
-  }
-  return out;
-}
-function utf8Encode(s) {
-  return new TextEncoder().encode(s);
-}
-function utf8Decode(b) {
-  return new TextDecoder().decode(b);
-}
-function canonicalHashHex(sha256, value) {
-  const canonical = canonicalize(value);
-  return hexEncode2(sha256(utf8Encode(canonical)));
-}
-
 // src/encryption/types.ts
 var DEFAULT_ENCRYPTION_ALG = "x25519-aes256gcm/v1";
 var ENVELOPE_VERSION = 1;
@@ -7563,7 +7711,7 @@ function encryptToNetwork(crypto2, input) {
   const symmetricKey = crypto2.randomBytes(32);
   const ciphertext = crypto2.authEncrypt(symmetricKey, input.plaintext, input.aad);
   const wrapped = crypto2.sealToNetworkKey(input.networkPublicKey, symmetricKey);
-  const encryptedSymmetricKey = base64Encode2(wrapped);
+  const encryptedSymmetricKey = base64Encode(wrapped);
   const encryptedSymmetricKeyHash = canonicalHashHex(
     crypto2.sha256,
     encryptedSymmetricKey
@@ -7575,8 +7723,8 @@ function encryptToNetwork(crypto2, input) {
     keyVersion,
     encryptedSymmetricKey,
     encryptedSymmetricKeyHash,
-    ciphertext: base64Encode2(ciphertext),
-    ...input.aad !== void 0 ? { aad: base64Encode2(input.aad) } : {},
+    ciphertext: base64Encode(ciphertext),
+    ...input.aad !== void 0 ? { aad: base64Encode(input.aad) } : {},
     ...input.metadata !== void 0 ? { metadata: input.metadata } : {}
   };
   return { envelope, symmetricKey };
@@ -7650,8 +7798,8 @@ function validateEnvelope(crypto2, envelope) {
   return { ok: true, data: e };
 }
 function decryptEnvelopeWithKey(crypto2, envelope, symmetricKey) {
-  const ciphertext = base64Decode2(envelope.ciphertext);
-  const aad = envelope.aad !== void 0 ? base64Decode2(envelope.aad) : void 0;
+  const ciphertext = base64Decode(envelope.ciphertext);
+  const aad = envelope.aad !== void 0 ? base64Decode(envelope.aad) : void 0;
   return crypto2.authDecrypt(symmetricKey, ciphertext, aad);
 }
 
@@ -7669,7 +7817,7 @@ function buildCanonicalDecryptRequest(input) {
   return { canonicalBody, bodyHash, receiverPublicKeyHash };
 }
 function buildDecryptFacts(input) {
-  const bodyHash = input.canonicalBody !== void 0 ? hexEncode2(input.crypto.sha256(utf8Encode(input.canonicalBody))) : canonicalHashHex(
+  const bodyHash = input.canonicalBody !== void 0 ? hexEncode(input.crypto.sha256(utf8Encode(input.canonicalBody))) : canonicalHashHex(
     input.crypto.sha256,
     input.body
   );
@@ -7952,7 +8100,7 @@ function verifyDecryptResponse(input) {
       })
     };
   }
-  const expectedRequestHash = hexEncode2(
+  const expectedRequestHash = hexEncode(
     crypto2.sha256(utf8Encode(`${invocationCid}${requestBodyHash}`))
   );
   if (response.requestHash !== expectedRequestHash) {
@@ -7976,7 +8124,7 @@ function verifyDecryptResponse(input) {
   const signedBytes = new TextEncoder().encode(
     canonicalSignedResponse(response)
   );
-  const signatureBytes = base64Decode2(response.nodeSignature);
+  const signatureBytes = base64Decode(response.nodeSignature);
   if (!crypto2.verifyNodeSignature(response.nodeId, signedBytes, signatureBytes)) {
     return {
       ok: false,
@@ -7988,7 +8136,7 @@ function verifyDecryptResponse(input) {
   return { ok: true, data: response };
 }
 function openWrappedKey(crypto2, receiverPrivateKey, response) {
-  const wrapped = base64Decode2(response.wrappedKey);
+  const wrapped = base64Decode(response.wrappedKey);
   return crypto2.openWithReceiverKey(receiverPrivateKey, wrapped);
 }
 
@@ -8032,7 +8180,7 @@ var EncryptionService = class extends BaseService {
       const usable = ensureNetworkUsableForDecrypt(discovered.data);
       if (!usable.ok) return usable;
       const descriptor = usable.data;
-      const networkPublicKey = base64Decode2(descriptor.publicEncryptionKey);
+      const networkPublicKey = base64Decode(descriptor.publicEncryptionKey);
       const result = encryptToNetwork(this.crypto, {
         // Discovery returns the node's canonical network identifier. Persist
         // that spelling in the envelope so a later response can be compared
@@ -8060,7 +8208,7 @@ var EncryptionService = class extends BaseService {
       this.assertActive();
       const validated = validateEnvelope(this.crypto, envelope);
       if (!validated.ok) return validated;
-      if (options?.aad !== void 0 && validated.data.aad !== base64Encode2(options.aad)) {
+      if (options?.aad !== void 0 && validated.data.aad !== base64Encode(options.aad)) {
         return encErr(
           encryptionError({
             code: "INVALID_INPUT",
@@ -8088,7 +8236,7 @@ var EncryptionService = class extends BaseService {
         );
       }
       const receiverKey = generateRandomReceiverKey({ crypto: this.crypto });
-      const receiverPublicKey = base64Encode2(receiverKey.publicKey);
+      const receiverPublicKey = base64Encode(receiverKey.publicKey);
       const receiverPublicKeyHash = canonicalHashHex(
         this.crypto.sha256,
         receiverPublicKey
@@ -8264,8 +8412,8 @@ export {
   authRequiredError,
   authUnauthorizedError,
   authorizationVerdictOf,
-  base64Decode2 as base64Decode,
-  base64Encode2 as base64Encode,
+  base64Decode,
+  base64Encode,
   buildCanonicalDecryptRequest,
   buildDecryptAttenuation,
   buildDecryptFacts,
@@ -8295,13 +8443,14 @@ export {
   generateRandomReceiverKey,
   getTinyCloudDebugLogs,
   hexDecode,
-  hexEncode2 as hexEncode,
+  hexEncode,
   installTinyCloudDebugGlobals,
   isNetworkId,
   isStorageFullError,
   kvPrefixCovers,
   networkDiscoveryKey,
   networkError,
+  nodeRetryError,
   notFoundError,
   ok,
   openWrappedKey,