@enbox/api 0.6.11 → 0.6.13

package/src/typed-enbox.ts

@@ -639,12 +639,25 @@ export class TypedEnbox<
     }
 
     // Not installed or definition has changed — configure the new version.
-    // Auto-enable encryption if any type in the definition requires it.
-    // Skip encryption key derivation when operating as a delegate — the
-    // wallet already configured the protocol with encryption keys.
-    const needsEncryption = !this._dwn.isDelegate && Object.values(this._definition.types)
+    // In delegate mode, the wallet is responsible for installing encrypted
+    // protocols during the connect flow. The delegate cannot derive the
+    // owner's encryption keys, so configuring here would install the
+    // protocol WITHOUT $encryption keys — breaking all encrypted writes.
+    const hasEncryptedTypes = Object.values(this._definition.types)
       .some((type) => (type as ProtocolType)?.encryptionRequired === true);
 
+    if (this._dwn.isDelegate && hasEncryptedTypes) {
+      throw new Error(
+        `TypedEnbox: Protocol '${this._definition.protocol}' requires ` +
+        `encryption but is not installed or has changed. In delegate mode, ` +
+        `encrypted protocols must be installed by the wallet during the ` +
+        `connect flow. Ensure the sync engine has completed its initial ` +
+        `sync before performing record operations.`,
+      );
+    }
+
+    const needsEncryption = !this._dwn.isDelegate && hasEncryptedTypes;
+
     const result = await this._dwn.protocols.configure({
       definition : this._definition,
       encryption : options?.encryption ?? (needsEncryption || undefined),
@@ -765,12 +778,53 @@ export class TypedEnbox<
       return;
     }
 
-    // Not installed — configure it now.
-    // Auto-enable encryption if any type in the definition requires it.
-    // Skip encryption key derivation when operating as a delegate — the
-    // wallet already configured the protocol with encryption keys. The
-    // delegate can't derive the owner's keys.
-    const needsEncryption = !this._dwn.isDelegate && Object.values(this._definition.types)
+    // Not installed locally — configure it now.
+    //
+    // For delegates: the wallet already installed the protocol with derived
+    // `$encryption` keys on the owner's remote DWN. We fetch that remote
+    // definition and install it locally so the delegate can encrypt records
+    // using the public keys from `$encryption`. This avoids the delegate
+    // needing the owner's private X25519 key — only the already-public
+    // derived keys are used for ProtocolPath encryption.
+    //
+    // For owners: derive encryption keys locally via the KMS.
+    if (this._dwn.isDelegate) {
+      const installed = await this._autoConfigureDelegateProtocol();
+      if (installed) {
+        return;
+      }
+
+      // The remote definition could not be fetched. If this protocol has
+      // any types with `encryptionRequired: true`, we MUST fail — silently
+      // installing without `$encryption` keys would allow plaintext writes
+      // that the owner's remote DWN would later reject, or worse, persist
+      // unencrypted sensitive data.
+      const hasEncryptedTypes = Object.values(this._definition.types)
+        .some((type) => (type as ProtocolType)?.encryptionRequired === true);
+
+      if (hasEncryptedTypes) {
+        throw new Error(
+          `TypedEnbox: delegate cannot install protocol '${this._definition.protocol}' ` +
+          'because it contains types with encryptionRequired but the owner\'s ' +
+          'remote protocol definition (with $encryption keys) could not be fetched. ' +
+          'Ensure the owner has installed the protocol on their DWN and that the ' +
+          'delegate has network access to the owner\'s DWN endpoints.',
+        );
+      }
+
+      // No encrypted types — safe to install the app-provided definition
+      // as-is (no encryption keys needed).
+      const result = await this._dwn.protocols.configure({
+        definition: this._definition,
+      });
+      if (result.status.code === 202) {
+        this._configured = true;
+      }
+      return;
+    }
+
+    // Owner path: derive encryption keys locally when any type needs them.
+    const needsEncryption = Object.values(this._definition.types)
       .some((type) => (type as ProtocolType)?.encryptionRequired === true);
 
     const result = await this._dwn.protocols.configure({
@@ -783,6 +837,46 @@ export class TypedEnbox<
     }
   }
 
+  /**
+   * For delegates: fetch the owner's protocol definition (with `$encryption`
+   * keys) from the remote DWN and install it locally.
+   *
+   * Returns `true` if the remote definition was successfully installed.
+   */
+  private async _autoConfigureDelegateProtocol(): Promise<boolean> {
+    try {
+      const { protocols: remoteProtocols } = await this._dwn.protocols.query({
+        from   : this._dwn.connectedDid,
+        filter : { protocol: this._definition.protocol },
+      });
+
+      if (remoteProtocols.length === 0) {
+        return false;
+      }
+
+      // The remote definition includes `$encryption` keys injected by the
+      // owner's agent during their `protocols.configure({ encryption: true })`
+      // call. Install it as-is on the delegate's local DWN so that:
+      //   1. `encryptionRequired` is enforced locally (matching the remote)
+      //   2. `$encryption` public keys are available for record encryption
+      const remoteDefinition = remoteProtocols[0].definition;
+
+      const result = await this._dwn.protocols.configure({
+        definition: remoteDefinition,
+      });
+
+      if (result.status.code === 202) {
+        this._configured = true;
+        return true;
+      }
+
+      return false;
+    } catch {
+      // Network error or grant issue — fall back to local-only install.
+      return false;
+    }
+  }
+
   /**
    * Protocol-scoped record operations.
    *
@@ -869,10 +963,11 @@ export class TypedEnbox<
         const typeName = lastSegment(normalizedPath);
         const typeEntry = this._definition.types[typeName] as ProtocolType | undefined;
 
-        // Auto-enable encryption when the type requires it, but skip for
-        // delegates — they don't have the owner's keys to derive encryption
-        // keys. The owner's DWN handles encryption on the remote side.
-        const autoEncryption = !this._dwn.isDelegate && typeEntry?.encryptionRequired === true
+        // Auto-enable encryption when the type requires it.
+        // Delegates CAN encrypt because the $encryption public keys in the
+        // synced protocol definition are sufficient for ProtocolPath
+        // encryption — no private key access is needed for writes.
+        const autoEncryption = typeEntry?.encryptionRequired === true
           ? true : undefined;
 
         const { status, record } = await this._dwn.records.write({
@@ -942,7 +1037,10 @@ export class TypedEnbox<
         const typeEntry = this._definition.types[typeName] as ProtocolType | undefined;
 
         const queryFilter = mapParentContextId(request?.filter);
-        const autoEncryption = !this._dwn.isDelegate && typeEntry?.encryptionRequired === true
+        // Auto-enable decryption when the type requires it. Delegates use
+        // delivered ProtocolPath keys from the connect flow; the agent layer
+        // resolves the correct key decrypter automatically.
+        const autoEncryption = typeEntry?.encryptionRequired === true
           ? true : undefined;
 
         const { status, records, cursor } = await this._dwn.records.query({
@@ -998,7 +1096,9 @@ export class TypedEnbox<
         const typeEntry = this._definition.types[typeName] as ProtocolType | undefined;
 
         const readFilter = mapParentContextId(request.filter);
-        const autoEncryption = !this._dwn.isDelegate && typeEntry?.encryptionRequired === true
+        // Auto-enable decryption when the type requires it. See query()
+        // comment for delegate decryption details.
+        const autoEncryption = typeEntry?.encryptionRequired === true
           ? true : undefined;
 
         const { status, record } = await this._dwn.records.read({
@@ -1145,14 +1245,43 @@ function mapParentContextId<T extends Record<string, unknown>>(
 }
 
 /**
- * Compares two protocol definitions for deep equality using deterministic
- * JSON serialization.
+ * Compares two protocol definitions for **logical** equality using
+ * deterministic JSON serialization with `$encryption` blocks stripped.
+ *
+ * When a protocol is installed with `encryption: true`, the agent injects
+ * `$encryption` blocks into the `structure` containing derived public keys.
+ * These blocks are operational metadata — not part of the developer-authored
+ * definition — so they must be ignored during equality checks. Otherwise,
+ * the installed definition (with `$encryption`) would always differ from
+ * the source definition (without `$encryption`), causing false drift
+ * detection and spurious reconfigure warnings.
  *
  * Keys are sorted recursively so that semantically identical definitions
  * with different key ordering are treated as equal.
  */
-function definitionsEqual(a: unknown, b: unknown): boolean {
-  return stableStringify(a) === stableStringify(b);
+export function definitionsEqual(a: unknown, b: unknown): boolean {
+  return stableStringify(stripEncryptionBlocks(a)) === stableStringify(stripEncryptionBlocks(b));
+}
+
+/**
+ * Recursively removes `$encryption` keys from an object tree.
+ * Returns a new object — the original is not mutated.
+ */
+function stripEncryptionBlocks(value: unknown): unknown {
+  if (value === null || value === undefined || typeof value !== 'object') {
+    return value;
+  }
+
+  if (Array.isArray(value)) {
+    return value.map((item) => stripEncryptionBlocks(item));
+  }
+
+  const result: Record<string, unknown> = {};
+  for (const [key, val] of Object.entries(value as Record<string, unknown>)) {
+    if (key === '$encryption') { continue; }
+    result[key] = stripEncryptionBlocks(val);
+  }
+  return result;
 }
 
 /**