@enbox/agent 0.1.4 → 0.1.6

package/dist/types/dwn-api.d.ts

@@ -1,9 +1,10 @@
-import type { DerivedPrivateJwk, DwnConfig, EncryptionKeyDeriver, GenericMessage, ProtocolDefinition } from '@enbox/dwn-sdk-js';
+import type { DerivedPrivateJwk, DwnConfig, EncryptionKeyDeriver, ProtocolDefinition } from '@enbox/dwn-sdk-js';
 import type { PublicKeyJwk } from '@enbox/crypto';
 import { Dwn } from '@enbox/dwn-sdk-js';
 import type { Web5PlatformAgent } from './types/agent.js';
-import type { DwnMessage, DwnMessagesPermissionScope, DwnPermissionScope, DwnRecordsInterfaces, DwnRecordsPermissionScope, DwnResponse, ProcessDwnRequest, SendDwnRequest } from './types/dwn.js';
+import type { DwnResponse, ProcessDwnRequest, SendDwnRequest } from './types/dwn.js';
 import { DwnInterface } from './types/dwn.js';
+export { isDwnMessage, isDwnRequest, isMessagesPermissionScope, isRecordPermissionScope, isRecordsType } from './dwn-type-guards.js';
 type DwnApiParams = {
     agent?: Web5PlatformAgent;
     dwn: Dwn;
@@ -11,11 +12,6 @@ type DwnApiParams = {
 interface DwnApiCreateDwnParams extends Partial<DwnConfig> {
     dataPath?: string;
 }
-export declare function isDwnRequest<T extends DwnInterface>(dwnRequest: ProcessDwnRequest<DwnInterface>, messageType: T): dwnRequest is ProcessDwnRequest<T>;
-export declare function isDwnMessage<T extends DwnInterface>(messageType: T, message: GenericMessage): message is DwnMessage[T];
-export declare function isRecordsType(messageType: DwnInterface): messageType is DwnRecordsInterfaces;
-export declare function isRecordPermissionScope(scope: DwnPermissionScope): scope is DwnRecordsPermissionScope;
-export declare function isMessagesPermissionScope(scope: DwnPermissionScope): scope is DwnMessagesPermissionScope;
 export declare class AgentDwnApi {
     /**
      * Holds the instance of a `Web5PlatformAgent` that represents the current execution context for
@@ -72,131 +68,65 @@ export declare class AgentDwnApi {
     private constructDwnMessage;
     private hasGrantParams;
     private getSigner;
-    /**
-     * Resolves the encryption key info for a given DID.
-     * Looks up the keyAgreement verification method in the DID document,
-     * then resolves the corresponding KMS key URI.
-     *
-     * @param didUri - The DID URI to resolve encryption key info for
-     * @returns keyId (fully qualified verification method ID), keyUri (KMS reference),
-     *          and publicKeyJwk. No private key material is returned.
-     * @throws If the DID has no keyAgreement verification method or it's not X25519.
-     */
-    private getEncryptionKeyInfo;
-    /**
-     * Builds a partial EncryptionInput object for a single key-encryption entry.
-     * The `authenticationTag` is NOT set here — the caller must set it after
-     * AEAD encryption produces the tag.
-     */
-    private buildEncryptionInput;
-    /**
-     * Encrypts plaintext bytes with AEAD (AES-256-GCM by default) and computes
-     * the CID of the resulting ciphertext. Returns everything needed to attach
-     * the encrypted data to a DWN message, including the authentication tag.
-     */
-    private encryptAndComputeCid;
-    /**
-     * Derives a ProtocolContext public key for a given DID and context ID,
-     * then returns a fully-formed EncryptionInput. Consolidates the repeated
-     * getEncryptionKeyInfo → constructKeyDerivationPath → derivePublicKey
-     * → build EncryptionInput sequence.
-     */
-    private deriveContextEncryptionInput;
-    /**
-     * Builds a KMS-backed JWE key unwrap callback. Used for both ProtocolPath
-     * and ProtocolContext decryption where the KMS holds the root private key.
-     */
-    private buildKmsDecryptCallback;
     /**
      * Constructs an EncryptionKeyDeriver callback for the SDK.
-     * The SDK calls derivePublicKey(path), the KMS performs HKDF + public key
-     * computation internally. The private key never leaves the KMS.
-     *
-     * Analogous to getSigner() for signing operations.
+     * Delegates to the standalone function in `dwn-encryption.ts`.
      *
      * @param didUri - The DID URI to create the key deriver for
      * @returns An EncryptionKeyDeriver callback object
      */
     getEncryptionKeyDeriver(didUri: string): Promise<EncryptionKeyDeriver>;
     /**
-     * Constructs a KeyDecrypter callback for the SDK.
-     * The SDK calls decrypt(path, eciesParams), the KMS performs HKDF + ECIES
-     * decryption internally. The private key never leaves the KMS.
-     *
-     * Analogous to getSigner() for signing operations.
+     * Resolves the keyAgreement verification method for the given DID and returns
+     * the key ID, key URI, and public key JWK.
      *
-     * @param didUri - The DID URI to create the key decrypter for
-     * @returns A KeyDecrypter callback object
+     * @param didUri - The DID URI to look up
      */
-    private getKeyDecrypter;
+    private getEncryptionKeyInfo;
     /**
-     * Fetches a protocol definition from the local DWN, with caching.
-     * Returns undefined if the protocol is not installed.
+     * Constructs a ProtocolPath KeyDecrypter for the given DID.
      *
-     * @param tenantDid - The tenant DID to query
-     * @param protocolUri - The protocol URI to fetch
-     * @returns The protocol definition, or undefined if not found
+     * @param didUri - The DID URI to build a decrypter for
      */
-    private getProtocolDefinition;
+    private getKeyDecrypter;
     /**
-     * Checks if a protocol path represents a multi-party context. Returns true
-     * if the root path's subtree contains:
-     *   (a) any `$role: true` descendants, OR
-     *   (b) any relational `who`/`of` `$actions` rules that grant `read` access
-     *       (indicating external authors or recipients need context keys).
+     * Checks if a protocol path represents a multi-party context.
      *
-     * This generalises the earlier `protocolPathHasRoles()` to cover protocols
-     * that use relational access without explicit role definitions.
+     * @param protocolDefinition - The full protocol definition
+     * @param rootProtocolPath - The root protocol path to check
      */
     private isMultiPartyContext;
     /**
-     * Checks whether any relational `who`/`of` rule in the protocol grants
-     * `read` access for a given actor type and ancestor path.
-     *
-     * Walks the *entire* protocol structure looking for any `$actions` rule that:
-     *   - Has `who` equal to `actorType` ('recipient' or 'author'), or any actor
-     *     type if `actorType` is `undefined`
-     *   - Has `of` equal to `ofPath`
-     *   - Has `can` including 'read'
+     * Checks if any `$actions` rule in the protocol grants read access
+     * via `who: '<actorType>'` and `of: '<path>'`.
      *
-     * The search covers all record types in the protocol, since a relational
-     * rule can appear at any level (e.g. `{ who: 'recipient', of: 'thread',
-     * can: ['read'] }` might be defined on `thread/message`).
-     *
-     * @param actorType  - 'author' | 'recipient', or undefined for any
-     * @param ofPath     - The protocol path to check (e.g. 'thread', 'email')
-     * @param protocolDefinition - The full protocol definition
-     * @returns true if a matching relational read rule exists
+     * @param actorType - The actor type to check ('author', 'recipient', or undefined for any)
+     * @param ofPath - The protocol path to check
+     * @param protocolDefinition - The protocol definition
      */
     private hasRelationalReadAccess;
     /**
      * Analyses a record write to determine which DIDs need context key delivery.
      *
-     * Returns a set of participant DIDs that should receive `contextKey` records.
-     * The DWN owner (tenantDid) is always excluded — they have ProtocolPath access.
-     *
-     * Cases handled:
-     *   1. `$role` record with a recipient → recipient is a participant
-     *   2. Record has a recipient and a relational read rule grants access
-     *      via `{ who: 'recipient', of: '<path>', can: ['read'] }`
-     *   3. Record is authored by an external party → if `{ who: 'author', of:
-     *      '<path>', can: ['read'] }` rules grant read access, the author needs
-     *      a context key.
-     *
-     * @param params.protocolDefinition - The installed protocol definition
-     * @param params.protocolPath       - The written record's protocol path
-     * @param params.recipient          - Recipient DID from the record, if any
-     * @param params.tenantDid          - The DWN owner's DID (excluded from results)
-     * @param params.authorDid          - Author DID if externally authored, undefined otherwise
+     * @param params - Parameters for participant detection
      * @returns Set of DIDs that need context key delivery
      */
-    detectNewParticipants({ protocolDefinition, protocolPath, recipient, tenantDid, authorDid }: {
+    detectNewParticipants(params: {
         protocolDefinition: ProtocolDefinition;
         protocolPath: string;
         recipient?: string;
         tenantDid: string;
         authorDid?: string;
     }): Set<string>;
+    /**
+      * Fetches a protocol definition from the local DWN, with caching.
+     * Returns undefined if the protocol is not installed.
+     *
+     * @param tenantDid - The tenant DID to query
+     * @param protocolUri - The protocol URI to fetch
+     * @returns The protocol definition, or undefined if not found
+     */
+    private getProtocolDefinition;
     /**
      * Fetches a protocol definition from a remote DWN.
      * Uses an unsigned ProtocolsQuery (public protocols can be queried anonymously).
@@ -215,59 +145,11 @@ export declare class AgentDwnApi {
      *          record exists yet
      */
     private extractDerivedPublicKey;
-    /**
-     * Reactively upgrades an externally-authored root record that has only
-     * ProtocolPath encryption by appending a ProtocolContext recipient entry.
-     *
-     * After the upgrade, both the owner (ProtocolPath) and context key holders —
-     * including the external author (ProtocolContext) — can decrypt the record.
-     *
-     * Steps:
-     *   1. Decrypt the DEK using the owner's ProtocolPath-derived private key
-     *   2. Derive the context public key from the owner's #enc key
-     *   3. ECIES-encrypt the same DEK to the context public key
-     *   4. Append the ProtocolContext recipient entry (using PR 0b append mode)
-     *   5. Re-sign the record as owner
-     *
-     * The author's signature payload includes an `encryptionCid` that becomes
-     * stale after step 4. The SDK's `validateIntegrity()` skips the encryptionCid
-     * check on the author's signature when an ownerSignature is present (step 5),
-     * since the owner vouches for the updated encryption property.
-     *
-     * NOTE: An alternative design would deliver the DEK out-of-band via the
-     * key-delivery protocol (as a field on the contextKey record) instead of
-     * mutating the record's encryption property. That avoids the stale
-     * encryptionCid concern entirely but adds complexity to the read path and
-     * the contextKey schema. We chose the in-record approach because it keeps
-     * records self-contained and the read/decrypt path unchanged.
-     *
-     * @param tenantDid     - The DWN owner's DID
-     * @param recordsWrite  - The RecordsWrite message to upgrade
-     */
-    private upgradeExternalRootRecord;
-    /**
-     * Resolves the appropriate KeyDecrypter for a record's encryption scheme.
-     * Handles both single-party (ProtocolPath) and multi-party (ProtocolContext).
-     *
-     * For ProtocolContext records:
-     *   - Context creator: derives key directly from KMS
-     *   - Participant: fetches contextKey via key-delivery protocol, caches it
-     */
-    private resolveKeyDecrypter;
-    /**
-     * Builds a KeyDecrypter from a context-derived private key.
-     * Uses the raw key directly (since it was shared with us via the key-delivery protocol).
-     */
-    private buildContextKeyDecrypter;
     /**
      * Post-processes a DWN reply, auto-decrypting data if encryption is enabled.
-     * Delegates to the SDK's Records.decrypt() with the appropriate KeyDecrypter —
-     * resolveKeyDecrypter() selects between ProtocolPath and ProtocolContext schemes.
+     * Delegates to the standalone function in `dwn-encryption.ts`.
      */
     private maybeDecryptReply;
-    /**
-     * FURTHER REFACTORING NEEDED BELOW THIS LINE
-     */
     private getDwnMessage;
     /**
      * Cache for key delivery protocol installation status per tenant.
@@ -276,8 +158,7 @@ export declare class AgentDwnApi {
     private _keyDeliveryProtocolInstalledCache;
     /**
      * Ensures the key delivery protocol is installed on the given tenant's DWN,
-     * with `$encryption` keys injected. Uses the same lazy initialization pattern
-     * as `DwnDataStore.initialize()`.
+     * with `$encryption` keys injected.
      *
      * @param tenantDid - The DID of the DWN owner
      */
@@ -286,27 +167,10 @@ export declare class AgentDwnApi {
      * Writes a `contextKey` record to the owner's DWN, delivering an encrypted
      * context key to a participant.
      *
-     * The payload is encrypted to the **recipient's** ProtocolPath-derived public
-     * key on the key-delivery protocol, so only the recipient can decrypt it.
-     * The recipient's key is supplied via `recipientKeyDeliveryPublicKey` (which
-     * the external author attached as `authorKeyDeliveryPublicKey` on the
-     * original cross-DWN record).
-     *
-     * When `recipientKeyDeliveryPublicKey` is not provided (e.g. the owner is
-     * writing a contextKey for themselves), the record is encrypted to the
-     * owner's own ProtocolPath key using the generic `processRequest` path.
-     *
-     * @param params.tenantDid      - The DWN owner's DID (who is delivering the key)
-     * @param params.recipientDid   - The participant's DID (who will receive the key)
-     * @param params.contextKeyData - The `DerivedPrivateJwk` to deliver
-     * @param params.sourceProtocol - The URI of the source protocol (tag)
-     * @param params.sourceContextId - The root context ID (tag)
-     * @param params.recipientKeyDeliveryPublicKey - The recipient's ProtocolPath-
-     *        derived public key for `key-delivery/contextKey`. When provided,
-     *        the contextKey record is encrypted directly to this key.
+     * @param params - The write parameters
      * @returns The recordId of the written contextKey record
      */
-    writeContextKeyRecord({ tenantDid, recipientDid, contextKeyData, sourceProtocol, sourceContextId, recipientKeyDeliveryPublicKey }: {
+    writeContextKeyRecord(params: {
         tenantDid: string;
         recipientDid: string;
         contextKeyData: DerivedPrivateJwk;
@@ -326,21 +190,14 @@ export declare class AgentDwnApi {
      * Fetches and decrypts a `contextKey` record from a DWN, returning the
      * `DerivedPrivateJwk` payload.
      *
-     * Supports both local reads (tenant queries own DWN) and remote reads
-     * (participant queries the context owner's DWN).
-     *
-     * @param params.ownerDid       - The DWN owner's DID (where contextKey records live)
-     * @param params.requesterDid   - The DID of the requester (used for signing and decryption)
-     * @param params.sourceProtocol - The URI of the source protocol (tag filter)
-     * @param params.sourceContextId - The root context ID (tag filter)
+     * @param params - The fetch parameters
      * @returns The decrypted `DerivedPrivateJwk`, or `undefined` if no matching record found
      */
-    fetchContextKeyRecord({ ownerDid, requesterDid, sourceProtocol, sourceContextId }: {
+    fetchContextKeyRecord(params: {
         ownerDid: string;
         requesterDid: string;
         sourceProtocol: string;
         sourceContextId: string;
     }): Promise<DerivedPrivateJwk | undefined>;
 }
-export {};
 //# sourceMappingURL=dwn-api.d.ts.map

package/dist/types/dwn-api.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"dwn-api.d.ts","sourceRoot":"","sources":["../../src/dwn-api.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"dwn-api.d.ts","sourceRoot":"","sources":["../../src/dwn-api.ts"],"names":[],"mappings":"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"}

package/dist/types/dwn-encryption.d.ts

@@ -0,0 +1,144 @@
+import type { DerivedPrivateJwk, EncryptionInput, EncryptionKeyDeriver, KeyDecrypter, RecordsWriteMessage } from '@enbox/dwn-sdk-js';
+import type { KeyIdentifier, PublicKeyJwk } from '@enbox/crypto';
+import type { Web5PlatformAgent } from './types/agent.js';
+import type { DwnMessageReply, ProcessDwnRequest, SendDwnRequest } from './types/dwn.js';
+import { ContentEncryptionAlgorithm, KeyDerivationScheme } from '@enbox/dwn-sdk-js';
+import { DwnInterface } from './types/dwn.js';
+/**
+ * Returns the correct nonce/IV byte length for the given content encryption algorithm.
+ * A256GCM uses 96-bit (12-byte) nonces; XC20P uses 192-bit (24-byte) nonces.
+ */
+export declare function ivLength(algorithm: ContentEncryptionAlgorithm): number;
+/**
+ * Builds a partial EncryptionInput object for a single key-encryption entry.
+ * The `authenticationTag` is NOT set here — the caller must set it after
+ * AEAD encryption produces the tag.
+ */
+export declare function buildEncryptionInput(dek: Uint8Array, iv: Uint8Array, publicKeyId: string, publicKey: PublicKeyJwk, derivationScheme: typeof KeyDerivationScheme.ProtocolPath | typeof KeyDerivationScheme.ProtocolContext): Omit<EncryptionInput, 'authenticationTag'>;
+/**
+ * Encrypts plaintext bytes with AEAD and computes the CID of the resulting ciphertext.
+ * Returns everything needed to attach the encrypted data to a DWN message, including
+ * the authentication tag.
+ */
+export declare function encryptAndComputeCid(plaintextBytes: Uint8Array, dek: Uint8Array, iv: Uint8Array, algorithm?: ContentEncryptionAlgorithm): Promise<{
+    encryptedBytes: Uint8Array;
+    dataCid: string;
+    dataSize: number;
+    authenticationTag: Uint8Array;
+}>;
+/**
+ * Resolves the encryption key info for a given DID.
+ * Looks up the keyAgreement verification method in the DID document,
+ * then resolves the corresponding KMS key URI.
+ *
+ * @param agent - The platform agent to use for DID resolution and key management
+ * @param didUri - The DID URI to resolve encryption key info for
+ * @returns keyId (fully qualified verification method ID), keyUri (KMS reference),
+ *          and publicKeyJwk. No private key material is returned.
+ * @throws If the DID has no keyAgreement verification method or it's not X25519.
+ */
+export declare function getEncryptionKeyInfo(agent: Web5PlatformAgent, didUri: string): Promise<{
+    keyId: string;
+    keyUri: KeyIdentifier;
+    publicKeyJwk: PublicKeyJwk;
+}>;
+/**
+ * Derives a ProtocolContext public key for a given DID and context ID,
+ * then returns a fully-formed EncryptionInput. Consolidates the repeated
+ * getEncryptionKeyInfo -> constructKeyDerivationPath -> derivePublicKey
+ * -> build EncryptionInput sequence.
+ *
+ * @param agent - The platform agent
+ * @param didUri - The DID URI to derive encryption key for
+ * @param contextId - The context ID
+ * @param dek - Data encryption key
+ * @param iv - Initialization vector
+ */
+export declare function deriveContextEncryptionInput(agent: Web5PlatformAgent, didUri: string, contextId: string, dek: Uint8Array, iv: Uint8Array): Promise<{
+    encryptionInput: Omit<EncryptionInput, 'authenticationTag'>;
+    keyId: string;
+    keyUri: KeyIdentifier;
+    contextDerivationPath: string[];
+}>;
+/**
+ * Builds a KMS-backed JWE key unwrap callback. Used for both ProtocolPath
+ * and ProtocolContext decryption where the KMS holds the root private key.
+ *
+ * @param agent - The platform agent with access to the key manager
+ * @param keyId - The root key ID
+ * @param keyUri - The KMS key URI
+ * @param derivationScheme - The key derivation scheme
+ */
+export declare function buildKmsDecryptCallback(agent: Web5PlatformAgent, keyId: string, keyUri: KeyIdentifier, derivationScheme: typeof KeyDerivationScheme.ProtocolPath | typeof KeyDerivationScheme.ProtocolContext): KeyDecrypter;
+/**
+ * Constructs an EncryptionKeyDeriver callback for the SDK.
+ * The SDK calls derivePublicKey(path), the KMS performs HKDF + public key
+ * computation internally. The private key never leaves the KMS.
+ *
+ * Analogous to getSigner() for signing operations.
+ *
+ * @param agent - The platform agent
+ * @param didUri - The DID URI to create the key deriver for
+ * @returns An EncryptionKeyDeriver callback object
+ */
+export declare function getEncryptionKeyDeriver(agent: Web5PlatformAgent, didUri: string): Promise<EncryptionKeyDeriver>;
+/**
+ * Constructs a ProtocolPath KeyDecrypter.
+ *
+ * @param agent - The platform agent
+ * @param didUri - The DID URI to create the key decrypter for
+ * @returns A KeyDecrypter callback object
+ */
+export declare function getKeyDecrypter(agent: Web5PlatformAgent, didUri: string): Promise<KeyDecrypter>;
+/**
+ * Builds a KeyDecrypter from a context-derived private key.
+ * Uses the raw key directly (since it was shared with us via the key-delivery protocol).
+ *
+ * @param contextKey - The derived private key for the context
+ */
+export declare function buildContextKeyDecrypter(contextKey: DerivedPrivateJwk): KeyDecrypter;
+/**
+ * Resolves the appropriate KeyDecrypter for a record's encryption scheme.
+ * Handles both single-party (ProtocolPath) and multi-party (ProtocolContext).
+ *
+ * For ProtocolContext records:
+ *   - Context creator: derives key directly from KMS
+ *   - Participant: fetches contextKey via key-delivery protocol, caches it
+ *
+ * @param agent - The platform agent
+ * @param authorDid - The DID of the author attempting to decrypt
+ * @param recordsWrite - The records write message containing encryption info
+ * @param targetDid - The target DID (DWN owner), if known
+ * @param contextDerivedKeyCache - Cache for context-derived private keys
+ * @param fetchContextKeyRecordFn - Function to fetch context key records from key-delivery protocol
+ */
+export declare function resolveKeyDecrypter(agent: Web5PlatformAgent, authorDid: string, recordsWrite: RecordsWriteMessage, targetDid: string | undefined, contextDerivedKeyCache: {
+    get(key: string): DerivedPrivateJwk | undefined;
+    set(key: string, value: DerivedPrivateJwk): void;
+}, fetchContextKeyRecordFn: (params: {
+    ownerDid: string;
+    requesterDid: string;
+    sourceProtocol: string;
+    sourceContextId: string;
+}) => Promise<DerivedPrivateJwk | undefined>): Promise<KeyDecrypter>;
+/**
+ * Post-processes a DWN reply, auto-decrypting data if encryption is enabled.
+ * Delegates to the SDK's Records.decrypt() with the appropriate KeyDecrypter —
+ * resolveKeyDecrypter() selects between ProtocolPath and ProtocolContext schemes.
+ *
+ * @param request - The original DWN request
+ * @param reply - The DWN reply to process
+ * @param agent - The platform agent
+ * @param contextDerivedKeyCache - Cache for context-derived private keys
+ * @param fetchContextKeyRecordFn - Function to fetch context key records
+ */
+export declare function maybeDecryptReply<T extends DwnInterface>(request: ProcessDwnRequest<T> | SendDwnRequest<T>, reply: DwnMessageReply[T], agent: Web5PlatformAgent, contextDerivedKeyCache: {
+    get(key: string): DerivedPrivateJwk | undefined;
+    set(key: string, value: DerivedPrivateJwk): void;
+}, fetchContextKeyRecordFn: (params: {
+    ownerDid: string;
+    requesterDid: string;
+    sourceProtocol: string;
+    sourceContextId: string;
+}) => Promise<DerivedPrivateJwk | undefined>): Promise<void>;
+//# sourceMappingURL=dwn-encryption.d.ts.map

package/dist/types/dwn-encryption.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dwn-encryption.d.ts","sourceRoot":"","sources":["../../src/dwn-encryption.ts"],"names":[],"mappings":"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"}

package/dist/types/dwn-key-delivery.d.ts

@@ -0,0 +1,112 @@
+import type { PublicKeyJwk } from '@enbox/crypto';
+import type { DerivedPrivateJwk } from '@enbox/dwn-sdk-js';
+import type { Web5PlatformAgent } from './types/agent.js';
+import type { DwnMessage, DwnMessageReply, ProcessDwnRequest } from './types/dwn.js';
+import { DwnInterface } from './types/dwn.js';
+/**
+ * Parameters for writeContextKeyRecord.
+ */
+export type WriteContextKeyParams = {
+    tenantDid: string;
+    recipientDid: string;
+    contextKeyData: DerivedPrivateJwk;
+    sourceProtocol: string;
+    sourceContextId: string;
+    recipientKeyDeliveryPublicKey?: {
+        rootKeyId: string;
+        publicKeyJwk: PublicKeyJwk;
+    };
+};
+/**
+ * Parameters for fetchContextKeyRecord.
+ */
+export type FetchContextKeyParams = {
+    ownerDid: string;
+    requesterDid: string;
+    sourceProtocol: string;
+    sourceContextId: string;
+};
+/** Callback type for processRequest, used by key-delivery functions. */
+type ProcessRequestFn = <T extends DwnInterface>(request: ProcessDwnRequest<T>) => Promise<{
+    reply: DwnMessageReply[T];
+    message?: DwnMessage[T];
+    messageCid: string;
+}>;
+/**
+ * Ensures the key delivery protocol is installed on the given tenant's DWN,
+ * with `$encryption` keys injected. Uses the same lazy initialization pattern
+ * as `DwnDataStore.initialize()`.
+ *
+ * @param agent - The platform agent
+ * @param tenantDid - The DID of the DWN owner
+ * @param processRequest - The agent's processRequest method (bound)
+ * @param getProtocolDefinition - Function to get a protocol definition
+ * @param installedCache - Cache for installation status
+ */
+export declare function ensureKeyDeliveryProtocol(agent: Web5PlatformAgent, tenantDid: string, processRequest: ProcessRequestFn, getProtocolDefinition: (tenantDid: string, protocolUri: string) => Promise<any>, installedCache: {
+    get(key: string): boolean | undefined;
+    set(key: string, value: boolean): void;
+    delete(key: string): void;
+}, protocolDefinitionCache: {
+    delete(key: string): void;
+}): Promise<void>;
+/**
+ * Writes a `contextKey` record to the owner's DWN, delivering an encrypted
+ * context key to a participant.
+ *
+ * The payload is encrypted to the **recipient's** ProtocolPath-derived public
+ * key on the key-delivery protocol, so only the recipient can decrypt it.
+ *
+ * @param agent - The platform agent
+ * @param params - The write parameters
+ * @param processRequest - The agent's processRequest method (bound)
+ * @param ensureProtocol - Function to ensure key delivery protocol is installed
+ * @param eagerSend - Function to eagerly send the record to the remote DWN
+ * @returns The recordId of the written contextKey record
+ */
+export declare function writeContextKeyRecord(agent: Web5PlatformAgent, params: WriteContextKeyParams, processRequest: ProcessRequestFn, ensureProtocol: (tenantDid: string) => Promise<void>, eagerSend: (tenantDid: string, message: DwnMessage[DwnInterface.RecordsWrite]) => Promise<void>): Promise<string>;
+/**
+ * Eagerly sends a contextKey record to the tenant's remote DWN.
+ * This is best-effort — sync guarantees eventual consistency regardless.
+ *
+ * @param agent - The platform agent
+ * @param tenantDid - The DWN owner's DID
+ * @param contextKeyMessage - The context key message to send
+ * @param getDwnMessage - Function to read a full message from local DWN
+ * @param sendDwnRpcRequest - Function to send a DWN RPC request
+ */
+export declare function eagerSendContextKeyRecord(agent: Web5PlatformAgent, tenantDid: string, contextKeyMessage: DwnMessage[DwnInterface.RecordsWrite], getDwnMessage: (params: {
+    author: string;
+    messageType: DwnInterface;
+    messageCid: string;
+}) => Promise<{
+    message: any;
+    data?: Blob;
+}>, sendDwnRpcRequest: (params: {
+    targetDid: string;
+    dwnEndpointUrls: string[];
+    message: any;
+    data?: Blob;
+}) => Promise<any>): Promise<void>;
+/**
+ * Fetches and decrypts a `contextKey` record from a DWN, returning the
+ * `DerivedPrivateJwk` payload.
+ *
+ * Supports both local reads (tenant queries own DWN) and remote reads
+ * (participant queries the context owner's DWN).
+ *
+ * @param agent - The platform agent
+ * @param params - The fetch parameters
+ * @param processRequest - The agent's processRequest method (bound)
+ * @param getSigner - Function to get a signer for a DID
+ * @param sendDwnRpcRequest - Function to send a DWN RPC request
+ * @returns The decrypted `DerivedPrivateJwk`, or `undefined` if no matching record found
+ */
+export declare function fetchContextKeyRecord(agent: Web5PlatformAgent, params: FetchContextKeyParams, processRequest: ProcessRequestFn, getSigner: (author: string) => Promise<any>, sendDwnRpcRequest: (params: {
+    targetDid: string;
+    dwnEndpointUrls: string[];
+    message: any;
+    data?: Blob;
+}) => Promise<any>): Promise<DerivedPrivateJwk | undefined>;
+export {};
+//# sourceMappingURL=dwn-key-delivery.d.ts.map

package/dist/types/dwn-key-delivery.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dwn-key-delivery.d.ts","sourceRoot":"","sources":["../../src/dwn-key-delivery.ts"],"names":[],"mappings":"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"}

package/dist/types/dwn-record-upgrade.d.ts

@@ -0,0 +1,33 @@
+import type { KeyIdentifier } from '@enbox/crypto';
+import type { Dwn, RecordsWriteMessage } from '@enbox/dwn-sdk-js';
+import type { DwnSigner } from './types/dwn.js';
+import type { Web5PlatformAgent } from './types/agent.js';
+/**
+ * Reactively upgrades an externally-authored root record that has only
+ * ProtocolPath encryption by appending a ProtocolContext recipient entry.
+ *
+ * After the upgrade, both the owner (ProtocolPath) and context key holders —
+ * including the external author (ProtocolContext) — can decrypt the record.
+ *
+ * Steps:
+ *   1. Decrypt the DEK using the owner's ProtocolPath-derived private key
+ *   2. Derive the context public key from the owner's #enc key
+ *   3. ECIES-encrypt the same DEK to the context public key
+ *   4. Append the ProtocolContext recipient entry (using PR 0b append mode)
+ *   5. Re-sign the record as owner
+ *
+ * @param agent - The platform agent
+ * @param tenantDid - The DWN owner's DID
+ * @param recordsWrite - The RecordsWrite message to upgrade
+ * @param dwn - The DWN instance
+ * @param getSigner - Function to get a DWN signer
+ * @param contextKeyCache - Cache for context key info
+ */
+export declare function upgradeExternalRootRecord(agent: Web5PlatformAgent, tenantDid: string, recordsWrite: RecordsWriteMessage, dwn: Dwn, getSigner: (author: string) => Promise<DwnSigner>, contextKeyCache: {
+    set(key: string, value: {
+        keyId: string;
+        keyUri: KeyIdentifier;
+        contextDerivationPath: string[];
+    }): void;
+}): Promise<void>;
+//# sourceMappingURL=dwn-record-upgrade.d.ts.map

package/dist/types/dwn-record-upgrade.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dwn-record-upgrade.d.ts","sourceRoot":"","sources":["../../src/dwn-record-upgrade.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AACnD,OAAO,KAAK,EACV,GAAG,EAIH,mBAAmB,EACpB,MAAM,mBAAmB,CAAC;AAE3B,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAChD,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AAY1D;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAsB,yBAAyB,CAC7C,KAAK,EAAE,iBAAiB,EACxB,SAAS,EAAE,MAAM,EACjB,YAAY,EAAE,mBAAmB,EACjC,GAAG,EAAE,GAAG,EACR,SAAS,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,OAAO,CAAC,SAAS,CAAC,EACjD,eAAe,EAAE;IAAE,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,aAAa,CAAC;QAAC,qBAAqB,EAAE,MAAM,EAAE,CAAA;KAAE,GAAG,IAAI,CAAA;CAAE,GAC5H,OAAO,CAAC,IAAI,CAAC,CAmHf"}

package/dist/types/dwn-type-guards.d.ts

@@ -0,0 +1,9 @@
+import type { GenericMessage } from '@enbox/dwn-sdk-js';
+import type { DwnMessage, DwnMessagesPermissionScope, DwnPermissionScope, DwnRecordsInterfaces, DwnRecordsPermissionScope, ProcessDwnRequest } from './types/dwn.js';
+import { DwnInterface } from './types/dwn.js';
+export declare function isDwnRequest<T extends DwnInterface>(dwnRequest: ProcessDwnRequest<DwnInterface>, messageType: T): dwnRequest is ProcessDwnRequest<T>;
+export declare function isDwnMessage<T extends DwnInterface>(messageType: T, message: GenericMessage): message is DwnMessage[T];
+export declare function isRecordsType(messageType: DwnInterface): messageType is DwnRecordsInterfaces;
+export declare function isRecordPermissionScope(scope: DwnPermissionScope): scope is DwnRecordsPermissionScope;
+export declare function isMessagesPermissionScope(scope: DwnPermissionScope): scope is DwnMessagesPermissionScope;
+//# sourceMappingURL=dwn-type-guards.d.ts.map

package/dist/types/dwn-type-guards.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dwn-type-guards.d.ts","sourceRoot":"","sources":["../../src/dwn-type-guards.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AAExD,OAAO,KAAK,EACV,UAAU,EACV,0BAA0B,EAC1B,kBAAkB,EAClB,oBAAoB,EACpB,yBAAyB,EACzB,iBAAiB,EAClB,MAAM,gBAAgB,CAAC;AAIxB,OAAO,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAE9C,wBAAgB,YAAY,CAAC,CAAC,SAAS,YAAY,EACjD,UAAU,EAAE,iBAAiB,CAAC,YAAY,CAAC,EAAE,WAAW,EAAE,CAAC,GAC1D,UAAU,IAAI,iBAAiB,CAAC,CAAC,CAAC,CAEpC;AAED,wBAAgB,YAAY,CAAC,CAAC,SAAS,YAAY,EACjD,WAAW,EAAE,CAAC,EAAE,OAAO,EAAE,cAAc,GACtC,OAAO,IAAI,UAAU,CAAC,CAAC,CAAC,CAG1B;AAED,wBAAgB,aAAa,CAAC,WAAW,EAAE,YAAY,GAAG,WAAW,IAAI,oBAAoB,CAM5F;AAED,wBAAgB,uBAAuB,CAAC,KAAK,EAAE,kBAAkB,GAAG,KAAK,IAAI,yBAAyB,CAErG;AAED,wBAAgB,yBAAyB,CAAC,KAAK,EAAE,kBAAkB,GAAG,KAAK,IAAI,0BAA0B,CAExG"}