@tinycloud/sdk-services 2.2.0-beta.7 → 2.2.0

package/dist/index.cjs

@@ -21,11 +21,22 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 var index_exports = {};
 __export(index_exports, {
   BaseService: () => BaseService,
+  DECRYPT_ACTION: () => DECRYPT_ACTION,
+  DECRYPT_FACT_TYPE: () => DECRYPT_FACT_TYPE,
+  DECRYPT_RESULT_TYPE: () => DECRYPT_RESULT_TYPE,
+  DEFAULT_ENCRYPTION_ALG: () => DEFAULT_ENCRYPTION_ALG,
+  DEFAULT_KEY_VERSION: () => DEFAULT_KEY_VERSION,
+  DEFAULT_SIGNED_READ_URL_EXPIRY_MS: () => DEFAULT_SIGNED_READ_URL_EXPIRY_MS,
   DataVaultService: () => DataVaultService,
   DatabaseHandle: () => DatabaseHandle,
   DuckDbAction: () => DuckDbAction,
   DuckDbDatabaseHandle: () => DuckDbDatabaseHandle,
   DuckDbService: () => DuckDbService,
+  ENCRYPTION_NETWORK_URN_PREFIX: () => ENCRYPTION_NETWORK_URN_PREFIX,
+  ENCRYPTION_SERVICE: () => ENCRYPTION_SERVICE,
+  ENCRYPTION_SERVICE_SHORT: () => ENCRYPTION_SERVICE_SHORT,
+  ENVELOPE_VERSION: () => ENVELOPE_VERSION,
+  EncryptionService: () => EncryptionService,
   ErrorCodes: () => ErrorCodes,
   GenericKVResponseSchema: () => GenericKVResponseSchema,
   GenericResultSchema: () => GenericResultSchema,
@@ -35,8 +46,11 @@ __export(index_exports, {
   KVListResultSchema: () => KVListResultSchema,
   KVResponseHeadersSchema: () => KVResponseHeadersSchema,
   KVService: () => KVService,
+  NETWORK_NAME_PATTERN: () => NETWORK_NAME_PATTERN,
+  NetworkIdError: () => NetworkIdError,
   PrefixedKVService: () => PrefixedKVService,
   RetryPolicySchema: () => RetryPolicySchema,
+  SECRET_NAME_RE: () => SECRET_NAME_RE,
   SQLAction: () => SQLAction,
   SQLService: () => SQLService,
   SecretsService: () => SecretsService,
@@ -55,21 +69,51 @@ __export(index_exports, {
   authExpiredError: () => authExpiredError,
   authRequiredError: () => authRequiredError,
   authUnauthorizedError: () => authUnauthorizedError,
+  base64Decode: () => base64Decode2,
+  base64Encode: () => base64Encode2,
+  buildCanonicalDecryptRequest: () => buildCanonicalDecryptRequest,
+  buildDecryptAttenuation: () => buildDecryptAttenuation,
+  buildDecryptFacts: () => buildDecryptFacts,
+  buildDecryptInvocation: () => buildDecryptInvocation,
+  buildNetworkId: () => buildNetworkId,
+  canonicalHashHex: () => canonicalHashHex,
+  canonicalSignedResponse: () => canonicalSignedResponse,
+  canonicalizeEncryptionJson: () => canonicalize,
+  canonicalizeSecretScope: () => canonicalizeSecretScope,
+  checkDecryptInvocationInput: () => checkDecryptInvocationInput,
   createKVResponseSchema: () => createKVResponseSchema,
   createResultSchema: () => createResultSchema,
   createVaultCrypto: () => createVaultCrypto,
+  decryptEnvelopeWithKey: () => decryptEnvelopeWithKey,
   defaultRetryPolicy: () => defaultRetryPolicy,
+  deriveSignedReceiverKey: () => deriveSignedReceiverKey,
+  discoverNetwork: () => discoverNetwork,
+  encryptToNetwork: () => encryptToNetwork,
+  encryptionError: () => encryptionError,
+  ensureNetworkUsableForDecrypt: () => ensureNetworkUsableForDecrypt,
   err: () => err,
   errorResult: () => errorResult,
+  generateRandomReceiverKey: () => generateRandomReceiverKey,
+  hexDecode: () => hexDecode,
+  hexEncode: () => hexEncode2,
+  isNetworkId: () => isNetworkId,
+  networkDiscoveryKey: () => networkDiscoveryKey,
   networkError: () => networkError,
   notFoundError: () => notFoundError,
   ok: () => ok,
+  openWrappedKey: () => openWrappedKey,
   parseAuthError: () => parseAuthError,
+  parseNetworkId: () => parseNetworkId,
   permissionDeniedError: () => permissionDeniedError,
+  resolveSecretListPrefix: () => resolveSecretListPrefix,
+  resolveSecretPath: () => resolveSecretPath,
   serviceError: () => serviceError,
   storageLimitReachedError: () => storageLimitReachedError,
   storageQuotaExceededError: () => storageQuotaExceededError,
   timeoutError: () => timeoutError,
+  utf8Decode: () => utf8Decode,
+  utf8Encode: () => utf8Encode,
+  validateEnvelope: () => validateEnvelope,
   validateKVListResponse: () => validateKVListResponse,
   validateKVResponseHeaders: () => validateKVResponseHeaders,
   validateRetryPolicy: () => validateRetryPolicy,
@@ -77,6 +121,7 @@ __export(index_exports, {
   validateServiceRequestEvent: () => validateServiceRequestEvent,
   validateServiceResponseEvent: () => validateServiceResponseEvent,
   validateServiceSession: () => validateServiceSession,
+  verifyDecryptResponse: () => verifyDecryptResponse,
   wrapError: () => wrapError
 });
 module.exports = __toCommonJS(index_exports);
@@ -901,6 +946,13 @@ var PrefixedKVService = class _PrefixedKVService {
     const fullKey = this.getFullKey(key);
     return this._kv.head(fullKey, { ...options, prefix: "" });
   }
+  /**
+   * Create a short-lived signed URL for reading a KV object.
+   */
+  async createSignedReadUrl(key, options) {
+    const fullKey = this.getFullKey(key);
+    return this._kv.createSignedReadUrl(fullKey, { ...options, prefix: "" });
+  }
   /**
    * Create a nested prefix-scoped view.
    */
@@ -912,6 +964,7 @@ var PrefixedKVService = class _PrefixedKVService {
 };
 
 // src/kv/types.ts
+var DEFAULT_SIGNED_READ_URL_EXPIRY_MS = 5 * 60 * 1e3;
 var KVAction = {
   GET: "tinycloud.kv/get",
   PUT: "tinycloud.kv/put",
@@ -996,6 +1049,15 @@ var KVService = class extends BaseService {
   get host() {
     return this.context.hosts[0];
   }
+  withJsonContentType(headers) {
+    if (Array.isArray(headers)) {
+      return [...headers, ["content-type", "application/json"]];
+    }
+    return {
+      ...headers,
+      "content-type": "application/json"
+    };
+  }
   /**
    * Execute an invoke operation.
    *
@@ -1065,6 +1127,48 @@ var KVService = class extends BaseService {
       return text;
     }
   }
+  async createSignedReadUrlError(response, key) {
+    let errorText = response.statusText;
+    try {
+      const text = await response.text();
+      if (text) {
+        errorText = text;
+      }
+    } 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 }
+      }));
+    }
+    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}`,
+        "kv",
+        { meta: { status: response.status, statusText: response.statusText } }
+      )
+    );
+  }
+  normalizeSignedReadUrlResponse(data) {
+    if (!data || typeof data !== "object") {
+      return void 0;
+    }
+    const response = data;
+    if (typeof response.url !== "string" || typeof response.ticketId !== "string" || typeof response.expiresAt !== "string") {
+      return void 0;
+    }
+    return {
+      url: new URL(response.url, this.host).toString(),
+      relativeUrl: response.url,
+      ticketId: response.ticketId,
+      expiresAt: response.expiresAt
+    };
+  }
   /**
    * Get a value by key.
    */
@@ -1337,6 +1441,61 @@ var KVService = class extends BaseService {
       }
     });
   }
+  /**
+   * Create a short-lived signed URL for reading a KV object.
+   */
+  async createSignedReadUrl(key, options) {
+    return this.withTelemetry("createSignedReadUrl", key, async () => {
+      if (!this.requireAuth()) {
+        return err(authRequiredError("kv"));
+      }
+      const path = this.getFullPath(key, options?.prefix);
+      const session = this.context.session;
+      const headers = this.context.invoke(
+        session,
+        "kv",
+        path,
+        KVAction.GET
+      );
+      const body = {
+        space: session.spaceId,
+        path,
+        ttl_seconds: options?.expiresInSeconds ?? Math.ceil(DEFAULT_SIGNED_READ_URL_EXPIRY_MS / 1e3)
+      };
+      if (options?.contentHash !== void 0) {
+        body.content_hash = options.contentHash;
+      }
+      if (options?.etag !== void 0) {
+        body.etag = options.etag;
+      }
+      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)
+        });
+        if (!response.ok) {
+          return this.createSignedReadUrlError(response, key);
+        }
+        const signedUrl = this.normalizeSignedReadUrlResponse(
+          await response.json()
+        );
+        if (!signedUrl) {
+          return err(
+            serviceError(
+              ErrorCodes.NETWORK_ERROR,
+              "Signed read URL response did not include url, ticketId, and expiresAt",
+              "kv"
+            )
+          );
+        }
+        return ok(signedUrl);
+      } catch (error) {
+        return err(wrapError("kv", error));
+      }
+    });
+  }
   /**
    * Create a prefix-scoped view of this KV service.
    *
@@ -2906,6 +3065,15 @@ function base64Decode(str) {
   }
   return bytes;
 }
+function unwrapKVData(value) {
+  if (value !== null && typeof value === "object" && "data" in value) {
+    return value.data;
+  }
+  return value;
+}
+function isUnlockSigner(signer) {
+  return typeof signer === "object" && signer !== null && typeof signer.signMessage === "function";
+}
 function defaultVaultMessage(input) {
   switch (input.code) {
     case "DECRYPTION_FAILED":
@@ -2943,6 +3111,7 @@ var DataVaultService = class extends BaseService {
     this.masterKey = null;
     this.encryptionIdentity = null;
     this._isUnlocked = false;
+    this.unlockInFlight = null;
     this.vaultConfig = config;
     this._config = config;
   }
@@ -2956,13 +3125,16 @@ var DataVaultService = class extends BaseService {
    * Whether the vault is currently unlocked.
    */
   get isUnlocked() {
-    return this._isUnlocked;
+    return this.usesNetworkEncryption || this._isUnlocked;
   }
   /**
    * The vault's public encryption key (X25519).
    * Throws if vault is locked.
    */
   get publicKey() {
+    if (this.usesNetworkEncryption) {
+      throw new Error("Network-encrypted vaults do not expose a local public key");
+    }
     if (!this.encryptionIdentity) {
       throw new Error("Vault is locked");
     }
@@ -2980,12 +3152,51 @@ var DataVaultService = class extends BaseService {
   get tc() {
     return this.vaultConfig.tc;
   }
+  get networkEncryption() {
+    return this.vaultConfig.encryption;
+  }
+  get usesNetworkEncryption() {
+    return this.networkEncryption !== void 0;
+  }
   /**
    * Get the host URL.
    */
   get host() {
     return this.tc.hosts[0];
   }
+  async decryptCapabilityProof() {
+    const proof = this.networkEncryption?.decryptCapabilityProof;
+    if (typeof proof === "function") {
+      return await proof();
+    }
+    return proof ?? { proofs: [] };
+  }
+  serializeValue(value, options) {
+    let plaintext;
+    if (value instanceof Uint8Array) {
+      plaintext = value;
+    } else if (options?.serialize) {
+      plaintext = options.serialize(value);
+    } else if (typeof value === "string") {
+      plaintext = toBytes(value);
+    } else {
+      plaintext = toBytes(JSON.stringify(value));
+    }
+    const contentType = options?.contentType ?? (value instanceof Uint8Array ? "application/octet-stream" : "application/json");
+    return { plaintext, contentType };
+  }
+  deserializeValue(plaintext, contentType, options) {
+    if (options?.raw) {
+      return plaintext;
+    }
+    if (options?.deserialize) {
+      return options.deserialize(plaintext);
+    }
+    if (contentType === "application/json") {
+      return JSON.parse(fromBytes(plaintext));
+    }
+    return plaintext;
+  }
   // =========================================================================
   // Phase 1: Core Operations
   // =========================================================================
@@ -3002,30 +3213,44 @@ var DataVaultService = class extends BaseService {
    *                 signatures exist (browser only).
    */
   async unlock(signer) {
-    return this.withTelemetry("unlock", void 0, async () => {
+    if (this.usesNetworkEncryption) {
+      this._isUnlocked = true;
+      return { ok: true, data: void 0 };
+    }
+    const unlockSigner = isUnlockSigner(signer) ? signer : void 0;
+    if (this._isUnlocked && this.masterKey && (this.encryptionIdentity || !unlockSigner)) {
+      return { ok: true, data: void 0 };
+    }
+    if (this.unlockInFlight) {
+      return this.unlockInFlight;
+    }
+    this.unlockInFlight = this.withTelemetry("unlock", void 0, async () => {
       const spaceId = this.vaultConfig.spaceId;
       const versionConfig = VaultVersionConfig[CURRENT_VAULT_VERSION];
       const masterCacheKey = `vault-master:${spaceId}`;
       const identityCacheKey = `vault-identity:${this.tc.address}`;
       try {
-        let masterSigBytes = await loadCachedSignature(masterCacheKey);
-        if (!masterSigBytes) {
-          if (!signer) {
-            return vaultError({
-              code: "VAULT_LOCKED",
-              message: "Signer is required when no cached master signature exists"
-            });
+        if (!this.masterKey) {
+          let masterSigBytes = await loadCachedSignature(masterCacheKey);
+          if (!masterSigBytes) {
+            if (!unlockSigner) {
+              return vaultError({
+                code: "VAULT_LOCKED",
+                message: "Signer is required when no cached master signature exists"
+              });
+            }
+            const sig = await unlockSigner.signMessage(
+              versionConfig.masterMessage(spaceId)
+            );
+            masterSigBytes = toBytes(sig);
+            await cacheSignature(masterCacheKey, masterSigBytes);
           }
-          const s = signer;
-          const sig = await s.signMessage(versionConfig.masterMessage(spaceId));
-          masterSigBytes = toBytes(sig);
-          await cacheSignature(masterCacheKey, masterSigBytes);
-        }
-        this.masterKey = this.crypto.deriveKey(
-          masterSigBytes,
-          this.crypto.sha256(toBytes(spaceId)),
-          toBytes("vault-master")
-        );
+          this.masterKey = this.crypto.deriveKey(
+            masterSigBytes,
+            this.crypto.sha256(toBytes(spaceId)),
+            toBytes("vault-master")
+          );
+        }
         const publicSpaceId = this.tc.makePublicSpaceId(this.tc.address, this.tc.chainId);
         let existingPubKey = null;
         try {
@@ -3048,13 +3273,14 @@ var DataVaultService = class extends BaseService {
         } else {
           let identitySigBytes = await loadCachedSignature(identityCacheKey);
           if (!identitySigBytes) {
-            if (!signer) {
+            if (!unlockSigner) {
               this.encryptionIdentity = null;
               this._isUnlocked = true;
               return ok(void 0);
             }
-            const s = signer;
-            const sig = await s.signMessage(versionConfig.identityMessage);
+            const sig = await unlockSigner.signMessage(
+              versionConfig.identityMessage
+            );
             identitySigBytes = toBytes(sig);
             await cacheSignature(identityCacheKey, identitySigBytes);
           }
@@ -3084,6 +3310,11 @@ var DataVaultService = class extends BaseService {
         });
       }
     });
+    try {
+      return await this.unlockInFlight;
+    } finally {
+      this.unlockInFlight = null;
+    }
   }
   /**
    * Clear the cached vault signatures.
@@ -3112,6 +3343,131 @@ var DataVaultService = class extends BaseService {
     this.lock();
     super.onSignOut();
   }
+  async putNetworkEncrypted(key, value, options) {
+    const config = this.networkEncryption;
+    if (!config) {
+      return vaultError({
+        code: "VAULT_LOCKED",
+        message: "Network encryption is not configured"
+      });
+    }
+    if (!this.requireAuth()) {
+      return vaultError({
+        code: "VAULT_LOCKED",
+        message: "Authentication required"
+      });
+    }
+    try {
+      const { plaintext, contentType } = this.serializeValue(value, options);
+      const metadata = {
+        [VaultHeaders.VERSION]: "2",
+        [VaultHeaders.CIPHER]: "tinycloud-network-envelope",
+        [VaultHeaders.CONTENT_TYPE]: contentType,
+        ...options?.metadata ?? {}
+      };
+      const aad = toBytes(`tinycloud.vault:${this.vaultConfig.spaceId}:${key}`);
+      const envelopeResult = await config.service.encryptToNetwork(
+        config.networkId,
+        plaintext,
+        { aad, metadata }
+      );
+      if (!envelopeResult.ok) {
+        return vaultError({
+          code: "STORAGE_ERROR",
+          cause: new Error(envelopeResult.error.message)
+        });
+      }
+      const valuePutResult = await this.tc.kv.put(
+        `vault/${key}`,
+        JSON.stringify(envelopeResult.data)
+      );
+      if (!valuePutResult.ok) {
+        return vaultError({
+          code: "STORAGE_ERROR",
+          cause: new Error(
+            `Failed to store encrypted value: ${valuePutResult.error.message}`
+          )
+        });
+      }
+      return { ok: true, data: void 0 };
+    } catch (error) {
+      return vaultError({
+        code: "STORAGE_ERROR",
+        cause: toError(error)
+      });
+    }
+  }
+  async getNetworkEncrypted(key, options) {
+    const config = this.networkEncryption;
+    if (!config) {
+      return vaultError({
+        code: "VAULT_LOCKED",
+        message: "Network encryption is not configured"
+      });
+    }
+    if (!this.requireAuth()) {
+      return vaultError({
+        code: "VAULT_LOCKED",
+        message: "Authentication required"
+      });
+    }
+    try {
+      const valueResult = await this.tc.kv.get(`vault/${key}`, {
+        raw: true
+      });
+      if (!valueResult.ok) {
+        return vaultError({ code: "KEY_NOT_FOUND", key });
+      }
+      const rawEnvelope = unwrapKVData(valueResult.data);
+      const envelope = typeof rawEnvelope === "string" ? JSON.parse(rawEnvelope) : rawEnvelope;
+      const proof = await this.decryptCapabilityProof();
+      const plaintextResult = await config.service.decryptEnvelope(envelope, proof);
+      if (!plaintextResult.ok) {
+        return vaultError({
+          code: "DECRYPTION_FAILED",
+          message: plaintextResult.error.message
+        });
+      }
+      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 { ok: true, data: { value, metadata, keyId } };
+    } catch (error) {
+      return vaultError({
+        code: "STORAGE_ERROR",
+        cause: toError(error)
+      });
+    }
+  }
+  async headNetworkEncrypted(key) {
+    if (!this.requireAuth()) {
+      return vaultError({
+        code: "VAULT_LOCKED",
+        message: "Authentication required"
+      });
+    }
+    try {
+      const valueResult = await this.tc.kv.get(`vault/${key}`, {
+        raw: true
+      });
+      if (!valueResult.ok) {
+        return vaultError({ code: "KEY_NOT_FOUND", key });
+      }
+      const rawEnvelope = unwrapKVData(valueResult.data);
+      const envelope = typeof rawEnvelope === "string" ? JSON.parse(rawEnvelope) : rawEnvelope;
+      return { ok: true, data: envelope.metadata ?? {} };
+    } catch (error) {
+      return vaultError({
+        code: "STORAGE_ERROR",
+        cause: toError(error)
+      });
+    }
+  }
   /**
    * Encrypt and store a value at the given key.
    *
@@ -3121,6 +3477,9 @@ var DataVaultService = class extends BaseService {
    */
   async put(key, value, options) {
     return this.withTelemetry("put", key, async () => {
+      if (this.usesNetworkEncryption) {
+        return this.putNetworkEncrypted(key, value, options);
+      }
       if (!this._isUnlocked || !this.masterKey) {
         return vaultError({
           code: "VAULT_LOCKED",
@@ -3213,6 +3572,9 @@ var DataVaultService = class extends BaseService {
    */
   async get(key, options) {
     return this.withTelemetry("get", key, async () => {
+      if (this.usesNetworkEncryption) {
+        return this.getNetworkEncrypted(key, options);
+      }
       if (!this._isUnlocked || !this.masterKey) {
         return vaultError({
           code: "VAULT_LOCKED",
@@ -3280,7 +3642,7 @@ var DataVaultService = class extends BaseService {
    */
   async delete(key) {
     return this.withTelemetry("delete", key, async () => {
-      if (!this._isUnlocked) {
+      if (!this.isUnlocked) {
         return vaultError({
           code: "VAULT_LOCKED",
           message: "Vault must be unlocked before deleting data"
@@ -3293,6 +3655,13 @@ var DataVaultService = class extends BaseService {
         });
       }
       try {
+        if (this.usesNetworkEncryption) {
+          const valueDelResult2 = await this.tc.kv.delete(`vault/${key}`);
+          if (!valueDelResult2.ok) {
+            return vaultError({ code: "KEY_NOT_FOUND", key });
+          }
+          return ok(void 0);
+        }
         const [keyDelResult, valueDelResult] = await Promise.all([
           this.tc.kv.delete(`keys/${key}`),
           this.tc.kv.delete(`vault/${key}`)
@@ -3317,7 +3686,7 @@ var DataVaultService = class extends BaseService {
    */
   async list(options) {
     return this.withTelemetry("list", options?.prefix, async () => {
-      if (!this._isUnlocked) {
+      if (!this.isUnlocked) {
         return vaultError({
           code: "VAULT_LOCKED",
           message: "Vault must be unlocked before listing data"
@@ -3367,6 +3736,9 @@ var DataVaultService = class extends BaseService {
    */
   async head(key) {
     return this.withTelemetry("head", key, async () => {
+      if (this.usesNetworkEncryption) {
+        return this.headNetworkEncrypted(key);
+      }
       if (!this._isUnlocked) {
         return vaultError({
           code: "VAULT_LOCKED",
@@ -3434,6 +3806,16 @@ var DataVaultService = class extends BaseService {
    */
   async reencrypt(key, recipientDID, options) {
     return this.withTelemetry("reencrypt", key, async () => {
+      if (this.usesNetworkEncryption) {
+        void recipientDID;
+        void options;
+        return vaultError({
+          code: "STORAGE_ERROR",
+          cause: new Error(
+            "Vault key grants are deprecated for network-encrypted vaults; grant tinycloud.encryption/decrypt on the network plus KV access to vault data."
+          )
+        });
+      }
       if (!this._isUnlocked || !this.masterKey) {
         return vaultError({
           code: "VAULT_LOCKED",
@@ -3523,6 +3905,66 @@ var DataVaultService = class extends BaseService {
    */
   async getShared(grantorDID, key, options) {
     return this.withTelemetry("getShared", key, async () => {
+      if (this.usesNetworkEncryption) {
+        const grantorKV = options?.kv;
+        if (!grantorKV) {
+          return vaultError({
+            code: "STORAGE_ERROR",
+            cause: new Error(
+              "getShared requires a delegated KV service via options.kv."
+            )
+          });
+        }
+        const config = this.networkEncryption;
+        if (!config) {
+          return vaultError({
+            code: "VAULT_LOCKED",
+            message: "Network encryption is not configured"
+          });
+        }
+        if (!this.requireAuth()) {
+          return vaultError({
+            code: "VAULT_LOCKED",
+            message: "Authentication required"
+          });
+        }
+        try {
+          const valueResult = await grantorKV.get(`vault/${key}`, {
+            raw: true
+          });
+          if (!valueResult.ok) {
+            return vaultError({ code: "KEY_NOT_FOUND", key });
+          }
+          const rawEnvelope = unwrapKVData(valueResult.data);
+          const envelope = typeof rawEnvelope === "string" ? JSON.parse(rawEnvelope) : rawEnvelope;
+          const proof = await this.decryptCapabilityProof();
+          const plaintextResult = await config.service.decryptEnvelope(
+            envelope,
+            proof
+          );
+          if (!plaintextResult.ok) {
+            return vaultError({
+              code: "DECRYPTION_FAILED",
+              message: plaintextResult.error.message
+            });
+          }
+          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
+          );
+          void grantorDID;
+          return { ok: true, data: { value, metadata, keyId } };
+        } catch (error) {
+          return vaultError({
+            code: "STORAGE_ERROR",
+            cause: toError(error)
+          });
+        }
+      }
       if (!this._isUnlocked || !this.masterKey || !this.encryptionIdentity) {
         return vaultError({
           code: "VAULT_LOCKED",
@@ -3648,6 +4090,10 @@ var DataVaultService = class extends BaseService {
    */
   async listGrants(key) {
     return this.withTelemetry("listGrants", key, async () => {
+      if (this.usesNetworkEncryption) {
+        void key;
+        return { ok: true, data: [] };
+      }
       if (!this._isUnlocked) {
         return vaultError({
           code: "VAULT_LOCKED",
@@ -3711,6 +4157,15 @@ var DataVaultService = class extends BaseService {
    */
   async revoke(key, recipientDID) {
     return this.withTelemetry("revoke", key, async () => {
+      if (this.usesNetworkEncryption) {
+        void recipientDID;
+        return vaultError({
+          code: "STORAGE_ERROR",
+          cause: new Error(
+            "Vault key grants are deprecated for network-encrypted vaults; revoke KV and tinycloud.encryption/decrypt grants instead."
+          )
+        });
+      }
       if (!this._isUnlocked || !this.masterKey) {
         return vaultError({
           code: "VAULT_LOCKED",
@@ -3846,18 +4301,67 @@ function createVaultCrypto(wasm) {
   };
 }
 
-// src/secrets/SecretsService.ts
+// src/secrets/paths.ts
 var SECRET_NAME_RE = /^[A-Z][A-Z0-9_]*$/;
 var SECRET_PREFIX = "secrets/";
-function invalidSecretName(name) {
+var SCOPED_SECRET_PREFIX = "secrets/scoped/";
+var RESERVED_SECRET_SCOPES = /* @__PURE__ */ new Set(["default", "global"]);
+function canonicalizeSecretScope(scope) {
+  if (scope === void 0) {
+    return void 0;
+  }
+  const trimmed = scope.trim();
+  if (trimmed === "") {
+    throw new Error("Secret scope must be non-empty; omit scope for global secrets.");
+  }
+  const canonical = trimmed.toLowerCase().replace(/[^a-z0-9-]/g, "-").replace(/-+/g, "-").replace(/^-|-$/g, "");
+  if (canonical === "") {
+    throw new Error("Secret scope must contain at least one letter or number.");
+  }
+  if (RESERVED_SECRET_SCOPES.has(canonical)) {
+    throw new Error(
+      `Secret scope ${JSON.stringify(scope)} is reserved; omit scope for global secrets.`
+    );
+  }
+  return canonical;
+}
+function resolveSecretPath(name, options = {}) {
+  const normalizedName = name.trim();
+  if (!SECRET_NAME_RE.test(normalizedName)) {
+    throw new Error(
+      `Invalid secret name ${JSON.stringify(name)}. Secret names must match ${SECRET_NAME_RE.source}.`
+    );
+  }
+  const scope = canonicalizeSecretScope(options.scope);
+  const vaultKey = scope === void 0 ? `${SECRET_PREFIX}${normalizedName}` : `${SCOPED_SECRET_PREFIX}${scope}/${normalizedName}`;
+  return {
+    name: normalizedName,
+    ...scope !== void 0 ? { scope } : {},
+    vaultKey,
+    permissionPaths: {
+      vault: `vault/${vaultKey}`
+    }
+  };
+}
+function resolveSecretListPrefix(options = {}) {
+  const scope = canonicalizeSecretScope(options.scope);
+  return scope === void 0 ? "vault/secrets/" : `vault/secrets/scoped/${scope}/`;
+}
+
+// src/secrets/SecretsService.ts
+function invalidSecretInput(message) {
   return err({
     code: ErrorCodes.INVALID_INPUT,
     service: "secrets",
-    message: `Invalid secret name ${JSON.stringify(name)}. Secret names must match ${SECRET_NAME_RE.source}.`
+    message
   });
 }
-function secretKey(name) {
-  return `${SECRET_PREFIX}${name}`;
+function resolveSecretPathResult(name, options) {
+  try {
+    return resolveSecretPath(name, options);
+  } catch (error) {
+    return invalidSecretInput(error instanceof Error ? error.message : String(error));
+  }
 }
 var SecretsService = class {
   constructor(vault) {
@@ -3875,36 +4379,40 @@ var SecretsService = class {
   lock() {
     this.vault.lock();
   }
-  async get(name) {
-    if (!SECRET_NAME_RE.test(name)) {
-      return invalidSecretName(name);
-    }
-    const result = await this.vault.get(secretKey(name));
+  async get(name, options) {
+    const secretPath = resolveSecretPathResult(name, options);
+    if ("ok" in secretPath) return secretPath;
+    const result = await this.vault.get(secretPath.vaultKey);
     if (!result.ok) {
       return result;
     }
     return { ok: true, data: result.data.value.value };
   }
-  async put(name, value) {
-    if (!SECRET_NAME_RE.test(name)) {
-      return invalidSecretName(name);
-    }
+  async put(name, value, options) {
+    const secretPath = resolveSecretPathResult(name, options);
+    if ("ok" in secretPath) return secretPath;
     const now = (/* @__PURE__ */ new Date()).toISOString();
-    return this.vault.put(secretKey(name), {
+    return this.vault.put(secretPath.vaultKey, {
       value,
       createdAt: now,
       updatedAt: now
     });
   }
-  async delete(name) {
-    if (!SECRET_NAME_RE.test(name)) {
-      return invalidSecretName(name);
-    }
-    return this.vault.delete(secretKey(name));
+  async delete(name, options) {
+    const secretPath = resolveSecretPathResult(name, options);
+    if ("ok" in secretPath) return secretPath;
+    return this.vault.delete(secretPath.vaultKey);
   }
-  async list() {
+  async list(options) {
+    let prefix;
+    try {
+      const scope = canonicalizeSecretScope(options?.scope);
+      prefix = scope === void 0 ? "secrets/" : `secrets/scoped/${scope}/`;
+    } catch (error) {
+      return invalidSecretInput(error instanceof Error ? error.message : String(error));
+    }
     const result = await this.vault.list({
-      prefix: SECRET_PREFIX,
+      prefix,
       removePrefix: true
     });
     if (!result.ok) {
@@ -3916,14 +4424,981 @@ var SecretsService = class {
     };
   }
 };
+
+// src/encryption/canonical.ts
+function canonicalize(value) {
+  if (value === void 0) {
+    return "";
+  }
+  return stringify(value);
+}
+function stringify(value) {
+  if (value === null) return "null";
+  switch (typeof value) {
+    case "boolean":
+    case "number":
+      return JSON.stringify(value);
+    case "string":
+      return JSON.stringify(value);
+    case "object": {
+      if (Array.isArray(value)) {
+        return `[${value.map(stringify).join(",")}]`;
+      }
+      const keys = Object.keys(value).sort();
+      const parts = [];
+      for (const k of keys) {
+        const v = value[k];
+        if (v === void 0) continue;
+        parts.push(`${JSON.stringify(k)}:${stringify(v)}`);
+      }
+      return `{${parts.join(",")}}`;
+    }
+    default:
+      throw new TypeError(
+        `canonicalize: unsupported value type ${typeof value}`
+      );
+  }
+}
+var HEX = "0123456789abcdef";
+function hexEncode2(bytes) {
+  let out = "";
+  for (let i = 0; i < bytes.length; i++) {
+    const b = bytes[i];
+    out += HEX[b >> 4 & 15] + HEX[b & 15];
+  }
+  return out;
+}
+function hexDecode(hex) {
+  if (hex.length % 2 !== 0) {
+    throw new Error("hex string must have even length");
+  }
+  const out = new Uint8Array(hex.length / 2);
+  for (let i = 0; i < out.length; i++) {
+    const hi = parseInt(hex[i * 2], 16);
+    const lo = parseInt(hex[i * 2 + 1], 16);
+    if (Number.isNaN(hi) || Number.isNaN(lo)) {
+      throw new Error("invalid hex character");
+    }
+    out[i] = hi << 4 | lo;
+  }
+  return out;
+}
+function base64Encode2(bytes) {
+  const chars = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/";
+  let out = "";
+  for (let i = 0; i < bytes.length; i += 3) {
+    const b0 = bytes[i];
+    const b1 = i + 1 < bytes.length ? bytes[i + 1] : 0;
+    const b2 = i + 2 < bytes.length ? bytes[i + 2] : 0;
+    out += chars[b0 >> 2 & 63];
+    out += chars[(b0 << 4 | b1 >> 4) & 63];
+    out += i + 1 < bytes.length ? chars[(b1 << 2 | b2 >> 6) & 63] : "=";
+    out += i + 2 < bytes.length ? chars[b2 & 63] : "=";
+  }
+  return out;
+}
+function base64Decode2(s) {
+  const clean = s.replace(/[^A-Za-z0-9+/=]/g, "");
+  const len = clean.length;
+  if (len % 4 !== 0) {
+    throw new Error("invalid base64 input");
+  }
+  const padding = clean.endsWith("==") ? 2 : clean.endsWith("=") ? 1 : 0;
+  const outLen = len / 4 * 3 - padding;
+  const out = new Uint8Array(outLen);
+  const lookup = {};
+  const chars = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/";
+  for (let i = 0; i < chars.length; i++) lookup[chars[i]] = i;
+  let outIdx = 0;
+  for (let i = 0; i < len; i += 4) {
+    const v0 = lookup[clean[i]] ?? 0;
+    const v1 = lookup[clean[i + 1]] ?? 0;
+    const v2 = clean[i + 2] === "=" ? 0 : lookup[clean[i + 2]] ?? 0;
+    const v3 = clean[i + 3] === "=" ? 0 : lookup[clean[i + 3]] ?? 0;
+    const b0 = v0 << 2 | v1 >> 4;
+    const b1 = (v1 & 15) << 4 | v2 >> 2;
+    const b2 = (v2 & 3) << 6 | v3;
+    if (outIdx < outLen) out[outIdx++] = b0;
+    if (outIdx < outLen) out[outIdx++] = b1;
+    if (outIdx < outLen) out[outIdx++] = b2;
+  }
+  return out;
+}
+function utf8Encode(s) {
+  return new TextEncoder().encode(s);
+}
+function utf8Decode(b) {
+  return new TextDecoder().decode(b);
+}
+function canonicalHashHex(sha256, value) {
+  const canonical = canonicalize(value);
+  return hexEncode2(sha256(utf8Encode(canonical)));
+}
+
+// src/encryption/networkId.ts
+var URN_PREFIX = "urn:tinycloud:encryption:";
+var NETWORK_NAME_RE = /^[a-z0-9][a-z0-9-]*$/;
+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 principal or name segment (got ${JSON.stringify(networkId)})`
+    );
+  }
+  const principal = body.slice(0, lastColon);
+  const name = body.slice(lastColon + 1);
+  if (!principal.startsWith("did:")) {
+    throw new NetworkIdError(
+      `networkId principal must be a DID (got ${JSON.stringify(principal)})`
+    );
+  }
+  const didParts = principal.split(":");
+  if (didParts.length < 3 || didParts.some((p) => p.length === 0)) {
+    throw new NetworkIdError(
+      `networkId principal is not a well-formed DID (got ${JSON.stringify(principal)})`
+    );
+  }
+  if (!NETWORK_NAME_RE.test(name)) {
+    throw new NetworkIdError(
+      `networkId name ${JSON.stringify(name)} must match ${NETWORK_NAME_RE.source}`
+    );
+  }
+  return { networkId, principal, name };
+}
+function buildNetworkId(principal, name) {
+  if (typeof principal !== "string" || !principal.startsWith("did:")) {
+    throw new NetworkIdError("principal 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}${principal}:${name}`;
+  parseNetworkId(networkId);
+  return networkId;
+}
+function isNetworkId(networkId) {
+  if (typeof networkId !== "string") {
+    return false;
+  }
+  try {
+    parseNetworkId(networkId);
+    return true;
+  } catch {
+    return false;
+  }
+}
+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;
+var DEFAULT_KEY_VERSION = 1;
+var DECRYPT_FACT_TYPE = "tinycloud.encryption.decrypt/v1";
+var DECRYPT_RESULT_TYPE = "tinycloud.encryption.decrypt-result/v1";
+var ENCRYPTION_SERVICE = "tinycloud.encryption";
+var ENCRYPTION_SERVICE_SHORT = "encryption";
+var DECRYPT_ACTION = "tinycloud.encryption/decrypt";
+function defaultEncryptionMessage(input) {
+  switch (input.code) {
+    case "NETWORK_NOT_FOUND":
+      return input.message ?? `Network not found: ${input.networkId ?? input.name ?? "<unknown>"}`;
+    case "NETWORK_NOT_ACTIVE":
+      return input.message ?? `Network not active (state=${input.state})`;
+    case "INVALID_NETWORK_ID":
+      return input.message;
+    case "INVALID_ENVELOPE":
+      return input.message;
+    case "DECRYPT_DENIED":
+      return input.message;
+    case "INVALID_RESPONSE":
+      return input.message;
+    case "RESPONSE_SIGNATURE_INVALID":
+      return input.message ?? "Node response signature failed to verify";
+    case "RESPONSE_BINDING_MISMATCH":
+      return input.message ?? `Node response binding mismatch on field ${JSON.stringify(input.field)}`;
+    case "TRANSPORT_ERROR":
+      return input.message ?? input.cause.message;
+    case "INVALID_INPUT":
+      return input.message;
+  }
+}
+function encryptionError(input) {
+  return {
+    ...input,
+    service: "encryption",
+    message: defaultEncryptionMessage(input)
+  };
+}
+function toError2(error) {
+  if (error instanceof Error) return error;
+  if (typeof error === "object" && error !== null) {
+    return new Error(JSON.stringify(error));
+  }
+  return new Error(String(error));
+}
+
+// src/encryption/discovery.ts
+async function discoverNetwork(input) {
+  let networkId;
+  let principal;
+  let name;
+  try {
+    if (input.identifier.startsWith("urn:tinycloud:encryption:")) {
+      const parsed = parseNetworkId(input.identifier);
+      networkId = parsed.networkId;
+      principal = parsed.principal;
+      name = parsed.name;
+    } else {
+      if (input.principal === void 0) {
+        return {
+          ok: false,
+          error: encryptionError({
+            code: "INVALID_INPUT",
+            message: "discoverNetwork requires `principal` when identifier is a bare network name"
+          })
+        };
+      }
+      networkId = `urn:tinycloud:encryption:${input.principal}:${input.identifier}`;
+      const parsed = parseNetworkId(networkId);
+      principal = parsed.principal;
+      name = parsed.name;
+    }
+  } catch (err3) {
+    if (err3 instanceof NetworkIdError) {
+      return {
+        ok: false,
+        error: encryptionError({
+          code: "INVALID_NETWORK_ID",
+          message: err3.message
+        })
+      };
+    }
+    throw err3;
+  }
+  if (input.node !== void 0) {
+    try {
+      const descriptor = await input.node.fetchByNetworkId(networkId);
+      if (descriptor !== null) {
+        const validated = validateDescriptor(descriptor, networkId, principal, name);
+        if (!validated.ok) return validated;
+        return { ok: true, data: { descriptor: validated.data, source: "node" } };
+      }
+    } catch (err3) {
+    }
+  }
+  if (input.wellKnown !== void 0) {
+    try {
+      const descriptor = await input.wellKnown.fetchWellKnown(
+        principal,
+        networkDiscoveryKey(name)
+      );
+      if (descriptor !== null) {
+        const validated = validateDescriptor(descriptor, networkId, principal, name);
+        if (!validated.ok) return validated;
+        return {
+          ok: true,
+          data: { descriptor: validated.data, source: "well-known" }
+        };
+      }
+    } catch (err3) {
+    }
+  }
+  return {
+    ok: false,
+    error: encryptionError({
+      code: "NETWORK_NOT_FOUND",
+      networkId,
+      name
+    })
+  };
+}
+function validateDescriptor(descriptor, networkId, principal, name) {
+  if (descriptor.networkId !== networkId) {
+    return {
+      ok: false,
+      error: encryptionError({
+        code: "INVALID_NETWORK_ID",
+        message: `descriptor networkId ${JSON.stringify(descriptor.networkId)} does not match expected ${JSON.stringify(networkId)}`
+      })
+    };
+  }
+  if (descriptor.principal !== principal) {
+    return {
+      ok: false,
+      error: encryptionError({
+        code: "INVALID_NETWORK_ID",
+        message: "descriptor principal does not match networkId principal"
+      })
+    };
+  }
+  if (descriptor.name !== name) {
+    return {
+      ok: false,
+      error: encryptionError({
+        code: "INVALID_NETWORK_ID",
+        message: "descriptor name does not match networkId name"
+      })
+    };
+  }
+  if (typeof descriptor.publicEncryptionKey !== "string" || descriptor.publicEncryptionKey.length === 0) {
+    return {
+      ok: false,
+      error: encryptionError({
+        code: "INVALID_NETWORK_ID",
+        message: "descriptor publicEncryptionKey must be a non-empty string"
+      })
+    };
+  }
+  return { ok: true, data: descriptor };
+}
+function ensureNetworkUsableForDecrypt(descriptor) {
+  if (descriptor.state === "active" || descriptor.state === "rotating") {
+    return { ok: true, data: descriptor };
+  }
+  return {
+    ok: false,
+    error: encryptionError({
+      code: "NETWORK_NOT_ACTIVE",
+      state: descriptor.state
+    })
+  };
+}
+
+// src/encryption/envelope.ts
+function encryptToNetwork(crypto2, input) {
+  parseNetworkId(input.networkId);
+  const alg = input.alg ?? DEFAULT_ENCRYPTION_ALG;
+  const keyVersion = input.keyVersion ?? DEFAULT_KEY_VERSION;
+  const symmetricKey = crypto2.randomBytes(32);
+  const ciphertext = crypto2.authEncrypt(symmetricKey, input.plaintext, input.aad);
+  const wrapped = crypto2.sealToNetworkKey(input.networkPublicKey, symmetricKey);
+  const encryptedSymmetricKey = base64Encode2(wrapped);
+  const encryptedSymmetricKeyHash = canonicalHashHex(
+    crypto2.sha256,
+    encryptedSymmetricKey
+  );
+  const envelope = {
+    v: ENVELOPE_VERSION,
+    networkId: input.networkId,
+    alg,
+    keyVersion,
+    encryptedSymmetricKey,
+    encryptedSymmetricKeyHash,
+    ciphertext: base64Encode2(ciphertext),
+    ...input.aad !== void 0 ? { aad: base64Encode2(input.aad) } : {},
+    ...input.metadata !== void 0 ? { metadata: input.metadata } : {}
+  };
+  return { envelope, symmetricKey };
+}
+function validateEnvelope(crypto2, envelope) {
+  if (envelope === null || typeof envelope !== "object") {
+    return {
+      ok: false,
+      error: encryptionError({
+        code: "INVALID_ENVELOPE",
+        message: "envelope must be an object"
+      })
+    };
+  }
+  const e = envelope;
+  if (e.v !== ENVELOPE_VERSION) {
+    return {
+      ok: false,
+      error: encryptionError({
+        code: "INVALID_ENVELOPE",
+        message: `envelope.v must be ${ENVELOPE_VERSION} (got ${e.v})`
+      })
+    };
+  }
+  try {
+    parseNetworkId(e.networkId);
+  } catch (err3) {
+    return {
+      ok: false,
+      error: encryptionError({
+        code: "INVALID_ENVELOPE",
+        message: `envelope.networkId is malformed: ${err3 instanceof Error ? err3.message : String(err3)}`
+      })
+    };
+  }
+  for (const field of [
+    "alg",
+    "encryptedSymmetricKey",
+    "encryptedSymmetricKeyHash",
+    "ciphertext"
+  ]) {
+    if (typeof e[field] !== "string" || e[field].length === 0) {
+      return {
+        ok: false,
+        error: encryptionError({
+          code: "INVALID_ENVELOPE",
+          message: `envelope.${field} must be a non-empty string`
+        })
+      };
+    }
+  }
+  if (typeof e.keyVersion !== "number" || !Number.isInteger(e.keyVersion)) {
+    return {
+      ok: false,
+      error: encryptionError({
+        code: "INVALID_ENVELOPE",
+        message: "envelope.keyVersion must be an integer"
+      })
+    };
+  }
+  const expectedHash = canonicalHashHex(crypto2.sha256, e.encryptedSymmetricKey);
+  if (expectedHash !== e.encryptedSymmetricKeyHash) {
+    return {
+      ok: false,
+      error: encryptionError({
+        code: "INVALID_ENVELOPE",
+        message: "envelope.encryptedSymmetricKeyHash does not match canonical hash of encryptedSymmetricKey"
+      })
+    };
+  }
+  return { ok: true, data: e };
+}
+function decryptEnvelopeWithKey(crypto2, envelope, symmetricKey) {
+  const ciphertext = base64Decode2(envelope.ciphertext);
+  const aad = envelope.aad !== void 0 ? base64Decode2(envelope.aad) : void 0;
+  return crypto2.authDecrypt(symmetricKey, ciphertext, aad);
+}
+
+// src/encryption/invocation.ts
+function buildCanonicalDecryptRequest(input) {
+  const canonicalBody = canonicalize(input.body);
+  const bodyHash = canonicalHashHex(
+    input.crypto.sha256,
+    input.body
+  );
+  const receiverPublicKeyHash = canonicalHashHex(
+    input.crypto.sha256,
+    input.body.receiverPublicKey
+  );
+  return { canonicalBody, bodyHash, receiverPublicKeyHash };
+}
+function buildDecryptFacts(input) {
+  const bodyHash = input.canonicalBody !== void 0 ? hexEncode2(input.crypto.sha256(utf8Encode(input.canonicalBody))) : canonicalHashHex(
+    input.crypto.sha256,
+    input.body
+  );
+  const receiverPublicKeyHash = canonicalHashHex(
+    input.crypto.sha256,
+    input.body.receiverPublicKey
+  );
+  return {
+    type: DECRYPT_FACT_TYPE,
+    targetNode: input.body.targetNode,
+    networkId: input.body.networkId,
+    bodyHash,
+    encryptedSymmetricKeyHash: input.encryptedSymmetricKeyHash,
+    receiverPublicKeyHash,
+    alg: input.body.alg,
+    keyVersion: input.body.keyVersion
+  };
+}
+function buildDecryptAttenuation(networkId) {
+  parseNetworkId(networkId);
+  return {
+    [networkId]: {
+      [DECRYPT_ACTION]: {}
+    }
+  };
+}
+function checkDecryptInvocationInput(crypto2, input) {
+  if (input.body.type !== DECRYPT_FACT_TYPE) {
+    return {
+      ok: false,
+      error: encryptionError({
+        code: "INVALID_INPUT",
+        message: `body.type must be ${DECRYPT_FACT_TYPE}`
+      })
+    };
+  }
+  if (input.facts.type !== DECRYPT_FACT_TYPE) {
+    return {
+      ok: false,
+      error: encryptionError({
+        code: "INVALID_INPUT",
+        message: `facts.type must be ${DECRYPT_FACT_TYPE}`
+      })
+    };
+  }
+  if (input.facts.targetNode !== input.targetNode) {
+    return {
+      ok: false,
+      error: encryptionError({
+        code: "INVALID_INPUT",
+        message: "facts.targetNode must equal targetNode \u2014 the UCAN audience binds the request to a single node"
+      })
+    };
+  }
+  if (input.body.targetNode !== input.targetNode) {
+    return {
+      ok: false,
+      error: encryptionError({
+        code: "INVALID_INPUT",
+        message: "body.targetNode must equal targetNode"
+      })
+    };
+  }
+  if (input.facts.networkId !== input.networkId) {
+    return {
+      ok: false,
+      error: encryptionError({
+        code: "INVALID_INPUT",
+        message: "facts.networkId must equal networkId"
+      })
+    };
+  }
+  if (input.body.networkId !== input.networkId) {
+    return {
+      ok: false,
+      error: encryptionError({
+        code: "INVALID_INPUT",
+        message: "body.networkId must equal networkId"
+      })
+    };
+  }
+  if (input.facts.alg !== input.body.alg) {
+    return {
+      ok: false,
+      error: encryptionError({
+        code: "INVALID_INPUT",
+        message: "facts.alg must equal body.alg"
+      })
+    };
+  }
+  if (input.facts.keyVersion !== input.body.keyVersion) {
+    return {
+      ok: false,
+      error: encryptionError({
+        code: "INVALID_INPUT",
+        message: "facts.keyVersion must equal body.keyVersion"
+      })
+    };
+  }
+  if (input.facts.encryptedSymmetricKeyHash !== input.body.encryptedSymmetricKeyHash) {
+    return {
+      ok: false,
+      error: encryptionError({
+        code: "INVALID_INPUT",
+        message: "facts.encryptedSymmetricKeyHash must equal body.encryptedSymmetricKeyHash"
+      })
+    };
+  }
+  if (input.facts.receiverPublicKeyHash !== input.body.receiverPublicKeyHash) {
+    return {
+      ok: false,
+      error: encryptionError({
+        code: "INVALID_INPUT",
+        message: "facts.receiverPublicKeyHash must equal body.receiverPublicKeyHash"
+      })
+    };
+  }
+  try {
+    parseNetworkId(input.networkId);
+  } catch (err3) {
+    return {
+      ok: false,
+      error: encryptionError({
+        code: "INVALID_NETWORK_ID",
+        message: err3 instanceof Error ? err3.message : String(err3)
+      })
+    };
+  }
+  const canonicalBody = canonicalize(
+    input.body
+  );
+  const expectedBodyHash = canonicalHashHex(crypto2.sha256, input.body);
+  if (expectedBodyHash !== input.facts.bodyHash) {
+    return {
+      ok: false,
+      error: encryptionError({
+        code: "INVALID_INPUT",
+        message: "facts.bodyHash does not match the canonical body hash"
+      })
+    };
+  }
+  return { ok: true, data: input, canonicalBody };
+}
+async function buildDecryptInvocation(crypto2, signer, input) {
+  const checked = checkDecryptInvocationInput(crypto2, input);
+  if (!checked.ok) {
+    return checked;
+  }
+  try {
+    const built = await signer.signDecryptInvocation(checked.data);
+    if (!built.authorization || !built.invocationCid) {
+      return {
+        ok: false,
+        error: encryptionError({
+          code: "INVALID_INPUT",
+          message: "decrypt-invocation signer returned an empty authorization or invocationCid"
+        })
+      };
+    }
+    if (built.canonicalBody !== checked.canonicalBody) {
+      return {
+        ok: false,
+        error: encryptionError({
+          code: "INVALID_INPUT",
+          message: "decrypt-invocation signer returned a canonicalBody that does not match the SDK's canonicalization \u2014 signer must use the SDK-provided body"
+        })
+      };
+    }
+    return { ok: true, data: built };
+  } catch (err3) {
+    return {
+      ok: false,
+      error: encryptionError({
+        code: "TRANSPORT_ERROR",
+        cause: err3 instanceof Error ? err3 : new Error(String(err3)),
+        message: `failed to sign decrypt invocation: ${err3 instanceof Error ? err3.message : String(err3)}`
+      })
+    };
+  }
+}
+
+// src/encryption/receiverKey.ts
+function generateRandomReceiverKey(input) {
+  const seed = input.crypto.randomBytes(32);
+  return input.crypto.x25519FromSeed(seed);
+}
+async function deriveSignedReceiverKey(input) {
+  const message = `tinycloud.encryption.receiver-key/v1:${input.networkId}:${input.context ?? ""}`;
+  const sig = await input.signer.signMessage(message);
+  const sigBytes = utf8Encode(sig);
+  const seed = input.crypto.sha256(sigBytes);
+  return input.crypto.x25519FromSeed(seed);
+}
+
+// src/encryption/response.ts
+function canonicalSignedResponse(response) {
+  const { nodeSignature: _drop, ...rest } = response;
+  return canonicalize(rest);
+}
+function verifyDecryptResponse(input) {
+  const { crypto: crypto2, request, facts, invocationCid, requestBodyHash, response } = input;
+  if (response.type !== DECRYPT_RESULT_TYPE) {
+    return {
+      ok: false,
+      error: encryptionError({
+        code: "INVALID_RESPONSE",
+        message: `response.type must be ${DECRYPT_RESULT_TYPE}`
+      })
+    };
+  }
+  if (response.targetNode !== request.targetNode) {
+    return {
+      ok: false,
+      error: encryptionError({
+        code: "RESPONSE_BINDING_MISMATCH",
+        field: "targetNode"
+      })
+    };
+  }
+  if (response.networkId !== request.networkId) {
+    return {
+      ok: false,
+      error: encryptionError({
+        code: "RESPONSE_BINDING_MISMATCH",
+        field: "networkId"
+      })
+    };
+  }
+  if (response.alg !== request.alg) {
+    return {
+      ok: false,
+      error: encryptionError({
+        code: "RESPONSE_BINDING_MISMATCH",
+        field: "alg"
+      })
+    };
+  }
+  if (response.keyVersion !== request.keyVersion) {
+    return {
+      ok: false,
+      error: encryptionError({
+        code: "RESPONSE_BINDING_MISMATCH",
+        field: "keyVersion"
+      })
+    };
+  }
+  if (response.encryptedSymmetricKeyHash !== request.encryptedSymmetricKeyHash) {
+    return {
+      ok: false,
+      error: encryptionError({
+        code: "RESPONSE_BINDING_MISMATCH",
+        field: "encryptedSymmetricKeyHash"
+      })
+    };
+  }
+  if (response.receiverPublicKeyHash !== request.receiverPublicKeyHash) {
+    return {
+      ok: false,
+      error: encryptionError({
+        code: "RESPONSE_BINDING_MISMATCH",
+        field: "receiverPublicKeyHash"
+      })
+    };
+  }
+  if (response.invocationCid !== invocationCid) {
+    return {
+      ok: false,
+      error: encryptionError({
+        code: "RESPONSE_BINDING_MISMATCH",
+        field: "invocationCid"
+      })
+    };
+  }
+  const expectedRequestHash = hexEncode2(
+    crypto2.sha256(utf8Encode(`${invocationCid}${requestBodyHash}`))
+  );
+  if (response.requestHash !== expectedRequestHash) {
+    return {
+      ok: false,
+      error: encryptionError({
+        code: "RESPONSE_BINDING_MISMATCH",
+        field: "requestHash"
+      })
+    };
+  }
+  if (facts.encryptedSymmetricKeyHash !== response.encryptedSymmetricKeyHash || facts.receiverPublicKeyHash !== response.receiverPublicKeyHash || facts.networkId !== response.networkId || facts.targetNode !== response.targetNode || facts.alg !== response.alg || facts.keyVersion !== response.keyVersion) {
+    return {
+      ok: false,
+      error: encryptionError({
+        code: "RESPONSE_BINDING_MISMATCH",
+        field: "facts"
+      })
+    };
+  }
+  const signedBytes = new TextEncoder().encode(
+    canonicalSignedResponse(response)
+  );
+  const signatureBytes = base64Decode2(response.nodeSignature);
+  if (!crypto2.verifyNodeSignature(response.nodeId, signedBytes, signatureBytes)) {
+    return {
+      ok: false,
+      error: encryptionError({
+        code: "RESPONSE_SIGNATURE_INVALID"
+      })
+    };
+  }
+  return { ok: true, data: response };
+}
+function openWrappedKey(crypto2, receiverPrivateKey, response) {
+  const wrapped = base64Decode2(response.wrappedKey);
+  return crypto2.openWithReceiverKey(receiverPrivateKey, wrapped);
+}
+
+// src/encryption/EncryptionService.ts
+function encOk(data) {
+  return { ok: true, data };
+}
+function encErr(error) {
+  return { ok: false, error };
+}
+var EncryptionService = class extends BaseService {
+  constructor(config) {
+    super();
+    this._config = config;
+  }
+  get config() {
+    return this._config;
+  }
+  get crypto() {
+    return this._config.crypto;
+  }
+  async discoverNetwork(identifier, principal) {
+    const result = await discoverNetwork({
+      identifier,
+      ...principal !== void 0 ? { principal } : {},
+      ...this._config.node !== void 0 ? { node: this._config.node } : {},
+      ...this._config.wellKnown !== void 0 ? { wellKnown: this._config.wellKnown } : {}
+    });
+    if (!result.ok) return result;
+    return encOk(result.data.descriptor);
+  }
+  async encryptToNetwork(networkId, plaintext, options) {
+    try {
+      const discovered = await this.discoverNetwork(networkId);
+      if (!discovered.ok) return discovered;
+      const usable = ensureNetworkUsableForDecrypt(discovered.data);
+      if (!usable.ok) return usable;
+      const descriptor = usable.data;
+      const networkPublicKey = base64Decode2(descriptor.publicEncryptionKey);
+      const result = encryptToNetwork(this.crypto, {
+        networkId,
+        networkPublicKey,
+        plaintext,
+        ...options?.aad !== void 0 ? { aad: options.aad } : {},
+        alg: options?.alg ?? descriptor.alg,
+        keyVersion: options?.keyVersion ?? descriptor.keyVersion,
+        ...options?.metadata !== void 0 ? { metadata: options.metadata } : {}
+      });
+      return encOk(result.envelope);
+    } catch (error) {
+      return encErr(
+        encryptionError({
+          code: "TRANSPORT_ERROR",
+          cause: toError2(error)
+        })
+      );
+    }
+  }
+  async decryptEnvelope(envelope, capabilityProof, options) {
+    try {
+      const validated = validateEnvelope(this.crypto, envelope);
+      if (!validated.ok) return validated;
+      let descriptor;
+      if (options?.descriptor !== void 0) {
+        descriptor = options.descriptor;
+      } else {
+        const discovered = await this.discoverNetwork(envelope.networkId);
+        if (!discovered.ok) return discovered;
+        descriptor = discovered.data;
+      }
+      const usable = ensureNetworkUsableForDecrypt(descriptor);
+      if (!usable.ok) return usable;
+      const targetNode = options?.targetNode ?? descriptor.members[0]?.nodeId;
+      if (targetNode === void 0) {
+        return encErr(
+          encryptionError({
+            code: "INVALID_INPUT",
+            message: "no target node available from descriptor"
+          })
+        );
+      }
+      const receiverKey = generateRandomReceiverKey({ crypto: this.crypto });
+      const receiverPublicKey = base64Encode2(receiverKey.publicKey);
+      const receiverPublicKeyHash = canonicalHashHex(
+        this.crypto.sha256,
+        receiverPublicKey
+      );
+      const body = {
+        type: DECRYPT_FACT_TYPE,
+        targetNode,
+        networkId: envelope.networkId,
+        alg: envelope.alg,
+        keyVersion: envelope.keyVersion,
+        encryptedSymmetricKey: envelope.encryptedSymmetricKey,
+        encryptedSymmetricKeyHash: envelope.encryptedSymmetricKeyHash,
+        receiverPublicKey,
+        receiverPublicKeyHash
+      };
+      const canonicalRequest = buildCanonicalDecryptRequest({
+        crypto: this.crypto,
+        body,
+        receiverPublicKey: receiverKey.publicKey
+      });
+      const facts = buildDecryptFacts({
+        crypto: this.crypto,
+        body,
+        encryptedSymmetricKeyHash: envelope.encryptedSymmetricKeyHash,
+        receiverPublicKey: receiverKey.publicKey,
+        canonicalBody: canonicalRequest.canonicalBody
+      });
+      const built = await buildDecryptInvocation(this.crypto, this._config.signer, {
+        targetNode,
+        networkId: envelope.networkId,
+        body,
+        facts,
+        proof: capabilityProof
+      });
+      if (!built.ok) return built;
+      let response;
+      try {
+        response = await this._config.transport.postDecrypt({
+          targetNode,
+          networkId: envelope.networkId,
+          authorization: built.data.authorization,
+          canonicalBody: built.data.canonicalBody
+        });
+      } catch (error) {
+        return encErr(
+          encryptionError({
+            code: "TRANSPORT_ERROR",
+            cause: toError2(error)
+          })
+        );
+      }
+      const verified = verifyDecryptResponse({
+        crypto: this.crypto,
+        request: body,
+        facts,
+        invocationCid: built.data.invocationCid,
+        requestBodyHash: facts.bodyHash,
+        response
+      });
+      if (!verified.ok) return verified;
+      const symmetricKey = openWrappedKey(
+        this.crypto,
+        receiverKey.privateKey,
+        verified.data
+      );
+      const plaintext = decryptEnvelopeWithKey(
+        this.crypto,
+        envelope,
+        symmetricKey
+      );
+      return encOk(plaintext);
+    } catch (error) {
+      return encErr(
+        encryptionError({
+          code: "TRANSPORT_ERROR",
+          cause: toError2(error)
+        })
+      );
+    }
+  }
+};
+EncryptionService.serviceName = "encryption";
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   BaseService,
+  DECRYPT_ACTION,
+  DECRYPT_FACT_TYPE,
+  DECRYPT_RESULT_TYPE,
+  DEFAULT_ENCRYPTION_ALG,
+  DEFAULT_KEY_VERSION,
+  DEFAULT_SIGNED_READ_URL_EXPIRY_MS,
   DataVaultService,
   DatabaseHandle,
   DuckDbAction,
   DuckDbDatabaseHandle,
   DuckDbService,
+  ENCRYPTION_NETWORK_URN_PREFIX,
+  ENCRYPTION_SERVICE,
+  ENCRYPTION_SERVICE_SHORT,
+  ENVELOPE_VERSION,
+  EncryptionService,
   ErrorCodes,
   GenericKVResponseSchema,
   GenericResultSchema,
@@ -3933,8 +5408,11 @@ var SecretsService = class {
   KVListResultSchema,
   KVResponseHeadersSchema,
   KVService,
+  NETWORK_NAME_PATTERN,
+  NetworkIdError,
   PrefixedKVService,
   RetryPolicySchema,
+  SECRET_NAME_RE,
   SQLAction,
   SQLService,
   SecretsService,
@@ -3953,21 +5431,51 @@ var SecretsService = class {
   authExpiredError,
   authRequiredError,
   authUnauthorizedError,
+  base64Decode,
+  base64Encode,
+  buildCanonicalDecryptRequest,
+  buildDecryptAttenuation,
+  buildDecryptFacts,
+  buildDecryptInvocation,
+  buildNetworkId,
+  canonicalHashHex,
+  canonicalSignedResponse,
+  canonicalizeEncryptionJson,
+  canonicalizeSecretScope,
+  checkDecryptInvocationInput,
   createKVResponseSchema,
   createResultSchema,
   createVaultCrypto,
+  decryptEnvelopeWithKey,
   defaultRetryPolicy,
+  deriveSignedReceiverKey,
+  discoverNetwork,
+  encryptToNetwork,
+  encryptionError,
+  ensureNetworkUsableForDecrypt,
   err,
   errorResult,
+  generateRandomReceiverKey,
+  hexDecode,
+  hexEncode,
+  isNetworkId,
+  networkDiscoveryKey,
   networkError,
   notFoundError,
   ok,
+  openWrappedKey,
   parseAuthError,
+  parseNetworkId,
   permissionDeniedError,
+  resolveSecretListPrefix,
+  resolveSecretPath,
   serviceError,
   storageLimitReachedError,
   storageQuotaExceededError,
   timeoutError,
+  utf8Decode,
+  utf8Encode,
+  validateEnvelope,
   validateKVListResponse,
   validateKVResponseHeaders,
   validateRetryPolicy,
@@ -3975,6 +5483,7 @@ var SecretsService = class {
   validateServiceRequestEvent,
   validateServiceResponseEvent,
   validateServiceSession,
+  verifyDecryptResponse,
   wrapError
 });
 //# sourceMappingURL=index.cjs.map