@tinycloud/sdk-services 3.0.0 → 3.1.0-beta.10

package/dist/index.js

@@ -5,6 +5,10 @@ var ErrorCodes = {
   AUTH_EXPIRED: "AUTH_EXPIRED",
   AUTH_REQUIRED: "AUTH_REQUIRED",
   AUTH_UNAUTHORIZED: "AUTH_UNAUTHORIZED",
+  /** HTTP 401: the delegation the invocation cites was revoked. */
+  AUTH_DELEGATION_REVOKED: "AUTH_DELEGATION_REVOKED",
+  /** HTTP 401: a delegation the cited one rests on was revoked. */
+  AUTH_DELEGATION_ANCESTOR_REVOKED: "AUTH_DELEGATION_ANCESTOR_REVOKED",
   NETWORK_ERROR: "NETWORK_ERROR",
   TIMEOUT: "TIMEOUT",
   ABORTED: "ABORTED",
@@ -16,6 +20,10 @@ var ErrorCodes = {
   KV_PRECONDITION_FAILED: "KV_PRECONDITION_FAILED",
   KV_CONFLICT: "KV_CONFLICT",
   KV_RESPONSE_TOO_LARGE: "KV_RESPONSE_TOO_LARGE",
+  /** HTTP 410 from the change feed: discard sync state and restart without a cursor; `meta.reason` says why. */
+  KV_SYNC_RESET_REQUIRED: "KV_SYNC_RESET_REQUIRED",
+  /** HTTP 403 from the change feed: the retention grant was refused; `meta.reason` says why. */
+  KV_RETENTION_GRANT_REFUSED: "KV_RETENTION_GRANT_REFUSED",
   // SQL-specific errors
   SQL_ERROR: "SQL_ERROR",
   SQL_PERMISSION_DENIED: "SQL_PERMISSION_DENIED",
@@ -896,6 +904,106 @@ var ServiceContext = class {
   }
 };
 
+// src/errors.ts
+import { CAPABILITY_REGISTRY } from "@tinycloud/bootstrap";
+
+// src/encryption/networkId.ts
+var URN_PREFIX = "urn:tinycloud:encryption:";
+var NETWORK_NAME_RE = /^[a-z0-9][a-z0-9-]*$/;
+var PKH_EIP155_DID_RE = /^did:pkh:eip155:(\d+):(0x[a-fA-F0-9]{40})$/;
+var NetworkIdError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "NetworkIdError";
+  }
+};
+function parseNetworkId(networkId) {
+  if (typeof networkId !== "string" || networkId.length === 0) {
+    throw new NetworkIdError("networkId must be a non-empty string");
+  }
+  if (!networkId.startsWith(URN_PREFIX)) {
+    throw new NetworkIdError(
+      `networkId must start with ${URN_PREFIX} (got ${JSON.stringify(networkId)})`
+    );
+  }
+  const body = networkId.slice(URN_PREFIX.length);
+  const lastColon = body.lastIndexOf(":");
+  if (lastColon <= 0 || lastColon === body.length - 1) {
+    throw new NetworkIdError(
+      `networkId missing ownerDid or name segment (got ${JSON.stringify(networkId)})`
+    );
+  }
+  const ownerDid = body.slice(0, lastColon);
+  const name = body.slice(lastColon + 1);
+  if (!ownerDid.startsWith("did:")) {
+    throw new NetworkIdError(
+      `networkId ownerDid must be a DID (got ${JSON.stringify(ownerDid)})`
+    );
+  }
+  const didParts = ownerDid.split(":");
+  if (didParts.length < 3 || didParts.some((p) => p.length === 0)) {
+    throw new NetworkIdError(
+      `networkId ownerDid is not a well-formed DID (got ${JSON.stringify(ownerDid)})`
+    );
+  }
+  if (!NETWORK_NAME_RE.test(name)) {
+    throw new NetworkIdError(
+      `networkId name ${JSON.stringify(name)} must match ${NETWORK_NAME_RE.source}`
+    );
+  }
+  return { networkId, ownerDid, name };
+}
+function buildNetworkId(ownerDid, name) {
+  if (typeof ownerDid !== "string" || !ownerDid.startsWith("did:")) {
+    throw new NetworkIdError("ownerDid must be a DID");
+  }
+  if (typeof name !== "string" || !NETWORK_NAME_RE.test(name)) {
+    throw new NetworkIdError(
+      `network name ${JSON.stringify(name)} must match ${NETWORK_NAME_RE.source}`
+    );
+  }
+  const networkId = `${URN_PREFIX}${ownerDid}:${name}`;
+  parseNetworkId(networkId);
+  return networkId;
+}
+function isNetworkId(networkId) {
+  if (typeof networkId !== "string") {
+    return false;
+  }
+  try {
+    parseNetworkId(networkId);
+    return true;
+  } catch {
+    return false;
+  }
+}
+function parsePkhOwnerDid(ownerDid) {
+  const match = ownerDid.match(PKH_EIP155_DID_RE);
+  if (!match) return null;
+  return {
+    chainId: match[1],
+    address: match[2].toLowerCase()
+  };
+}
+function ownerDidMatches(a, b) {
+  const aPkh = parsePkhOwnerDid(a);
+  const bPkh = parsePkhOwnerDid(b);
+  if (aPkh && bPkh) {
+    return aPkh.chainId === bPkh.chainId && aPkh.address === bPkh.address;
+  }
+  return a === b;
+}
+function networkDiscoveryKey(name) {
+  if (!NETWORK_NAME_RE.test(name)) {
+    throw new NetworkIdError(
+      `network name ${JSON.stringify(name)} must match ${NETWORK_NAME_RE.source}`
+    );
+  }
+  return `.well-known/encryption/network/${name}`;
+}
+var ENCRYPTION_NETWORK_URN_PREFIX = URN_PREFIX;
+var NETWORK_NAME_PATTERN = NETWORK_NAME_RE;
+
 // src/errors.ts
 function parsePermissionHint(value) {
   if (typeof value !== "object" || value === null || Array.isArray(value)) return void 0;
@@ -955,11 +1063,31 @@ function networkError(service, message, cause) {
     cause
   };
 }
-function timeoutError(service) {
+var RequestTimeoutError = class extends Error {
+  constructor(timeoutMs) {
+    super(`Request timed out after ${timeoutMs}ms.`);
+    this.name = "TimeoutError";
+    this.timeoutMs = timeoutMs;
+  }
+};
+function isRequestTimeoutError(error) {
+  return error instanceof RequestTimeoutError || error instanceof Error && error.name === "TimeoutError" && typeof error.timeoutMs === "number";
+}
+function timeoutError(service, timeoutMs, cause) {
+  if (timeoutMs === void 0) {
+    return {
+      code: ErrorCodes.TIMEOUT,
+      message: "Request timed out.",
+      service,
+      ...cause === void 0 ? {} : { cause }
+    };
+  }
   return {
     code: ErrorCodes.TIMEOUT,
-    message: "Request timed out.",
-    service
+    message: `Request timed out after ${timeoutMs}ms.`,
+    service,
+    ...cause === void 0 ? {} : { cause },
+    meta: { timeoutMs }
   };
 }
 function abortedError(service) {
@@ -993,6 +1121,101 @@ function parseAuthError(responseText) {
 function authUnauthorizedError(service, message, meta) {
   return serviceError(ErrorCodes.AUTH_UNAUTHORIZED, message, service, { meta });
 }
+var grantableActions = new Set(
+  CAPABILITY_REGISTRY.map(({ urn }) => urn).filter((urn) => !urn.endsWith("/*"))
+);
+var capabilityServices = new Set(
+  CAPABILITY_REGISTRY.map(({ service }) => service.slice("tinycloud.".length))
+);
+function parseCapabilityResource(resource, service) {
+  if (resource.length === 0 || resource.length > 1024 || !capabilityServices.has(service) || /[\s\p{C}*#]/u.test(resource) || resource.includes("://")) return void 0;
+  const segments = resource.split("/");
+  if (!/^tinycloud:[A-Za-z0-9][A-Za-z0-9:._-]*$/.test(segments[0])) return void 0;
+  const serviceIndex = segments.findIndex(
+    (segment, index) => index > 0 && capabilityServices.has(segment)
+  );
+  if (serviceIndex < 1 || segments[serviceIndex] !== service) return void 0;
+  if (segments.slice(1, serviceIndex).some(
+    (segment) => segment.length === 0 || segment === "." || segment === ".."
+  )) return void 0;
+  const pathSegments = segments.slice(serviceIndex + 1);
+  if (pathSegments.some((segment) => segment === "." || segment === "..")) return void 0;
+  if (service !== "kv" && (pathSegments.length === 0 || pathSegments[pathSegments.length - 1] === "")) return void 0;
+  return {
+    space: segments.slice(0, serviceIndex).join("/"),
+    path: pathSegments.join("/")
+  };
+}
+function safeCapabilityResource(value, service, action) {
+  if (typeof value !== "string" || value.length === 0 || value.length > 1024) return false;
+  if (service === "encryption" && value.startsWith("urn:tinycloud:encryption:")) {
+    if (!/^[A-Za-z0-9_][A-Za-z0-9_.:/-]*$/.test(value) || value.includes("//") || value.split("/").some((segment) => segment === "." || segment === "..")) return false;
+    try {
+      parseNetworkId(value);
+      return true;
+    } catch {
+      return false;
+    }
+  }
+  const parsed = parseCapabilityResource(value, service);
+  return parsed !== void 0 && (!parsed.path.endsWith("/") || service === "kv" && action === "tinycloud.kv/list") && (parsed.path !== "" || service === "kv" && action === "tinycloud.kv/list");
+}
+function validatedCapabilityOf(error) {
+  const verdict = authorizationVerdictOf(error);
+  if (verdict !== "unauthenticated" && verdict !== "forbidden") return void 0;
+  const seen = /* @__PURE__ */ new Set();
+  let node = error;
+  for (let depth = 0; depth < MAX_CAUSE_DEPTH && typeof node === "object" && node !== null && !seen.has(node); depth += 1) {
+    seen.add(node);
+    const record = node;
+    const status = errorStatusOf(record);
+    const meta = record.meta;
+    if ((status === 401 || status === 403 || status === void 0 && record.code === ErrorCodes.AUTH_UNAUTHORIZED) && typeof meta === "object" && meta !== null && !Array.isArray(meta)) {
+      const metadata = meta;
+      const { resource, requiredAction } = metadata;
+      if (typeof requiredAction === "string" && grantableActions.has(requiredAction)) {
+        const actionService = requiredAction.slice("tinycloud.".length, requiredAction.indexOf("/"));
+        const explicitService = record.service === void 0 ? metadata.service : record.service;
+        if (safeCapabilityResource(resource, actionService, requiredAction) && (explicitService === void 0 || explicitService === actionService || explicitService === `tinycloud.${actionService}`)) {
+          return { resource, requiredAction };
+        }
+      }
+    }
+    node = record.cause;
+  }
+  return void 0;
+}
+var MAX_CAUSE_DEPTH = 8;
+function errorStatusOf(node) {
+  const meta = node.meta;
+  const candidates = [
+    node.status,
+    node.statusCode,
+    typeof meta === "object" && meta !== null ? meta.status : void 0
+  ];
+  for (const candidate of candidates) {
+    if (typeof candidate === "number" && Number.isInteger(candidate) && candidate >= 400 && candidate <= 599) {
+      return candidate;
+    }
+  }
+  return void 0;
+}
+function authorizationVerdictOf(error) {
+  const seen = /* @__PURE__ */ new Set();
+  let sawUnauthorizedCode = false;
+  let node = error;
+  for (let depth = 0; depth < MAX_CAUSE_DEPTH && typeof node === "object" && node !== null && !seen.has(node); depth += 1) {
+    seen.add(node);
+    const record = node;
+    const status = errorStatusOf(record);
+    if (status === 401) return "unauthenticated";
+    if (status === 403) return "forbidden";
+    if (status !== void 0) return "other";
+    if (record.code === ErrorCodes.AUTH_UNAUTHORIZED) sawUnauthorizedCode = true;
+    node = record.cause;
+  }
+  return sawUnauthorizedCode ? "forbidden" : void 0;
+}
 function storageQuotaExceededError(service, message, meta) {
   return {
     code: ErrorCodes.STORAGE_QUOTA_EXCEEDED,
@@ -1009,8 +1232,28 @@ function storageLimitReachedError(service, message, meta) {
     meta
   };
 }
+var STORAGE_FULL_MESSAGE = "TinyCloud storage is full, so this change was not saved. Reading still works. Free up space or upgrade your plan to save again.";
+var STORAGE_WRITE_TOO_LARGE_MESSAGE = "This change is larger than the TinyCloud storage you have left, so it was not saved. Reading still works. Free up space or upgrade your plan to save it.";
+function parseStorageQuotaBytes(responseText) {
+  const match = responseText.match(/Used:\s*(\d+)\s*bytes,\s*Limit:\s*(\d+)\s*bytes/i);
+  if (!match) return void 0;
+  return {
+    usedBytes: parseInt(match[1], 10),
+    limitBytes: parseInt(match[2], 10)
+  };
+}
+function storageRejectionError(service, status, meta, responseText) {
+  const quotaMeta = { ...meta, ...parseStorageQuotaBytes(responseText) };
+  return status === 402 ? storageQuotaExceededError(service, STORAGE_FULL_MESSAGE, quotaMeta) : storageLimitReachedError(service, STORAGE_WRITE_TOO_LARGE_MESSAGE, quotaMeta);
+}
+function isStorageFullError(error) {
+  return error?.code === ErrorCodes.STORAGE_QUOTA_EXCEEDED || error?.code === ErrorCodes.STORAGE_LIMIT_REACHED;
+}
 function wrapError(service, error, defaultCode = ErrorCodes.NETWORK_ERROR) {
   if (error instanceof Error) {
+    if (isRequestTimeoutError(error)) {
+      return timeoutError(service, error.timeoutMs, error);
+    }
     if (error.name === "AbortError") {
       return abortedError(service);
     }
@@ -1035,6 +1278,7 @@ function errorResult(error) {
 }
 
 // src/base/BaseService.ts
+var MAX_TIMER_DELAY_MS = 2147483647;
 var BaseService = class {
   constructor() {
     /**
@@ -1215,6 +1459,64 @@ var BaseService = class {
     }
     return controller.signal;
   }
+  /**
+   * Create the abort signal for one request, bounded by the request timeout.
+   *
+   * The signal aborts when the service signs out, the context aborts, the
+   * caller's `signal` aborts, or the timeout elapses, whichever comes first.
+   * A timeout aborts with a {@link RequestTimeoutError} (`TimeoutError`), which
+   * `wrapError` maps to `ErrorCodes.TIMEOUT`; the other sources keep their own
+   * reason (normally `AbortError`, mapped to `ErrorCodes.ABORTED`).
+   *
+   * The timeout is `timeoutMs` when given, otherwise `config.timeout`. Only a
+   * positive, finite value (at most 2^31-1 ms) applies; `undefined`, `0`, and
+   * `Infinity` mean no timeout, so a per-call `0` opts out of a configured one.
+   *
+   * Callers must call `dispose()` once the response body has been consumed,
+   * which clears the timer and removes the listeners this adds to the
+   * long-lived service and context signals.
+   *
+   * @param signal - The caller's abort signal for this request
+   * @param timeoutMs - Per-request timeout override in milliseconds
+   */
+  createRequestSignal(signal, timeoutMs) {
+    const controller = new AbortController();
+    const detachers = [];
+    let timer;
+    const dispose = () => {
+      if (timer !== void 0) {
+        clearTimeout(timer);
+        timer = void 0;
+      }
+      for (const detach of detachers.splice(0)) {
+        detach();
+      }
+    };
+    const abort = (reason) => {
+      dispose();
+      controller.abort(reason);
+    };
+    const requestSignal = { signal: controller.signal, dispose };
+    const parents = [
+      this.abortController.signal,
+      this.context?.abortSignal,
+      signal
+    ].filter((parent) => parent !== void 0);
+    for (const parent of parents) {
+      if (parent.aborted) {
+        abort(parent.reason);
+        return requestSignal;
+      }
+      const onAbort = () => abort(parent.reason);
+      parent.addEventListener("abort", onAbort, { once: true });
+      detachers.push(() => parent.removeEventListener("abort", onAbort));
+    }
+    const timeout = timeoutMs ?? this._config.timeout;
+    if (typeof timeout === "number" && timeout > 0 && timeout <= MAX_TIMER_DELAY_MS) {
+      timer = setTimeout(() => abort(new RequestTimeoutError(timeout)), timeout);
+    }
+    return requestSignal;
+  }
   /**
    * Wrap an operation with error handling and telemetry.
    *
@@ -1323,6 +1625,30 @@ var PrefixedKVService = class _PrefixedKVService {
       removePrefix
     });
   }
+  /**
+   * Read the change feed for everything under this prefix. A view with an
+   * empty prefix (`""` or `"/"`) is refused: the node does not serve a
+   * whole-space feed.
+   */
+  async changes(options) {
+    if (this._prefix.replace(/\/+$/, "") === "") {
+      return err(serviceError(
+        ErrorCodes.INVALID_INPUT,
+        "KV changes needs a non-empty prefix; this view has none",
+        "kv"
+      ));
+    }
+    const syncPrefix = `${this._prefix}/`;
+    const response = await this._kv.changes({ ...options, prefix: syncPrefix });
+    if (!response.ok) return response;
+    return ok({
+      ...response.data,
+      changes: response.data.changes.map((change) => ({
+        ...change,
+        key: change.key.startsWith(syncPrefix) ? change.key.slice(syncPrefix.length) : change.key
+      }))
+    });
+  }
   /**
    * Delete a key.
    */
@@ -1375,11 +1701,24 @@ var KVAction = {
   PUT: "tinycloud.kv/put",
   LIST: "tinycloud.kv/list",
   DELETE: "tinycloud.kv/del",
-  HEAD: "tinycloud.kv/metadata"
+  HEAD: "tinycloud.kv/metadata",
+  /** The change feed; never implied by `*` or `tinycloud.kv/*`. */
+  SYNC: "tinycloud.kv/sync",
+  /** Retention attestation; presented through `retentionGrant`, never invoked or implied. */
+  RETAIN: "tinycloud.kv/retain"
 };
 
 // src/kv/KVService.ts
 var MAX_KV_BATCH_READ_ITEMS = 100;
+function isJsonObject(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+var REVOKED_BODY = /^(?:Invalid invocation: )?delegation-(?:(revoked): [A-Za-z0-9]+|(ancestor-revoked): ancestor=[A-Za-z0-9]+ invoked=[A-Za-z0-9]+)$/;
+function revocationCodeOf(body) {
+  const match = REVOKED_BODY.exec(body.trim());
+  if (match === null) return void 0;
+  return match[1] !== void 0 ? ErrorCodes.AUTH_DELEGATION_REVOKED : ErrorCodes.AUTH_DELEGATION_ANCESTOR_REVOKED;
+}
 function encodeKvBatchPartName(path) {
   return encodeURIComponent(path).replace(
     /[!'()*]/g,
@@ -1402,47 +1741,21 @@ var KVService = class extends BaseService {
   get config() {
     return this._config;
   }
-  // Parses "Used: X bytes, Limit: Y bytes" from tinycloud-node error responses
-  parseQuotaInfo(errorText) {
-    const match = errorText.match(
-      /Used:\s*(\d+)\s*bytes,\s*Limit:\s*(\d+)\s*bytes/i
-    );
-    if (match) {
-      return {
-        usedBytes: parseInt(match[1], 10),
-        limitBytes: parseInt(match[2], 10)
-      };
-    }
-    return void 0;
-  }
   handleQuotaErrorResponse(response, errorText, key) {
-    if (response.status === 402) {
-      const quotaInfo = this.parseQuotaInfo(errorText);
-      return err(
-        storageQuotaExceededError(
-          "kv",
-          `Storage quota exceeded for key "${key}": ${errorText}`,
-          {
-            status: response.status,
-            ...quotaInfo ? { usedBytes: quotaInfo.usedBytes, limitBytes: quotaInfo.limitBytes } : {}
-          }
-        )
-      );
+    if (response.status !== 402 && response.status !== 413) {
+      return void 0;
     }
-    if (response.status === 413) {
-      const quotaInfo = this.parseQuotaInfo(errorText);
-      return err(
-        storageLimitReachedError(
-          "kv",
-          `Storage limit reached for key "${key}": ${errorText}`,
-          {
-            status: response.status,
-            ...quotaInfo ? { usedBytes: quotaInfo.usedBytes, limitBytes: quotaInfo.limitBytes } : {}
-          }
-        )
-      );
+    if (response.status === 413 && !parseStorageQuotaBytes(errorText)) {
+      return void 0;
     }
-    return void 0;
+    return err(
+      storageRejectionError(
+        "kv",
+        response.status,
+        { status: response.status, statusText: response.statusText, key },
+        errorText
+      )
+    );
   }
   /**
    * Classify a KV 404 by reading the response body once.
@@ -1501,7 +1814,7 @@ var KVService = class extends BaseService {
    * @param path - Resource path
    * @param action - KV action
    * @param body - Optional request body
-   * @param signal - Optional abort signal
+   * @param signal - Request signal from createRequestSignal()
    * @returns Fetch response
    */
   async invokeOperation(path, action, body, signal, extraHeaders) {
@@ -1517,7 +1830,7 @@ var KVService = class extends BaseService {
       method: "POST",
       headers: requestHeaders,
       body,
-      signal: this.combineSignals(signal)
+      signal
     });
   }
   /**
@@ -1694,6 +2007,7 @@ var KVService = class extends BaseService {
         "kv"
       ));
     }
+    const request = this.createRequestSignal(options?.signal, options?.timeout);
     try {
       const session = this.context.session;
       const invocationHeaders = this.context.invokeAny(
@@ -1715,17 +2029,18 @@ var KVService = class extends BaseService {
       const response = await this.context.fetch(`${this.host}/invoke`, {
         method: "POST",
         headers,
-        signal: this.combineSignals(options?.signal)
+        signal: request.signal
       });
       if (!response.ok) {
-        const errorText = await response.text();
+        const errorText = response.status === 401 || response.status === 403 ? await this.readAuthorizationText(response) : await response.text();
         if (response.status === 401 || response.status === 403) {
-          const { resource, action: requiredAction } = parseAuthError(errorText);
-          return err(authUnauthorizedError("kv", errorText, {
-            status: response.status,
-            ...requiredAction && { requiredAction },
-            ...resource && { resource }
-          }));
+          return this.authorizationFailure(
+            `Failed to batch read ${keys.length} key(s)`,
+            response,
+            errorText,
+            paths,
+            action
+          );
         }
         if (response.status === 413) {
           return err(serviceError(
@@ -1779,6 +2094,8 @@ var KVService = class extends BaseService {
       return ok({ results, count: results.length });
     } catch (error) {
       return err(wrapError("kv", error));
+    } finally {
+      request.dispose();
     }
   }
   /**
@@ -1814,7 +2131,7 @@ var KVService = class extends BaseService {
       return text;
     }
   }
-  async createSignedReadUrlError(response, key) {
+  async createSignedReadUrlError(response, key, path) {
     let errorText = response.statusText;
     try {
       const text = await response.text();
@@ -1824,23 +2141,62 @@ var KVService = class extends BaseService {
     } catch {
     }
     if (response.status === 401 || response.status === 403) {
-      const { resource, action } = parseAuthError(errorText);
-      return err(authUnauthorizedError("kv", errorText, {
-        status: response.status,
-        ...action && { requiredAction: action },
-        ...resource && { resource }
-      }));
+      return this.authorizationFailure(
+        `Failed to create signed read URL for key ${JSON.stringify(key)}`,
+        response,
+        errorText,
+        [path],
+        KVAction.GET
+      );
     }
     const code = response.status === 400 ? ErrorCodes.INVALID_INPUT : ErrorCodes.NETWORK_ERROR;
     return err(
       serviceError(
         code,
-        `Failed to create signed read URL for key "${key}": ${response.status} - ${errorText}`,
+        `Failed to create signed read URL for key ${JSON.stringify(key)}: ${response.status} - ${errorText}`,
         "kv",
         { meta: { status: response.status, statusText: response.statusText } }
       )
     );
   }
+  /** A known 401/403 keeps its typed status even if reading its body fails. */
+  async readAuthorizationText(response) {
+    try {
+      return await response.text();
+    } catch {
+      return "";
+    }
+  }
+  /**
+   * AUTH_UNAUTHORIZED for a 401/403 response. The message keeps the HTTP
+   * status and the server text (`<context>: <status> - <text>`, the same
+   * shape as every other KV failure) so callers that rethrow only the message
+   * still see the status; `meta.status` carries it for typed callers.
+   * Server hints must match the requested path/action (whether the node sends
+   * a relative path or full resource); metadata uses only the request-derived
+   * canonical resource under the authenticated session's space.
+   */
+  authorizationFailure(context, response, errorText, paths, expectedAction, extraMeta = {}) {
+    const { resource, action } = parseAuthError(errorText);
+    const requestedPath = paths.find(
+      (path) => resource === path || resource === `${this.context.session.spaceId}/kv/${path}`
+    );
+    const capability = requestedPath !== void 0 && action === expectedAction ? validatedCapabilityOf({
+      service: "kv",
+      code: ErrorCodes.AUTH_UNAUTHORIZED,
+      meta: {
+        status: response.status,
+        resource: `${this.context.session.spaceId}/kv/${requestedPath}`,
+        requiredAction: action
+      }
+    }) : void 0;
+    const detail = errorText.trim().length > 0 ? errorText : response.statusText || "authorization failed";
+    return err(authUnauthorizedError("kv", `${context}: ${response.status} - ${detail}`, {
+      status: response.status,
+      ...extraMeta,
+      ...capability
+    }));
+  }
   normalizeSignedReadUrlResponse(data) {
     if (!data || typeof data !== "object") {
       return void 0;
@@ -1872,25 +2228,36 @@ var KVService = class extends BaseService {
         ));
       }
       const path = this.getFullPath(key, options?.prefix);
+      const request = this.createRequestSignal(options?.signal, options?.timeout);
       try {
         const response = await this.invokeOperation(
           path,
           KVAction.GET,
           void 0,
-          options?.signal,
+          request.signal,
           options?.maxResponseBytes === void 0 ? void 0 : { "x-tinycloud-max-response-bytes": String(options.maxResponseBytes) }
         );
         if (!response.ok) {
           if (response.status === 401 || response.status === 403) {
-            const errorText2 = await response.text();
-            const { resource, action } = parseAuthError(errorText2);
+            const errorText2 = await this.readAuthorizationText(response);
             const permissionHint = parsePermissionHintFromErrorText(errorText2);
-            return err(authUnauthorizedError("kv", errorText2, {
-              status: response.status,
-              ...action && { requiredAction: action },
-              ...resource && { resource },
-              ...permissionHint === void 0 ? {} : { permissionHint }
-            }));
+            const structuredCapability = permissionHint?.service === "tinycloud.kv" && permissionHint.space === this.context.session.spaceId && permissionHint.path === path ? validatedCapabilityOf({
+              service: "kv",
+              code: ErrorCodes.AUTH_UNAUTHORIZED,
+              meta: {
+                status: response.status,
+                resource: `${this.context.session.spaceId}/kv/${path}`,
+                requiredAction: KVAction.GET
+              }
+            }) : void 0;
+            return this.authorizationFailure(
+              `Failed to get key ${JSON.stringify(key)}`,
+              response,
+              errorText2,
+              [path],
+              KVAction.GET,
+              structuredCapability ? { permissionHint, ...structuredCapability } : {}
+            );
           }
           if (response.status === 404) {
             return this.classifyNotFound(response, key);
@@ -1899,7 +2266,7 @@ var KVService = class extends BaseService {
           if (response.status === 413) {
             return err(serviceError(
               ErrorCodes.KV_RESPONSE_TOO_LARGE,
-              `KV value at key "${key}" exceeds the requested response limit`,
+              `KV value at key ${JSON.stringify(key)} exceeds the requested response limit`,
               "kv",
               { meta: { status: response.status, statusText: response.statusText } }
             ));
@@ -1907,7 +2274,7 @@ var KVService = class extends BaseService {
           return err(
             serviceError(
               ErrorCodes.NETWORK_ERROR,
-              `Failed to get key "${key}": ${response.status} - ${errorText}`,
+              `Failed to get key ${JSON.stringify(key)}: ${response.status} - ${errorText}`,
               "kv",
               { meta: { status: response.status, statusText: response.statusText } }
             )
@@ -1924,6 +2291,8 @@ var KVService = class extends BaseService {
         });
       } catch (error) {
         return err(wrapError("kv", error));
+      } finally {
+        request.dispose();
       }
     });
   }
@@ -1951,33 +2320,33 @@ var KVService = class extends BaseService {
       }
       const path = this.getFullPath(key, options?.prefix);
       const body = this.serializePutValue(value, options?.contentType);
+      const request = this.createRequestSignal(options?.signal, options?.timeout);
       try {
         const response = await this.invokeOperation(
           path,
           KVAction.PUT,
           body,
-          options?.signal,
+          request.signal,
           {
             ...options?.ifMatch === void 0 ? {} : { "if-match": options.ifMatch },
             ...options?.ifNoneMatch === void 0 ? {} : { "if-none-match": options.ifNoneMatch }
           }
         );
         if (response.status === 401 || response.status === 403) {
-          const errorText = await response.text();
-          const message = errorText.trim().length > 0 ? errorText : `Failed to put key "${key}": ${response.status} - ${response.statusText || "authorization failed"}`;
-          const { resource, action: requiredAction } = parseAuthError(errorText);
-          return err(authUnauthorizedError("kv", message, {
-            status: response.status,
-            ...requiredAction && { requiredAction },
-            ...resource && { resource }
-          }));
+          return this.authorizationFailure(
+            `Failed to put key ${JSON.stringify(key)}`,
+            response,
+            await this.readAuthorizationText(response),
+            [path],
+            KVAction.PUT
+          );
         }
         if (!response.ok) {
           const errorText = await response.text();
           if (response.status === 412) {
             return err(serviceError(
               ErrorCodes.KV_PRECONDITION_FAILED,
-              `KV precondition failed for key "${key}"`,
+              `KV precondition failed for key ${JSON.stringify(key)}`,
               "kv",
               { meta: { status: response.status, statusText: response.statusText } }
             ));
@@ -1985,7 +2354,7 @@ var KVService = class extends BaseService {
           if (response.status === 503 && (options?.ifMatch !== void 0 || options?.ifNoneMatch !== void 0)) {
             return err(serviceError(
               ErrorCodes.KV_CONFLICT,
-              `Concurrent KV update conflicted for key "${key}"`,
+              `Concurrent KV update conflicted for key ${JSON.stringify(key)}`,
               "kv",
               { meta: { status: response.status, statusText: response.statusText } }
             ));
@@ -2001,7 +2370,7 @@ var KVService = class extends BaseService {
           return err(
             serviceError(
               ErrorCodes.KV_WRITE_FAILED,
-              `Failed to put key "${key}": ${response.status} - ${errorText}`,
+              `Failed to put key ${JSON.stringify(key)}: ${response.status} - ${errorText}`,
               "kv",
               { meta: { status: response.status, statusText: response.statusText } }
             )
@@ -2013,6 +2382,8 @@ var KVService = class extends BaseService {
         });
       } catch (error) {
         return err(wrapError("kv", error));
+      } finally {
+        request.dispose();
       }
     });
   }
@@ -2052,6 +2423,7 @@ var KVService = class extends BaseService {
         seen.add(path);
       }
       let requestMayHaveDispatched = false;
+      const request = this.createRequestSignal(options?.signal, options?.timeout);
       try {
         const body = new FormData();
         for (let index = 0; index < items.length; index++) {
@@ -2074,7 +2446,7 @@ var KVService = class extends BaseService {
           method: "POST",
           headers,
           body,
-          signal: this.combineSignals(options?.signal)
+          signal: request.signal
         };
         const fetchFn = this.context.fetch;
         requestMayHaveDispatched = true;
@@ -2095,12 +2467,13 @@ var KVService = class extends BaseService {
             );
           }
           if (response.status === 401 || response.status === 403) {
-            const { resource, action } = parseAuthError(errorText);
-            return err(authUnauthorizedError("kv", errorText, {
-              status: response.status,
-              ...action && { requiredAction: action },
-              ...resource && { resource }
-            }));
+            return this.authorizationFailure(
+              `Failed to batch put ${items.length} key(s)`,
+              response,
+              errorText,
+              paths,
+              KVAction.PUT
+            );
           }
           const quotaError = this.handleQuotaErrorResponse(
             response,
@@ -2124,14 +2497,16 @@ var KVService = class extends BaseService {
           rawBody = await response.json();
         } catch (jsonError) {
           const cause = jsonError instanceof Error ? jsonError : new Error(String(jsonError));
+          const timedOut = isRequestTimeoutError(cause);
           return err(
             serviceError(
-              ErrorCodes.NETWORK_ERROR,
-              `KV batchPut response was not valid JSON: ${cause.message}`,
+              timedOut ? ErrorCodes.TIMEOUT : ErrorCodes.NETWORK_ERROR,
+              timedOut ? `KV batchPut response body did not arrive in time: ${cause.message}` : `KV batchPut response was not valid JSON: ${cause.message}`,
               "kv",
               {
                 cause,
                 meta: {
+                  ...timedOut ? { timeoutMs: cause.timeoutMs } : {},
                   requestMayHaveDispatched: true,
                   responseReceived: true,
                   status: response.status,
@@ -2186,6 +2561,8 @@ var KVService = class extends BaseService {
           ...wrapped,
           meta: { ...wrapped.meta, requestMayHaveDispatched }
         });
+      } finally {
+        request.dispose();
       }
     });
   }
@@ -2208,26 +2585,27 @@ var KVService = class extends BaseService {
       if (options?.path) {
         listPath = listPath ? `${listPath}/${options.path}` : options.path;
       }
+      const request = this.createRequestSignal(options?.signal, options?.timeout);
       try {
         const response = await this.invokeOperation(
           listPath,
           KVAction.LIST,
           void 0,
-          options?.signal,
+          request.signal,
           options?.limit === void 0 && options?.cursor === void 0 ? void 0 : {
             ...options?.limit === void 0 ? {} : { "x-tinycloud-limit": String(options.limit) },
             ...options?.cursor === void 0 ? {} : { "x-tinycloud-cursor": options.cursor }
           }
         );
         if (!response.ok) {
-          if (response.status === 401) {
-            const errorText2 = await response.text();
-            const { resource, action } = parseAuthError(errorText2);
-            return err(authUnauthorizedError("kv", errorText2, {
-              status: response.status,
-              ...action && { requiredAction: action },
-              ...resource && { resource }
-            }));
+          if (response.status === 401 || response.status === 403) {
+            return this.authorizationFailure(
+              "Failed to list keys",
+              response,
+              await this.readAuthorizationText(response),
+              [listPath],
+              KVAction.LIST
+            );
           }
           const errorText = await response.text();
           return err(
@@ -2254,9 +2632,174 @@ var KVService = class extends BaseService {
         });
       } catch (error) {
         return err(wrapError("kv", error));
+      } finally {
+        request.dispose();
+      }
+    });
+  }
+  /**
+   * Read one page of the `tinycloud.kv/sync` change feed for a prefix.
+   */
+  async changes(options) {
+    return this.withTelemetry("changes", options?.prefix, async () => {
+      if (!this.requireAuth()) {
+        return err(authRequiredError("kv"));
+      }
+      if (typeof options?.prefix !== "string" || options.prefix.length === 0) {
+        return err(serviceError(
+          ErrorCodes.INVALID_INPUT,
+          "KV changes prefix must be a non-empty string",
+          "kv"
+        ));
+      }
+      if (options.limit !== void 0 && (!Number.isInteger(options.limit) || options.limit < 1 || options.limit > 1e3)) {
+        return err(serviceError(
+          ErrorCodes.INVALID_INPUT,
+          "KV changes limit must be an integer from 1 through 1000",
+          "kv"
+        ));
+      }
+      const headers = {};
+      if (options.limit !== void 0) headers["x-tinycloud-limit"] = String(options.limit);
+      if (options.cursor !== void 0) headers["x-tinycloud-cursor"] = options.cursor;
+      if (options.retentionGrant !== void 0) {
+        headers["x-tinycloud-retention-grant"] = options.retentionGrant;
+      }
+      const request = this.createRequestSignal(options.signal, options.timeout);
+      try {
+        const response = await this.invokeOperation(
+          options.prefix,
+          KVAction.SYNC,
+          void 0,
+          request.signal,
+          headers
+        );
+        if (!response.ok) {
+          return await this.changesFailure(response, options.prefix, request.signal);
+        }
+        const text = await response.text();
+        let body;
+        try {
+          body = JSON.parse(text);
+        } catch {
+          body = void 0;
+        }
+        const page = this.normalizeChangesResponse(body);
+        if (!page) {
+          return err(serviceError(
+            ErrorCodes.NETWORK_ERROR,
+            "KV changes response was not a tinycloud.kv/sync page",
+            "kv",
+            { meta: { status: response.status, statusText: response.statusText } }
+          ));
+        }
+        return ok(page);
+      } catch (error) {
+        return err(wrapError("kv", error));
+      } finally {
+        request.dispose();
       }
     });
   }
+  /**
+   * Map a failed `kv/sync` response. 410 and the retention 403 carry
+   * `{"error":{"code","reason"}}`; a revoked grant is a 401 whose whole body
+   * is the node's revocation error (see REVOKED_BODY). A body read that
+   * fails because the request was cancelled or timed out rethrows, so the
+   * caller sees `ABORTED`/`TIMEOUT` rather than a mapped status.
+   */
+  async changesFailure(response, prefix, signal) {
+    if (response.status === 404) {
+      return this.classifyNotFound(response, prefix);
+    }
+    let errorText;
+    try {
+      errorText = await response.text();
+    } catch (error) {
+      if (signal.aborted) throw error;
+      errorText = "";
+    }
+    const meta = { status: response.status, statusText: response.statusText };
+    let reason;
+    let bodyCode;
+    try {
+      const body = JSON.parse(errorText);
+      const error = isJsonObject(body) ? body.error : void 0;
+      if (isJsonObject(error)) {
+        if (typeof error.code === "string") bodyCode = error.code;
+        if (typeof error.reason === "string") reason = error.reason;
+      }
+    } catch {
+    }
+    const context = `Failed to read KV changes for ${JSON.stringify(prefix)}`;
+    if (response.status === 410) {
+      return err(serviceError(
+        ErrorCodes.KV_SYNC_RESET_REQUIRED,
+        `${context}: the node requires a reset (${reason ?? "reason not given"}); discard sync state and restart without a cursor`,
+        "kv",
+        { meta: { ...meta, reason } }
+      ));
+    }
+    if (response.status === 403 && bodyCode === "RETENTION_GRANT_REFUSED") {
+      return err(serviceError(
+        ErrorCodes.KV_RETENTION_GRANT_REFUSED,
+        `${context}: the retention grant was refused (${reason ?? "reason not given"})`,
+        "kv",
+        { meta: { ...meta, reason } }
+      ));
+    }
+    if (response.status === 401) {
+      const revoked = revocationCodeOf(errorText);
+      if (revoked !== void 0) {
+        return err(serviceError(revoked, `${context}: 401 - ${errorText}`, "kv", { meta }));
+      }
+    }
+    if (response.status === 401 || response.status === 403) {
+      return this.authorizationFailure(context, response, errorText, [prefix], KVAction.SYNC);
+    }
+    return err(serviceError(
+      response.status === 400 ? ErrorCodes.INVALID_INPUT : ErrorCodes.NETWORK_ERROR,
+      `${context}: ${response.status} - ${errorText}`,
+      "kv",
+      { meta }
+    ));
+  }
+  normalizeChangesResponse(data) {
+    if (!isJsonObject(data)) return void 0;
+    const { changes, more, cursor, source, authority } = data;
+    if (!Array.isArray(changes) || typeof more !== "boolean" || typeof cursor !== "string" || !isJsonObject(source) || typeof source.nodeDid !== "string" || typeof source.space !== "string" || typeof source.prefix !== "string" || !isJsonObject(authority)) {
+      return void 0;
+    }
+    const { notBefore, expiresAt, retainUntil } = authority;
+    if (notBefore !== null && typeof notBefore !== "string" || expiresAt !== null && typeof expiresAt !== "string" || retainUntil !== null && typeof retainUntil !== "string") {
+      return void 0;
+    }
+    const parsed = [];
+    for (const change of changes) {
+      if (!isJsonObject(change) || typeof change.key !== "string") return void 0;
+      if (change.deleted === true) {
+        parsed.push({ key: change.key, deleted: true });
+        continue;
+      }
+      const { metadata } = change;
+      if (change.deleted !== false || typeof change.etag !== "string" || !isJsonObject(metadata) || !Object.values(metadata).every((value) => typeof value === "string")) {
+        return void 0;
+      }
+      parsed.push({
+        key: change.key,
+        deleted: false,
+        etag: change.etag,
+        metadata
+      });
+    }
+    return {
+      changes: parsed,
+      more,
+      cursor,
+      source: { nodeDid: source.nodeDid, space: source.space, prefix: source.prefix },
+      authority: { notBefore, expiresAt, retainUntil }
+    };
+  }
   /**
    * Delete a key.
    */
@@ -2266,23 +2809,24 @@ var KVService = class extends BaseService {
         return err(authRequiredError("kv"));
       }
       const path = this.getFullPath(key, options?.prefix);
+      const request = this.createRequestSignal(options?.signal, options?.timeout);
       try {
         const response = await this.invokeOperation(
           path,
           KVAction.DELETE,
           void 0,
-          options?.signal,
+          request.signal,
           options?.ifMatch === void 0 ? void 0 : { "if-match": options.ifMatch }
         );
         if (!response.ok) {
-          if (response.status === 401) {
-            const errorText2 = await response.text();
-            const { resource, action } = parseAuthError(errorText2);
-            return err(authUnauthorizedError("kv", errorText2, {
-              status: response.status,
-              ...action && { requiredAction: action },
-              ...resource && { resource }
-            }));
+          if (response.status === 401 || response.status === 403) {
+            return this.authorizationFailure(
+              `Failed to delete key ${JSON.stringify(key)}`,
+              response,
+              await this.readAuthorizationText(response),
+              [path],
+              KVAction.DELETE
+            );
           }
           if (response.status === 404) {
             return this.classifyNotFound(response, key);
@@ -2291,7 +2835,7 @@ var KVService = class extends BaseService {
           if (response.status === 412) {
             return err(serviceError(
               ErrorCodes.KV_PRECONDITION_FAILED,
-              `KV precondition failed for key "${key}"`,
+              `KV precondition failed for key ${JSON.stringify(key)}`,
               "kv",
               { meta: { status: response.status, statusText: response.statusText } }
             ));
@@ -2299,7 +2843,7 @@ var KVService = class extends BaseService {
           if (response.status === 503 && options?.ifMatch !== void 0) {
             return err(serviceError(
               ErrorCodes.KV_CONFLICT,
-              `Concurrent KV delete conflicted for key "${key}"`,
+              `Concurrent KV delete conflicted for key ${JSON.stringify(key)}`,
               "kv",
               { meta: { status: response.status, statusText: response.statusText } }
             ));
@@ -2307,7 +2851,7 @@ var KVService = class extends BaseService {
           return err(
             serviceError(
               ErrorCodes.NETWORK_ERROR,
-              `Failed to delete key "${key}": ${response.status} - ${errorText}`,
+              `Failed to delete key ${JSON.stringify(key)}: ${response.status} - ${errorText}`,
               "kv",
               { meta: { status: response.status, statusText: response.statusText } }
             )
@@ -2319,6 +2863,8 @@ var KVService = class extends BaseService {
         });
       } catch (error) {
         return err(wrapError("kv", error));
+      } finally {
+        request.dispose();
       }
     });
   }
@@ -2331,22 +2877,23 @@ var KVService = class extends BaseService {
         return err(authRequiredError("kv"));
       }
       const path = this.getFullPath(key, options?.prefix);
+      const request = this.createRequestSignal(options?.signal, options?.timeout);
       try {
         const response = await this.invokeOperation(
           path,
           KVAction.HEAD,
           void 0,
-          options?.signal
+          request.signal
         );
         if (!response.ok) {
-          if (response.status === 401) {
-            const errorText2 = await response.text();
-            const { resource, action } = parseAuthError(errorText2);
-            return err(authUnauthorizedError("kv", errorText2, {
-              status: response.status,
-              ...action && { requiredAction: action },
-              ...resource && { resource }
-            }));
+          if (response.status === 401 || response.status === 403) {
+            return this.authorizationFailure(
+              `Failed to get metadata for key ${JSON.stringify(key)}`,
+              response,
+              await this.readAuthorizationText(response),
+              [path],
+              KVAction.HEAD
+            );
           }
           if (response.status === 404) {
             return this.classifyNotFound(response, key);
@@ -2355,7 +2902,7 @@ var KVService = class extends BaseService {
           return err(
             serviceError(
               ErrorCodes.NETWORK_ERROR,
-              `Failed to get metadata for key "${key}": ${response.status} - ${errorText}`,
+              `Failed to get metadata for key ${JSON.stringify(key)}: ${response.status} - ${errorText}`,
               "kv",
               { meta: { status: response.status, statusText: response.statusText } }
             )
@@ -2367,6 +2914,8 @@ var KVService = class extends BaseService {
         });
       } catch (error) {
         return err(wrapError("kv", error));
+      } finally {
+        request.dispose();
       }
     });
   }
@@ -2404,15 +2953,16 @@ var KVService = class extends BaseService {
       if (options?.etag !== void 0) {
         body.etag = options.etag;
       }
+      const request = this.createRequestSignal(options?.signal, options?.timeout);
       try {
         const response = await this.context.fetch(`${this.host}/signed/kv`, {
           method: "POST",
           headers: this.withJsonContentType(headers),
           body: JSON.stringify(body),
-          signal: this.combineSignals(options?.signal)
+          signal: request.signal
         });
         if (!response.ok) {
-          return this.createSignedReadUrlError(response, key);
+          return this.createSignedReadUrlError(response, key, path);
         }
         const signedUrl = this.normalizeSignedReadUrlResponse(
           await response.json()
@@ -2429,6 +2979,8 @@ var KVService = class extends BaseService {
         return ok(signedUrl);
       } catch (error) {
         return err(wrapError("kv", error));
+      } finally {
+        request.dispose();
       }
     });
   }
@@ -2642,6 +3194,7 @@ var SQLService = class extends BaseService {
       if (!this.requireAuth()) {
         return err(authRequiredError("sql"));
       }
+      const request = this.createRequestSignal(options?.signal);
       try {
         const body = {
           action: "query",
@@ -2650,19 +3203,22 @@ var SQLService = class extends BaseService {
         };
         if (options?.maxRows !== void 0) body.maxRows = options.maxRows;
         if (options?.maxBytes !== void 0) body.maxBytes = options.maxBytes;
+        const action = this.actionForSql(sql, SQLAction.READ);
         const response = await this.invokeSQL(
           dbName,
-          this.actionForSql(sql, SQLAction.READ),
+          action,
           body,
-          options?.signal
+          request.signal
         );
         if (!response.ok) {
-          return this.handleErrorResponse(response, "query");
+          return this.handleErrorResponse(response, "query", dbName, [action]);
         }
         const data = await response.json();
         return ok(data);
       } catch (error) {
         return err(wrapError("sql", error));
+      } finally {
+        request.dispose();
       }
     });
   }
@@ -2671,6 +3227,7 @@ var SQLService = class extends BaseService {
       if (!this.requireAuth()) {
         return err(authRequiredError("sql"));
       }
+      const request = this.createRequestSignal(options?.signal);
       try {
         const body = {
           action: "execute",
@@ -2686,19 +3243,22 @@ var SQLService = class extends BaseService {
             (statement) => this.actionForSql(statement, SQLAction.SCHEMA)
           )
         ];
+        const requestedActions = this.dedupeActions(actions);
         const response = await this.invokeSQL(
           dbName,
-          this.dedupeActions(actions),
+          requestedActions,
           body,
-          options?.signal
+          request.signal
         );
         if (!response.ok) {
-          return this.handleErrorResponse(response, "execute");
+          return this.handleErrorResponse(response, "execute", dbName, requestedActions);
         }
         const data = await response.json();
         return ok(data);
       } catch (error) {
         return err(wrapError("sql", error));
+      } finally {
+        request.dispose();
       }
     });
   }
@@ -2707,20 +3267,24 @@ var SQLService = class extends BaseService {
       if (!this.requireAuth()) {
         return err(authRequiredError("sql"));
       }
+      const request = this.createRequestSignal(options?.signal);
       try {
+        const requestedActions = this.actionsForSqlBatch(statements);
         const response = await this.invokeSQL(
           dbName,
-          this.actionsForSqlBatch(statements),
+          requestedActions,
           { action: "batch", statements },
-          options?.signal
+          request.signal
         );
         if (!response.ok) {
-          return this.handleErrorResponse(response, "batch");
+          return this.handleErrorResponse(response, "batch", dbName, requestedActions);
         }
         const data = await response.json();
         return ok(data);
       } catch (error) {
         return err(wrapError("sql", error));
+      } finally {
+        request.dispose();
       }
     });
   }
@@ -2729,20 +3293,23 @@ var SQLService = class extends BaseService {
       if (!this.requireAuth()) {
         return err(authRequiredError("sql"));
       }
+      const request = this.createRequestSignal(options?.signal);
       try {
         const response = await this.invokeSQL(
           dbName,
           SQLAction.WRITE,
           { action: "execute_statement", name, params: params ?? [] },
-          options?.signal
+          request.signal
         );
         if (!response.ok) {
-          return this.handleErrorResponse(response, "executeStatement");
+          return this.handleErrorResponse(response, "executeStatement", dbName, [SQLAction.WRITE]);
         }
         const data = await response.json();
         return ok(data);
       } catch (error) {
         return err(wrapError("sql", error));
+      } finally {
+        request.dispose();
       }
     });
   }
@@ -2751,15 +3318,16 @@ var SQLService = class extends BaseService {
       if (!this.requireAuth()) {
         return err(authRequiredError("sql"));
       }
+      const request = this.createRequestSignal(options?.signal);
       try {
         const response = await this.invokeSQL(
           dbName,
           SQLAction.READ,
           { action: "export" },
-          options?.signal
+          request.signal
         );
         if (!response.ok) {
-          return this.handleErrorResponse(response, "export");
+          return this.handleErrorResponse(response, "export", dbName, [SQLAction.READ]);
         }
         const resp = response;
         if (typeof resp.blob === "function") {
@@ -2770,26 +3338,31 @@ var SQLService = class extends BaseService {
         return ok(text);
       } catch (error) {
         return err(wrapError("sql", error));
+      } finally {
+        request.dispose();
       }
     });
   }
   async applyMigrationsOnDbUnlocked(dbName, options) {
     return this.withTelemetry("migrations.apply", dbName, async () => {
-      const created = await this.ensureMigrationsTable(dbName, options.signal);
-      if (!created.ok) return created;
       const listed = await this.queryOnDb(
         dbName,
         `SELECT id FROM ${MIGRATIONS_TABLE} WHERE namespace = ? ORDER BY applied_at, id`,
         [options.namespace],
         { signal: options.signal }
       );
-      if (!listed.ok) return listed;
+      const tableMissing = !listed.ok && (listed.error.code === ErrorCodes.SQL_DATABASE_NOT_FOUND || isMissingTableError(listed.error.message));
+      if (!listed.ok && !tableMissing) return listed;
       const appliedIds = new Set(
-        listed.data.rows.map((row) => rowValue(row, 0)).filter((id) => typeof id === "string")
+        (listed.ok ? listed.data.rows : []).map((row) => rowValue(row, 0)).filter((id) => typeof id === "string")
       );
       const skipped = options.migrations.filter((migration) => appliedIds.has(migration.id)).map((migration) => migration.id);
       const pending = options.migrations.filter((migration) => !appliedIds.has(migration.id));
       const applied = [];
+      if (pending.length > 0 && tableMissing) {
+        const created = await this.ensureMigrationsTable(dbName, options.signal);
+        if (!created.ok) return created;
+      }
       for (const migration of pending) {
         const result = await this.applyOneMigration(dbName, options.namespace, migration, options.signal);
         if (!result.ok) return result;
@@ -2857,7 +3430,7 @@ var SQLService = class extends BaseService {
         "Content-Type": "application/json"
       },
       body: JSON.stringify(body),
-      signal: this.combineSignals(signal)
+      signal
     });
   }
   actionForSql(sql, fallback) {
@@ -2890,8 +3463,12 @@ var SQLService = class extends BaseService {
       }))
     );
   }
-  async handleErrorResponse(response, operation) {
+  async handleErrorResponse(response, operation, dbName, requestedActions) {
     const errorText = await response.text();
+    const meta = responseErrorMeta(response.status, response.statusText, errorText);
+    if (response.status === 402) {
+      return err(storageRejectionError("sql", 402, meta, errorText));
+    }
     const errorBody = parseServiceErrorBody(errorText);
     const errorCode = this.mapHttpStatusToErrorCode(
       response.status,
@@ -2904,11 +3481,12 @@ var SQLService = class extends BaseService {
       errorText,
       errorBody
     );
-    const meta = responseErrorMeta(response.status, response.statusText, errorText);
     if (response.status === 401) {
-      const { resource, action } = parseAuthError(errorText);
-      if (action) meta.requiredAction = action;
-      if (resource) meta.resource = resource;
+      const { action } = parseAuthError(errorText);
+      if (action && requestedActions.includes(action)) {
+        meta.requiredAction = action;
+        meta.resource = `${this.context.session.spaceId}/sql/${dbName}`;
+      }
     }
     return err(
       serviceError(errorCode, message, "sql", { meta })
@@ -3005,6 +3583,9 @@ function serializeSqlValues(values) {
     (value) => value instanceof Uint8Array ? Array.from(value) : value
   );
 }
+function isMissingTableError(message) {
+  return /no such table/i.test(message);
+}
 function migrationKey(namespace, id) {
   return `${encodeURIComponent(namespace)}:${encodeURIComponent(id)}`;
 }
@@ -3113,12 +3694,13 @@ var DuckDbService = class extends BaseService {
       if (!this.requireAuth()) {
         return err(authRequiredError("duckdb"));
       }
+      const request = this.createRequestSignal(options?.signal);
       try {
         const response = await this.invokeDuckDb(
           dbName,
           DuckDbAction.READ,
           { action: "query", sql, params: params ?? [] },
-          options?.signal
+          request.signal
         );
         if (!response.ok) {
           return this.handleErrorResponse(response, "query");
@@ -3127,6 +3709,8 @@ var DuckDbService = class extends BaseService {
         return ok(data);
       } catch (error) {
         return err(wrapError("duckdb", error));
+      } finally {
+        request.dispose();
       }
     });
   }
@@ -3135,12 +3719,13 @@ var DuckDbService = class extends BaseService {
       if (!this.requireAuth()) {
         return err(authRequiredError("duckdb"));
       }
+      const request = this.createRequestSignal(options?.signal);
       try {
         const response = await this.invokeDuckDb(
           dbName,
           DuckDbAction.READ,
           { action: "query", sql, params: params ?? [] },
-          options?.signal,
+          request.signal,
           { Accept: "application/vnd.apache.arrow.stream" }
         );
         if (!response.ok) {
@@ -3150,6 +3735,8 @@ var DuckDbService = class extends BaseService {
         return ok(buffer);
       } catch (error) {
         return err(wrapError("duckdb", error));
+      } finally {
+        request.dispose();
       }
     });
   }
@@ -3158,6 +3745,7 @@ var DuckDbService = class extends BaseService {
       if (!this.requireAuth()) {
         return err(authRequiredError("duckdb"));
       }
+      const request = this.createRequestSignal(options?.signal);
       try {
         const body = {
           action: "execute",
@@ -3171,7 +3759,7 @@ var DuckDbService = class extends BaseService {
           dbName,
           DuckDbAction.WRITE,
           body,
-          options?.signal
+          request.signal
         );
         if (!response.ok) {
           return this.handleErrorResponse(response, "execute");
@@ -3180,6 +3768,8 @@ var DuckDbService = class extends BaseService {
         return ok(data);
       } catch (error) {
         return err(wrapError("duckdb", error));
+      } finally {
+        request.dispose();
       }
     });
   }
@@ -3188,6 +3778,7 @@ var DuckDbService = class extends BaseService {
       if (!this.requireAuth()) {
         return err(authRequiredError("duckdb"));
       }
+      const request = this.createRequestSignal(options?.signal);
       try {
         const body = {
           action: "batch",
@@ -3200,7 +3791,7 @@ var DuckDbService = class extends BaseService {
           dbName,
           DuckDbAction.WRITE,
           body,
-          options?.signal
+          request.signal
         );
         if (!response.ok) {
           return this.handleErrorResponse(response, "batch");
@@ -3209,6 +3800,8 @@ var DuckDbService = class extends BaseService {
         return ok(data);
       } catch (error) {
         return err(wrapError("duckdb", error));
+      } finally {
+        request.dispose();
       }
     });
   }
@@ -3217,12 +3810,13 @@ var DuckDbService = class extends BaseService {
       if (!this.requireAuth()) {
         return err(authRequiredError("duckdb"));
       }
+      const request = this.createRequestSignal(options?.signal);
       try {
         const response = await this.invokeDuckDb(
           dbName,
           DuckDbAction.WRITE,
           { action: "executeStatement", name, params: params ?? [] },
-          options?.signal
+          request.signal
         );
         if (!response.ok) {
           return this.handleErrorResponse(response, "executeStatement");
@@ -3231,6 +3825,8 @@ var DuckDbService = class extends BaseService {
         return ok(data);
       } catch (error) {
         return err(wrapError("duckdb", error));
+      } finally {
+        request.dispose();
       }
     });
   }
@@ -3239,12 +3835,13 @@ var DuckDbService = class extends BaseService {
       if (!this.requireAuth()) {
         return err(authRequiredError("duckdb"));
       }
+      const request = this.createRequestSignal(options?.signal);
       try {
         const response = await this.invokeDuckDb(
           dbName,
           DuckDbAction.READ,
           { action: "describe" },
-          options?.signal
+          request.signal
         );
         if (!response.ok) {
           return this.handleErrorResponse(response, "describe");
@@ -3253,6 +3850,8 @@ var DuckDbService = class extends BaseService {
         return ok(data);
       } catch (error) {
         return err(wrapError("duckdb", error));
+      } finally {
+        request.dispose();
       }
     });
   }
@@ -3261,12 +3860,13 @@ var DuckDbService = class extends BaseService {
       if (!this.requireAuth()) {
         return err(authRequiredError("duckdb"));
       }
+      const request = this.createRequestSignal(options?.signal);
       try {
         const response = await this.invokeDuckDb(
           dbName,
           DuckDbAction.EXPORT,
           { action: "export" },
-          options?.signal
+          request.signal
         );
         if (!response.ok) {
           return this.handleErrorResponse(response, "export");
@@ -3275,6 +3875,8 @@ var DuckDbService = class extends BaseService {
         return ok(blob);
       } catch (error) {
         return err(wrapError("duckdb", error));
+      } finally {
+        request.dispose();
       }
     });
   }
@@ -3283,6 +3885,7 @@ var DuckDbService = class extends BaseService {
       if (!this.requireAuth()) {
         return err(authRequiredError("duckdb"));
       }
+      const request = this.createRequestSignal(options?.signal);
       try {
         const session = this.context.session;
         const headers = this.context.invoke(
@@ -3298,7 +3901,7 @@ var DuckDbService = class extends BaseService {
             "Content-Type": "application/x-duckdb"
           },
           body: new Blob([data]),
-          signal: this.combineSignals(options?.signal)
+          signal: request.signal
         });
         if (!response.ok) {
           return this.handleErrorResponse(response, "import");
@@ -3306,6 +3909,8 @@ var DuckDbService = class extends BaseService {
         return ok(void 0);
       } catch (error) {
         return err(wrapError("duckdb", error));
+      } finally {
+        request.dispose();
       }
     });
   }
@@ -3321,11 +3926,15 @@ var DuckDbService = class extends BaseService {
         ...extraHeaders
       },
       body: JSON.stringify(body),
-      signal: this.combineSignals(signal)
+      signal
     });
   }
   async handleErrorResponse(response, operation) {
     const errorText = await response.text();
+    const meta = responseErrorMeta(response.status, response.statusText, errorText);
+    if (response.status === 402) {
+      return err(storageRejectionError("duckdb", 402, meta, errorText));
+    }
     const errorBody = parseServiceErrorBody(errorText);
     const errorCode = this.mapHttpStatusToErrorCode(
       response.status,
@@ -3338,7 +3947,6 @@ var DuckDbService = class extends BaseService {
       errorText,
       errorBody
     );
-    const meta = responseErrorMeta(response.status, response.statusText, errorText);
     if (response.status === 401) {
       const { resource, action } = parseAuthError(errorText);
       if (action) meta.requiredAction = action;
@@ -3837,10 +4445,14 @@ async function responseError(service, message, response) {
     }
   } catch {
   }
-  return wrapError(
+  const error = wrapError(
     service,
     new Error(`${message}: ${response.status} ${detail}`)
   );
+  return {
+    ...error,
+    meta: { ...error.meta, status: response.status, statusText: response.statusText }
+  };
 }
 function isAbortError(error) {
   return error instanceof DOMException && error.name === "AbortError";
@@ -4306,6 +4918,9 @@ function defaultVaultMessage(input) {
       return input.message ?? `Public key not found for ${input.did}`;
     case "STORAGE_ERROR":
       return input.message ?? input.cause.message;
+    case "STORAGE_QUOTA_EXCEEDED":
+    case "STORAGE_LIMIT_REACHED":
+      return input.message;
   }
 }
 function vaultError(input) {
@@ -4316,6 +4931,15 @@ function vaultError(input) {
   };
   return { ok: false, 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 });
+  }
+  return vaultError({
+    code: "STORAGE_ERROR",
+    cause: new Error(`${context}: ${error.message}`)
+  });
+}
 var DataVaultService = class extends BaseService {
   /**
    * Create a new DataVaultService instance.
@@ -4598,12 +5222,7 @@ var DataVaultService = class extends BaseService {
         JSON.stringify(envelopeResult.data)
       );
       if (!valuePutResult.ok) {
-        return vaultError({
-          code: "STORAGE_ERROR",
-          cause: new Error(
-            `Failed to store encrypted value: ${valuePutResult.error.message}`
-          )
-        });
+        return kvWriteError("Failed to store encrypted value", valuePutResult.error);
       }
       return { ok: true, data: void 0 };
     } catch (error) {
@@ -4821,12 +5440,7 @@ var DataVaultService = class extends BaseService {
           keyPayload
         );
         if (!keyPutResult.ok) {
-          return vaultError({
-            code: "STORAGE_ERROR",
-            cause: new Error(
-              `Failed to store key blob: ${keyPutResult.error.message}`
-            )
-          });
+          return kvWriteError("Failed to store key blob", keyPutResult.error);
         }
         const valuePayload = JSON.stringify({
           data: base64Encode(encrypted),
@@ -4837,12 +5451,7 @@ var DataVaultService = class extends BaseService {
           valuePayload
         );
         if (!valuePutResult.ok) {
-          return vaultError({
-            code: "STORAGE_ERROR",
-            cause: new Error(
-              `Failed to store encrypted value: ${valuePutResult.error.message}`
-            )
-          });
+          return kvWriteError("Failed to store encrypted value", valuePutResult.error);
         }
         return ok(void 0);
       } catch (error) {
@@ -5173,12 +5782,7 @@ var DataVaultService = class extends BaseService {
           grantPayload
         );
         if (!grantPutResult.ok) {
-          return vaultError({
-            code: "STORAGE_ERROR",
-            cause: new Error(
-              `Failed to store grant: ${grantPutResult.error.message}`
-            )
-          });
+          return kvWriteError("Failed to store grant", grantPutResult.error);
         }
         return ok(void 0);
       } catch (error) {
@@ -5523,12 +6127,7 @@ var DataVaultService = class extends BaseService {
           keyPayload
         );
         if (!keyPutResult.ok) {
-          return vaultError({
-            code: "STORAGE_ERROR",
-            cause: new Error(
-              `Failed to store rotated key blob: ${keyPutResult.error.message}`
-            )
-          });
+          return kvWriteError("Failed to store rotated key blob", keyPutResult.error);
         }
         const valuePayload = JSON.stringify({
           data: base64Encode(encrypted),
@@ -5539,12 +6138,7 @@ var DataVaultService = class extends BaseService {
           valuePayload
         );
         if (!valuePutResult.ok) {
-          return vaultError({
-            code: "STORAGE_ERROR",
-            cause: new Error(
-              `Failed to store re-encrypted value: ${valuePutResult.error.message}`
-            )
-          });
+          return kvWriteError("Failed to store re-encrypted value", valuePutResult.error);
         }
         for (const did of remainingGrantees) {
           const grantResult = await this.reencrypt(key, did);
@@ -5753,6 +6347,7 @@ var SecretsService = class {
   }
   async listAll() {
     const entries = /* @__PURE__ */ new Map();
+    const seenCursors = /* @__PURE__ */ new Set();
     let cursor;
     do {
       const result = await this.vault.listPage({
@@ -5775,6 +6370,14 @@ var SecretsService = class {
           "Secret catalog listing was truncated without a continuation cursor."
         );
       }
+      if (cursor !== void 0) {
+        if (seenCursors.has(cursor)) {
+          return invalidSecretInput(
+            "Secret catalog listing repeated a continuation cursor; the node does not support paged KV lists."
+          );
+        }
+        seenCursors.add(cursor);
+      }
     } while (cursor !== void 0);
     return {
       ok: true,
@@ -5895,103 +6498,6 @@ function canonicalHashHex(sha256, value) {
   return hexEncode2(sha256(utf8Encode(canonical)));
 }
 
-// src/encryption/networkId.ts
-var URN_PREFIX = "urn:tinycloud:encryption:";
-var NETWORK_NAME_RE = /^[a-z0-9][a-z0-9-]*$/;
-var PKH_EIP155_DID_RE = /^did:pkh:eip155:(\d+):(0x[a-fA-F0-9]{40})$/;
-var NetworkIdError = class extends Error {
-  constructor(message) {
-    super(message);
-    this.name = "NetworkIdError";
-  }
-};
-function parseNetworkId(networkId) {
-  if (typeof networkId !== "string" || networkId.length === 0) {
-    throw new NetworkIdError("networkId must be a non-empty string");
-  }
-  if (!networkId.startsWith(URN_PREFIX)) {
-    throw new NetworkIdError(
-      `networkId must start with ${URN_PREFIX} (got ${JSON.stringify(networkId)})`
-    );
-  }
-  const body = networkId.slice(URN_PREFIX.length);
-  const lastColon = body.lastIndexOf(":");
-  if (lastColon <= 0 || lastColon === body.length - 1) {
-    throw new NetworkIdError(
-      `networkId missing ownerDid or name segment (got ${JSON.stringify(networkId)})`
-    );
-  }
-  const ownerDid = body.slice(0, lastColon);
-  const name = body.slice(lastColon + 1);
-  if (!ownerDid.startsWith("did:")) {
-    throw new NetworkIdError(
-      `networkId ownerDid must be a DID (got ${JSON.stringify(ownerDid)})`
-    );
-  }
-  const didParts = ownerDid.split(":");
-  if (didParts.length < 3 || didParts.some((p) => p.length === 0)) {
-    throw new NetworkIdError(
-      `networkId ownerDid is not a well-formed DID (got ${JSON.stringify(ownerDid)})`
-    );
-  }
-  if (!NETWORK_NAME_RE.test(name)) {
-    throw new NetworkIdError(
-      `networkId name ${JSON.stringify(name)} must match ${NETWORK_NAME_RE.source}`
-    );
-  }
-  return { networkId, ownerDid, name };
-}
-function buildNetworkId(ownerDid, name) {
-  if (typeof ownerDid !== "string" || !ownerDid.startsWith("did:")) {
-    throw new NetworkIdError("ownerDid must be a DID");
-  }
-  if (typeof name !== "string" || !NETWORK_NAME_RE.test(name)) {
-    throw new NetworkIdError(
-      `network name ${JSON.stringify(name)} must match ${NETWORK_NAME_RE.source}`
-    );
-  }
-  const networkId = `${URN_PREFIX}${ownerDid}:${name}`;
-  parseNetworkId(networkId);
-  return networkId;
-}
-function isNetworkId(networkId) {
-  if (typeof networkId !== "string") {
-    return false;
-  }
-  try {
-    parseNetworkId(networkId);
-    return true;
-  } catch {
-    return false;
-  }
-}
-function parsePkhOwnerDid(ownerDid) {
-  const match = ownerDid.match(PKH_EIP155_DID_RE);
-  if (!match) return null;
-  return {
-    chainId: match[1],
-    address: match[2].toLowerCase()
-  };
-}
-function ownerDidMatches(a, b) {
-  const aPkh = parsePkhOwnerDid(a);
-  const bPkh = parsePkhOwnerDid(b);
-  if (aPkh && bPkh) {
-    return aPkh.chainId === bPkh.chainId && aPkh.address === bPkh.address;
-  }
-  return a === b;
-}
-function networkDiscoveryKey(name) {
-  if (!NETWORK_NAME_RE.test(name)) {
-    throw new NetworkIdError(
-      `network name ${JSON.stringify(name)} must match ${NETWORK_NAME_RE.source}`
-    );
-  }
-  return `.well-known/encryption/network/${name}`;
-}
-var ENCRYPTION_NETWORK_URN_PREFIX = URN_PREFIX;
-var NETWORK_NAME_PATTERN = NETWORK_NAME_RE;
-
 // src/encryption/types.ts
 var DEFAULT_ENCRYPTION_ALG = "x25519-aes256gcm/v1";
 var ENVELOPE_VERSION = 1;
@@ -6873,6 +7379,8 @@ export {
   SQLAction,
   SQLMigrations,
   SQLService,
+  STORAGE_FULL_MESSAGE,
+  STORAGE_WRITE_TOO_LARGE_MESSAGE,
   SecretsService,
   ServiceContext,
   ServiceErrorEventSchema,
@@ -6891,6 +7399,7 @@ export {
   authExpiredError,
   authRequiredError,
   authUnauthorizedError,
+  authorizationVerdictOf,
   base64Decode2 as base64Decode,
   base64Encode2 as base64Encode,
   buildCanonicalDecryptRequest,
@@ -6924,22 +7433,26 @@ export {
   hexEncode2 as hexEncode,
   installTinyCloudDebugGlobals,
   isNetworkId,
+  isStorageFullError,
   networkDiscoveryKey,
   networkError,
   notFoundError,
   ok,
   openWrappedKey,
   parseAuthError,
+  parseCapabilityResource,
   parseNetworkId,
   parsePermissionHint,
   parsePermissionHintFromErrorText,
   parseSecretCatalogKey,
+  parseStorageQuotaBytes,
   permissionDeniedError,
   resolveSecretListPrefix,
   resolveSecretPath,
   serviceError,
   storageLimitReachedError,
   storageQuotaExceededError,
+  storageRejectionError,
   timeoutError,
   tinyCloudDebugLogger,
   utf8Decode,
@@ -6953,6 +7466,7 @@ export {
   validateServiceResponseEvent,
   validateServiceSession,
   validateTelemetrySpanEvent,
+  validatedCapabilityOf,
   verifyDecryptResponse,
   wrapError
 };