@tinycloud/sdk-services 2.7.0-beta.3 → 2.7.0

package/dist/index.cjs

@@ -18,8 +18,8 @@ var __copyProps = (to, from, except, desc) => {
 var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
 
 // src/index.ts
-var index_exports = {};
-__export(index_exports, {
+var src_exports = {};
+__export(src_exports, {
   BaseService: () => BaseService,
   DECRYPT_ACTION: () => DECRYPT_ACTION,
   DECRYPT_FACT_TYPE: () => DECRYPT_FACT_TYPE,
@@ -29,6 +29,7 @@ __export(index_exports, {
   DEFAULT_SIGNED_READ_URL_EXPIRY_MS: () => DEFAULT_SIGNED_READ_URL_EXPIRY_MS,
   DataVaultService: () => DataVaultService,
   DatabaseHandle: () => DatabaseHandle,
+  DecryptTransportResponseError: () => import_decrypt_transport_response_error3.DecryptTransportResponseError,
   DuckDbAction: () => DuckDbAction,
   DuckDbDatabaseHandle: () => DuckDbDatabaseHandle,
   DuckDbService: () => DuckDbService,
@@ -112,6 +113,8 @@ __export(index_exports, {
   openWrappedKey: () => openWrappedKey,
   parseAuthError: () => parseAuthError,
   parseNetworkId: () => parseNetworkId,
+  parsePermissionHint: () => parsePermissionHint,
+  parsePermissionHintFromErrorText: () => parsePermissionHintFromErrorText,
   permissionDeniedError: () => permissionDeniedError,
   resolveSecretListPrefix: () => resolveSecretListPrefix,
   resolveSecretPath: () => resolveSecretPath,
@@ -134,7 +137,7 @@ __export(index_exports, {
   verifyDecryptResponse: () => verifyDecryptResponse,
   wrapError: () => wrapError
 });
-module.exports = __toCommonJS(index_exports);
+module.exports = __toCommonJS(src_exports);
 
 // src/types.ts
 var ErrorCodes = {
@@ -205,6 +208,63 @@ function serviceError(code, message, service, options) {
   };
 }
 
+// src/diagnostics.ts
+var REDACTED = "[REDACTED]";
+var SAFE_NUMBER_FIELDS = /* @__PURE__ */ new Set([
+  "duration",
+  "durationMs",
+  "endedAt",
+  "startedAt",
+  "status",
+  "timestamp"
+]);
+var SAFE_BOOLEAN_FIELDS = /* @__PURE__ */ new Set(["authenticated", "ok", "persisted"]);
+function finiteNumber(value) {
+  return typeof value === "number" && Number.isFinite(value) ? value : void 0;
+}
+function isBinaryData(value) {
+  try {
+    return Array.isArray(value) || ArrayBuffer.isView(value) || value instanceof ArrayBuffer;
+  } catch {
+    return true;
+  }
+}
+function read(value, key) {
+  try {
+    return value[key];
+  } catch {
+    return REDACTED;
+  }
+}
+function projectDiagnosticError(error) {
+  if (typeof error !== "object" || error === null) return {};
+  const status = finiteNumber(read(error, "status"));
+  return status !== void 0 && status >= 100 && status <= 599 ? { status } : {};
+}
+function projectDiagnosticData(value) {
+  if (value === null || value === void 0) return value;
+  if (typeof value !== "object") return REDACTED;
+  try {
+    if (isBinaryData(value)) return REDACTED;
+    const projected = {};
+    for (const key of SAFE_NUMBER_FIELDS) {
+      const number = finiteNumber(read(value, key));
+      if (number !== void 0) projected[key] = number;
+    }
+    for (const key of SAFE_BOOLEAN_FIELDS) {
+      const boolean = read(value, key);
+      if (typeof boolean === "boolean") projected[key] = boolean;
+    }
+    const url = read(value, "url");
+    if (url !== void 0) projected.url = REDACTED;
+    const error = read(value, "error");
+    if (error !== void 0) projected.error = projectDiagnosticError(error);
+    return projected;
+  } catch {
+    return REDACTED;
+  }
+}
+
 // src/debug.ts
 var DEBUG_FLAG = "TinyCloud_debug";
 var MAX_EVENTS = 1e3;
@@ -363,6 +423,8 @@ var TinyCloudDebugLogger = class {
   record(event) {
     const debugEvent = {
       ...event,
+      ...event.data === void 0 ? {} : { data: projectDiagnosticData(event.data) },
+      ...event.message === void 0 ? {} : { message: "[REDACTED]" },
       sequence: ++this.sequence
     };
     this.events.push(debugEvent);
@@ -642,6 +704,7 @@ var ServiceContext = class {
     this._services = /* @__PURE__ */ new Map();
     this._eventHandlers = /* @__PURE__ */ new Map();
     this._abortController = new AbortController();
+    this._retired = false;
     this._invoke = this.wrapInvoke(config.invoke);
     this._invokeAny = config.invokeAny ? this.wrapInvokeAny(config.invokeAny) : void 0;
     this._fetch = this.wrapFetch(config.fetch ?? globalThis.fetch.bind(globalThis));
@@ -661,13 +724,13 @@ var ServiceContext = class {
    * Get the current session.
    */
   get session() {
-    return this._session;
+    return this._retired ? null : this._session;
   }
   /**
    * Check if the context has an authenticated session.
    */
   get isAuthenticated() {
-    return this._session !== null;
+    return !this._retired && this._session !== null;
   }
   /**
    * Update the session and notify all registered services.
@@ -675,6 +738,7 @@ var ServiceContext = class {
    * @param session - New session or null to clear
    */
   setSession(session) {
+    this.assertActive();
     this._session = session;
     this.emit("session.changed", { authenticated: session !== null });
     for (const service of this._services.values()) {
@@ -688,24 +752,28 @@ var ServiceContext = class {
    * Get the invoke function for WASM operations.
    */
   get invoke() {
+    this.assertActive();
     return this._invoke;
   }
   /**
    * Get the multi-resource invoke function when available.
    */
   get invokeAny() {
+    this.assertActive();
     return this._invokeAny;
   }
   /**
    * Get the fetch function for HTTP requests.
    */
   get fetch() {
+    this.assertActive();
     return this._fetch;
   }
   /**
    * Get the list of TinyCloud host URLs.
    */
   get hosts() {
+    this.assertActive();
     return this._hosts;
   }
   // ============================================================
@@ -750,7 +818,7 @@ var ServiceContext = class {
     tinyCloudDebugLogger.log(event, data);
     if (this._telemetryEnabled && this._telemetryHandler) {
       try {
-        this._telemetryHandler(event, data);
+        this._telemetryHandler(event, projectDiagnosticData(data));
       } catch (error) {
         console.error(`Error in telemetry handler for "${event}":`, error);
       }
@@ -809,21 +877,45 @@ var ServiceContext = class {
   get abortSignal() {
     return this._abortController.signal;
   }
+  /**
+   * Permanently retire this graph after its owner installs a replacement.
+   * Unlike `abort()`, retirement never creates a fresh controller, so captured
+   * services cannot resume calls under a superseded session.
+   */
+  retire() {
+    if (this._retired) return;
+    this._retired = true;
+    this._session = null;
+    this._abortController.abort();
+    for (const service of this._services.values()) {
+      try {
+        service.onSignOut();
+      } catch (error) {
+        console.error("Error retiring service:", error);
+      }
+    }
+  }
   /**
    * Abort all pending operations and notify services.
    * Creates a new AbortController for future operations.
    */
   abort() {
+    if (this._retired) return;
     this._abortController.abort();
     this._abortController = new AbortController();
     for (const service of this._services.values()) {
-      service.onSignOut();
+      try {
+        service.onSignOut();
+      } catch (error) {
+        console.error("Error signing out service:", error);
+      }
     }
   }
   /**
    * Sign out - abort operations and clear session.
    */
   signOut() {
+    if (this._retired) return;
     this.abort();
     this.setSession(null);
     this.emit("session.expired", {});
@@ -839,6 +931,7 @@ var ServiceContext = class {
   }
   wrapInvoke(invoke) {
     return (session, service, path, action, facts) => {
+      this.assertActive();
       if (!tinyCloudDebugLogger.isEnabled()) {
         return invoke(session, service, path, action, facts);
       }
@@ -858,8 +951,14 @@ var ServiceContext = class {
       }
     };
   }
+  assertActive() {
+    if (this._retired) {
+      throw new Error("Service graph has been retired by session replacement.");
+    }
+  }
   wrapInvokeAny(invokeAny) {
     return (session, entries, facts) => {
+      this.assertActive();
       if (!tinyCloudDebugLogger.isEnabled()) {
         return invokeAny(session, entries, facts);
       }
@@ -879,20 +978,25 @@ var ServiceContext = class {
   }
   wrapFetch(fetchFn) {
     return async (url, init) => {
+      this.assertActive();
+      const request = {
+        ...init,
+        signal: this.combineSignals(init?.signal)
+      };
       if (!tinyCloudDebugLogger.isEnabled()) {
-        return fetchFn(url, init);
+        return fetchFn(url, request);
       }
       const timer = tinyCloudDebugLogger.startTimer("sdk.fetch", {
         url,
-        method: init?.method ?? "GET",
-        init
+        method: request.method ?? "GET",
+        init: request
       });
       try {
-        const response = await fetchFn(url, init);
+        const response = await fetchFn(url, request);
         timer.stop({
           ok: response.ok,
           url,
-          method: init?.method ?? "GET",
+          method: request.method ?? "GET",
           status: response.status,
           statusText: response.statusText
         });
@@ -901,16 +1005,70 @@ var ServiceContext = class {
         timer.stop({
           ok: false,
           url,
-          method: init?.method ?? "GET",
+          method: request.method ?? "GET",
           error
         });
         throw error;
       }
     };
   }
+  combineSignals(signal) {
+    if (!signal) return this._abortController.signal;
+    const combined = new AbortController();
+    const abort = (source) => combined.abort(source.reason);
+    if (signal.aborted) {
+      abort(signal);
+    } else if (this._abortController.signal.aborted) {
+      abort(this._abortController.signal);
+    } else {
+      signal.addEventListener("abort", () => abort(signal), { once: true });
+      this._abortController.signal.addEventListener(
+        "abort",
+        () => abort(this._abortController.signal),
+        { once: true }
+      );
+    }
+    return combined.signal;
+  }
 };
 
 // src/errors.ts
+function parsePermissionHint(value) {
+  if (typeof value !== "object" || value === null || Array.isArray(value)) return void 0;
+  const candidate = value;
+  const keys = Object.keys(candidate).sort();
+  if (keys.some((key) => !["actions", "path", "service", "space"].includes(key))) return void 0;
+  if (candidate.service !== "tinycloud.kv" && candidate.service !== "tinycloud.encryption") return void 0;
+  if (typeof candidate.path !== "string" || candidate.path.length === 0 || candidate.path.includes("*")) return void 0;
+  if (candidate.service === "tinycloud.kv" && (typeof candidate.space !== "string" || candidate.space.length === 0 || !candidate.path.startsWith("vault/") || candidate.path.endsWith("/"))) {
+    return void 0;
+  }
+  if (candidate.service === "tinycloud.encryption" && (candidate.space !== void 0 || !candidate.path.startsWith("urn:tinycloud:encryption:") || candidate.path.endsWith(":"))) {
+    return void 0;
+  }
+  if (!Array.isArray(candidate.actions) || candidate.actions.length !== 1 || typeof candidate.actions[0] !== "string" || candidate.actions[0].includes("*")) return void 0;
+  const expectedAction = candidate.service === "tinycloud.kv" ? "tinycloud.kv/get" : "tinycloud.encryption/decrypt";
+  if (candidate.actions[0] !== expectedAction) return void 0;
+  const space = typeof candidate.space === "string" ? candidate.space : void 0;
+  return {
+    service: candidate.service,
+    ...space === void 0 ? {} : { space },
+    path: candidate.path,
+    actions: [candidate.actions[0]]
+  };
+}
+function parsePermissionHintFromErrorText(text) {
+  try {
+    const parsed = JSON.parse(text);
+    if (typeof parsed !== "object" || parsed === null) return void 0;
+    const root = parsed;
+    const nested = root.error;
+    const nestedRecord = typeof nested === "object" && nested !== null ? nested : void 0;
+    return parsePermissionHint(root.permissionHint) ?? parsePermissionHint(nestedRecord?.permissionHint);
+  } catch {
+    return void 0;
+  }
+}
 function authRequiredError(service) {
   return {
     code: ErrorCodes.AUTH_REQUIRED,
@@ -1061,7 +1219,7 @@ var BaseService = class {
    * Combines the service-level abort with context-level abort.
    */
   get abortSignal() {
-    return this.abortController.signal;
+    return this.combineSignals();
   }
   /**
    * Check if the service is authenticated.
@@ -1177,7 +1335,11 @@ var BaseService = class {
    */
   combineSignals(...signals) {
     const controller = new AbortController();
-    const allSignals = [this.abortSignal, ...signals.filter(Boolean)];
+    const allSignals = [
+      this.abortController.signal,
+      this.context?.abortSignal,
+      ...signals.filter(Boolean)
+    ].filter(Boolean);
     for (const signal of allSignals) {
       if (signal.aborted) {
         controller.abort(signal.reason);
@@ -1650,13 +1812,15 @@ var KVService = class extends BaseService {
           options?.signal
         );
         if (!response.ok) {
-          if (response.status === 401) {
+          if (response.status === 401 || response.status === 403) {
             const errorText2 = await response.text();
             const { resource, action } = parseAuthError(errorText2);
+            const permissionHint = parsePermissionHintFromErrorText(errorText2);
             return err(authUnauthorizedError("kv", errorText2, {
               status: response.status,
               ...action && { requiredAction: action },
-              ...resource && { resource }
+              ...resource && { resource },
+              ...permissionHint === void 0 ? {} : { permissionHint }
             }));
           }
           if (response.status === 404) {
@@ -3882,6 +4046,9 @@ function unwrapKVData(value) {
   }
   return value;
 }
+function hasHttpResponse(error) {
+  return typeof error.meta?.status === "number";
+}
 function isUnlockSigner(signer) {
   return typeof signer === "object" && signer !== null && typeof signer.signMessage === "function";
 }
@@ -4255,6 +4422,80 @@ var DataVaultService = class extends BaseService {
       });
     }
   }
+  /**
+   * Read a network-encrypted entry while preserving safe failure phases.
+   *
+   * Unlike {@link getNetworkEncrypted}, this is intentionally message-free so
+   * an operation layer can distinguish an authorized absence from a failed
+   * read without receiving node, envelope, plaintext, or key material.
+   */
+  async readNetworkEncrypted(key, options) {
+    const config = this.networkEncryption;
+    if (!config || !this.requireAuth()) {
+      return { status: "read_failed" };
+    }
+    let valueResult;
+    try {
+      valueResult = await this.tc.kv.get(`vault/${key}`, { raw: true });
+    } catch {
+      return { status: "node_unreachable" };
+    }
+    if (!valueResult.ok) {
+      const permissionHint = parsePermissionHint(valueResult.error.meta?.permissionHint);
+      if (valueResult.error.code === "AUTH_UNAUTHORIZED" && permissionHint !== void 0) {
+        return { status: "permission_required", hint: permissionHint };
+      }
+      if ((valueResult.error.code === "NOT_FOUND" || valueResult.error.code === "KV_NOT_FOUND") && !hasHttpResponse(valueResult.error)) {
+        return { status: "not_found" };
+      }
+      if (valueResult.error.code === "NETWORK_ERROR" || valueResult.error.code === "TIMEOUT" || valueResult.error.code === "ABORTED") {
+        return hasHttpResponse(valueResult.error) ? { status: "read_failed" } : { status: "node_unreachable" };
+      }
+      return { status: "read_failed" };
+    }
+    let envelope;
+    try {
+      const rawEnvelope = unwrapKVData(valueResult.data);
+      envelope = typeof rawEnvelope === "string" ? JSON.parse(rawEnvelope) : rawEnvelope;
+    } catch {
+      return { status: "corrupt_envelope" };
+    }
+    let plaintextResult;
+    try {
+      const proof = await this.decryptCapabilityProof();
+      plaintextResult = await config.service.decryptEnvelope(envelope, proof);
+    } catch {
+      return { status: "decrypt_failed" };
+    }
+    if (!plaintextResult.ok) {
+      const permissionHint = parsePermissionHint(
+        plaintextResult.error.permissionHint
+      );
+      if (plaintextResult.error.code === "DECRYPT_DENIED" && permissionHint !== void 0) {
+        return { status: "permission_required", hint: permissionHint };
+      }
+      if (plaintextResult.error.code === "INVALID_ENVELOPE") {
+        return { status: "corrupt_envelope" };
+      }
+      if (plaintextResult.error.code === "TRANSPORT_ERROR") {
+        return { status: "node_unreachable" };
+      }
+      return { status: "decrypt_failed" };
+    }
+    try {
+      const metadata = envelope.metadata ?? {};
+      const contentType = metadata[VaultHeaders.CONTENT_TYPE] ?? "application/json";
+      const keyId = metadata[VaultHeaders.KEY_ID] ?? envelope.encryptedSymmetricKeyHash.slice(0, 16);
+      const value = this.deserializeValue(
+        plaintextResult.data,
+        contentType,
+        options
+      );
+      return { status: "ok", entry: { value, metadata, keyId } };
+    } catch {
+      return { status: "invalid_payload" };
+    }
+  }
   async headNetworkEncrypted(key) {
     if (!this.requireAuth()) {
       return vaultError({
@@ -6082,6 +6323,8 @@ function openWrappedKey(crypto2, receiverPrivateKey, response) {
 }
 
 // src/encryption/EncryptionService.ts
+var import_decrypt_transport_response_error = require("@tinycloud/sdk-services/internal/decrypt-transport-response-error");
+var import_decrypt_transport_response_error2 = require("@tinycloud/sdk-services/internal/decrypt-transport-response-error");
 function encOk(data) {
   return { ok: true, data };
 }
@@ -6100,17 +6343,20 @@ var EncryptionService = class extends BaseService {
     return this._config.crypto;
   }
   async discoverNetwork(identifier, ownerDid) {
+    this.assertActive();
     const result = await discoverNetwork({
       identifier,
       ...ownerDid !== void 0 ? { ownerDid } : {},
       ...this._config.node !== void 0 ? { node: this._config.node } : {},
       ...this._config.wellKnown !== void 0 ? { wellKnown: this._config.wellKnown } : {}
     });
+    this.assertActive();
     if (!result.ok) return result;
     return encOk(result.data.descriptor);
   }
   async encryptToNetwork(networkId, plaintext, options) {
     try {
+      this.assertActive();
       const discovered = await this.discoverNetwork(networkId);
       if (!discovered.ok) return discovered;
       const usable = ensureNetworkUsableForDecrypt(discovered.data);
@@ -6138,6 +6384,7 @@ var EncryptionService = class extends BaseService {
   }
   async decryptEnvelope(envelope, capabilityProof, options) {
     try {
+      this.assertActive();
       const validated = validateEnvelope(this.crypto, envelope);
       if (!validated.ok) return validated;
       if (options?.aad !== void 0 && validated.data.aad !== base64Encode2(options.aad)) {
@@ -6203,16 +6450,38 @@ var EncryptionService = class extends BaseService {
         facts,
         proof: capabilityProof
       });
-      if (!built.ok) return built;
+      this.assertActive();
+      if (!built.ok) {
+        if (built.error.code !== "TRANSPORT_ERROR") return built;
+        return encErr(
+          encryptionError({
+            code: "INVALID_INPUT",
+            message: "Unable to build decrypt request"
+          })
+        );
+      }
       let response;
       try {
         response = await this._config.transport.postDecrypt({
           targetNode,
           networkId: envelope.networkId,
           authorization: built.data.authorization,
-          canonicalBody: built.data.canonicalBody
+          canonicalBody: built.data.canonicalBody,
+          signal: this.abortSignal
         });
+        this.assertActive();
       } catch (error) {
+        if (error instanceof import_decrypt_transport_response_error.DecryptTransportResponseError) {
+          return encErr(
+            encryptionError(
+              error.status === 401 || error.status === 403 ? {
+                code: "DECRYPT_DENIED",
+                message: "Node denied decrypt request",
+                ...error.permissionHint === void 0 ? {} : { permissionHint: error.permissionHint }
+              } : { code: "INVALID_RESPONSE", message: "Node decrypt request failed" }
+            )
+          );
+        }
         return encErr(
           encryptionError({
             code: "TRANSPORT_ERROR",
@@ -6243,14 +6512,20 @@ var EncryptionService = class extends BaseService {
     } catch (error) {
       return encErr(
         encryptionError({
-          code: "TRANSPORT_ERROR",
-          cause: toError2(error)
+          code: "INVALID_RESPONSE",
+          message: "Local decryption failed"
         })
       );
     }
   }
+  assertActive() {
+    this._config.assertActive?.();
+  }
 };
 EncryptionService.serviceName = "encryption";
+
+// src/encryption/index.ts
+var import_decrypt_transport_response_error3 = require("@tinycloud/sdk-services/internal/decrypt-transport-response-error");
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   BaseService,
@@ -6262,6 +6537,7 @@ EncryptionService.serviceName = "encryption";
   DEFAULT_SIGNED_READ_URL_EXPIRY_MS,
   DataVaultService,
   DatabaseHandle,
+  DecryptTransportResponseError,
   DuckDbAction,
   DuckDbDatabaseHandle,
   DuckDbService,
@@ -6345,6 +6621,8 @@ EncryptionService.serviceName = "encryption";
   openWrappedKey,
   parseAuthError,
   parseNetworkId,
+  parsePermissionHint,
+  parsePermissionHintFromErrorText,
   permissionDeniedError,
   resolveSecretListPrefix,
   resolveSecretPath,