@enbox/agent 0.1.4 → 0.1.6

package/dist/esm/dwn-key-delivery.js

@@ -0,0 +1,256 @@
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+import { ContentEncryptionAlgorithm, DataStream, KeyDerivationScheme, Message, Protocols, Records, } from '@enbox/dwn-sdk-js';
+import { getDwnServiceEndpointUrls } from './utils.js';
+import { KeyDeliveryProtocolDefinition } from './store-data-protocols.js';
+import { buildEncryptionInput, encryptAndComputeCid, getEncryptionKeyDeriver, getKeyDecrypter, ivLength } from './dwn-encryption.js';
+import { DwnInterface, dwnMessageConstructors } from './types/dwn.js';
+/**
+ * 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 function ensureKeyDeliveryProtocol(agent, tenantDid, processRequest, getProtocolDefinition, installedCache, protocolDefinitionCache) {
+    return __awaiter(this, void 0, void 0, function* () {
+        if (installedCache.get(tenantDid)) {
+            return;
+        }
+        const protocolUri = KeyDeliveryProtocolDefinition.protocol;
+        const existing = yield getProtocolDefinition(tenantDid, protocolUri);
+        if (!existing) {
+            // Derive and inject $encryption keys for each type path
+            const keyDeriver = yield getEncryptionKeyDeriver(agent, tenantDid);
+            const definitionWithKeys = yield Protocols.deriveAndInjectPublicEncryptionKeys(KeyDeliveryProtocolDefinition, keyDeriver);
+            const { reply: { status } } = yield processRequest({
+                author: tenantDid,
+                target: tenantDid,
+                messageType: DwnInterface.ProtocolsConfigure,
+                messageParams: { definition: definitionWithKeys },
+            });
+            if (status.code !== 202) {
+                throw new Error(`AgentDwnApi: Failed to install key delivery protocol: ${status.code} - ${status.detail}`);
+            }
+            // Invalidate protocol definition cache so subsequent reads pick up the new definition
+            protocolDefinitionCache.delete(`${tenantDid}~${protocolUri}`);
+        }
+        installedCache.set(tenantDid, true);
+    });
+}
+/**
+ * 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 function writeContextKeyRecord(agent, params, processRequest, ensureProtocol, eagerSend) {
+    return __awaiter(this, void 0, void 0, function* () {
+        const { tenantDid, recipientDid, contextKeyData, sourceProtocol, sourceContextId, recipientKeyDeliveryPublicKey } = params;
+        // Ensure the key delivery protocol is installed on the owner's DWN
+        yield ensureProtocol(tenantDid);
+        const protocolUri = KeyDeliveryProtocolDefinition.protocol;
+        // Serialize the payload to JSON bytes
+        const plaintextBytes = new TextEncoder().encode(JSON.stringify(contextKeyData));
+        // Common contextKey record parameters
+        const contextKeyParams = {
+            protocol: protocolUri,
+            protocolPath: 'contextKey',
+            dataFormat: 'application/json',
+            recipient: recipientDid,
+            tags: { protocol: sourceProtocol, contextId: sourceContextId },
+        };
+        let message;
+        let status;
+        if (recipientKeyDeliveryPublicKey) {
+            // --- Encrypt to the recipient's ProtocolPath key (cross-DWN delivery) ---
+            // Manually build encryption input targeting the recipient's key so the
+            // record is decryptable only by the recipient.
+            const algorithm = ContentEncryptionAlgorithm.A256GCM;
+            const dataEncryptionKey = crypto.getRandomValues(new Uint8Array(32));
+            const dataEncryptionIV = crypto.getRandomValues(new Uint8Array(ivLength(algorithm)));
+            const { encryptedBytes, dataCid, dataSize, authenticationTag } = yield encryptAndComputeCid(plaintextBytes, dataEncryptionKey, dataEncryptionIV, algorithm);
+            const encryptionInput = Object.assign(Object.assign({}, buildEncryptionInput(dataEncryptionKey, dataEncryptionIV, recipientKeyDeliveryPublicKey.rootKeyId, recipientKeyDeliveryPublicKey.publicKeyJwk, KeyDerivationScheme.ProtocolPath)), { authenticationTag });
+            ({ message, reply: { status } } = yield processRequest({
+                author: tenantDid,
+                target: tenantDid,
+                messageType: DwnInterface.RecordsWrite,
+                messageParams: Object.assign(Object.assign({}, contextKeyParams), { dataCid, dataSize, encryptionInput }),
+                dataStream: new Blob([encryptedBytes]),
+            }));
+        }
+        else {
+            // --- Fallback: encrypt to the owner's key (local self-delivery) ---
+            // When no recipient key is provided, use the generic processRequest
+            // encryption path which encrypts to the DWN owner's ProtocolPath key.
+            ({ message, reply: { status } } = yield processRequest({
+                author: tenantDid,
+                target: tenantDid,
+                messageType: DwnInterface.RecordsWrite,
+                messageParams: contextKeyParams,
+                dataStream: new Blob([plaintextBytes], { type: 'application/json' }),
+                encryption: true,
+            }));
+        }
+        if (!(message && status.code === 202)) {
+            throw new Error(`AgentDwnApi: Failed to write contextKey record for ${recipientDid}: ${status.code} - ${status.detail}`);
+        }
+        // Eagerly send the contextKey record to the tenant's remote DWN so that
+        // participants can fetch it immediately without waiting for sync.
+        // This is fire-and-forget — sync will guarantee eventual consistency.
+        eagerSend(tenantDid, message).catch((err) => {
+            console.warn(`AgentDwnApi: Eager send of contextKey record '${message.recordId}' ` +
+                `to remote DWN failed: ${err.message}. Sync will deliver it later.`);
+        });
+        return message.recordId;
+    });
+}
+/**
+ * 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 function eagerSendContextKeyRecord(agent, tenantDid, contextKeyMessage, getDwnMessage, sendDwnRpcRequest) {
+    return __awaiter(this, void 0, void 0, function* () {
+        let dwnEndpointUrls;
+        try {
+            dwnEndpointUrls = yield getDwnServiceEndpointUrls(tenantDid, agent.did);
+        }
+        catch (_a) {
+            // DID resolution or endpoint lookup failed — not fatal, sync will handle it.
+            return;
+        }
+        if (dwnEndpointUrls.length === 0) {
+            return;
+        }
+        // Read the full message (including data blob) from the local DWN
+        const { data } = yield getDwnMessage({
+            author: tenantDid,
+            messageType: DwnInterface.RecordsWrite,
+            messageCid: yield Message.getCid(contextKeyMessage),
+        });
+        yield sendDwnRpcRequest({
+            targetDid: tenantDid,
+            dwnEndpointUrls,
+            message: contextKeyMessage,
+            data,
+        });
+    });
+}
+/**
+ * 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 function fetchContextKeyRecord(agent, params, processRequest, getSigner, sendDwnRpcRequest) {
+    return __awaiter(this, void 0, void 0, function* () {
+        var _a, _b, _c, _d, _e;
+        const { ownerDid, requesterDid, sourceProtocol, sourceContextId } = params;
+        const protocolUri = KeyDeliveryProtocolDefinition.protocol;
+        const isLocal = ownerDid === requesterDid;
+        // Shared query filter for both local and remote paths
+        const contextKeyFilter = {
+            protocol: protocolUri,
+            protocolPath: 'contextKey',
+            recipient: requesterDid,
+            tags: { protocol: sourceProtocol, contextId: sourceContextId },
+        };
+        /** Parse decrypted bytes into a DerivedPrivateJwk. */
+        const parsePayload = (bytes) => JSON.parse(new TextDecoder().decode(bytes));
+        if (isLocal) {
+            // Local query: owner queries their own DWN
+            const { reply } = yield processRequest({
+                author: requesterDid,
+                target: ownerDid,
+                messageType: DwnInterface.RecordsQuery,
+                messageParams: { filter: contextKeyFilter },
+            });
+            if (reply.status.code !== 200 || !((_a = reply.entries) === null || _a === void 0 ? void 0 : _a.length)) {
+                return undefined;
+            }
+            // Read the full record to get the data (auto-decrypted by processRequest)
+            const recordId = reply.entries[0].recordId;
+            const { reply: readReply } = yield processRequest({
+                author: requesterDid,
+                target: ownerDid,
+                messageType: DwnInterface.RecordsRead,
+                messageParams: { filter: { recordId } },
+                encryption: true,
+            });
+            const readResult = readReply;
+            if (!((_b = readResult.entry) === null || _b === void 0 ? void 0 : _b.data)) {
+                return undefined;
+            }
+            return parsePayload(yield DataStream.toBytes(readResult.entry.data));
+        }
+        else {
+            // Remote query: participant queries the context owner's DWN
+            const signer = yield getSigner(requesterDid);
+            const dwnEndpointUrls = yield getDwnServiceEndpointUrls(ownerDid, agent.did);
+            const recordsQuery = yield dwnMessageConstructors[DwnInterface.RecordsQuery].create({
+                signer,
+                filter: contextKeyFilter,
+            });
+            const queryReply = yield sendDwnRpcRequest({
+                targetDid: ownerDid,
+                dwnEndpointUrls,
+                message: recordsQuery.message,
+            });
+            if (queryReply.status.code !== 200 || !((_c = queryReply.entries) === null || _c === void 0 ? void 0 : _c.length)) {
+                return undefined;
+            }
+            // Read the full record remotely
+            const recordId = queryReply.entries[0].recordId;
+            const recordsRead = yield dwnMessageConstructors[DwnInterface.RecordsRead].create({
+                signer,
+                filter: { recordId },
+            });
+            const readReply = yield sendDwnRpcRequest({
+                targetDid: ownerDid,
+                dwnEndpointUrls,
+                message: recordsRead.message,
+            });
+            if (!((_d = readReply.entry) === null || _d === void 0 ? void 0 : _d.data) || !((_e = readReply.entry) === null || _e === void 0 ? void 0 : _e.recordsWrite)) {
+                return undefined;
+            }
+            // Decrypt the contextKey payload using the requester's key-delivery protocol path key
+            const keyDecrypter = yield getKeyDecrypter(agent, requesterDid);
+            const decryptedStream = yield Records.decrypt(readReply.entry.recordsWrite, keyDecrypter, readReply.entry.data);
+            return parsePayload(yield DataStream.toBytes(decryptedStream));
+        }
+    });
+}
+//# sourceMappingURL=dwn-key-delivery.js.map

package/dist/esm/dwn-key-delivery.js.map

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

package/dist/esm/dwn-record-upgrade.js

@@ -0,0 +1,119 @@
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+import { Encoder, KeyDerivationScheme, Message, Records, } from '@enbox/dwn-sdk-js';
+import { deriveContextEncryptionInput, getKeyDecrypter } from './dwn-encryption.js';
+import { DwnInterface, dwnMessageConstructors } from './types/dwn.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 function upgradeExternalRootRecord(agent, tenantDid, recordsWrite, dwn, getSigner, contextKeyCache) {
+    return __awaiter(this, void 0, void 0, function* () {
+        const { encryption } = recordsWrite;
+        if (!encryption) {
+            return;
+        }
+        // Verify: has ProtocolPath but NOT ProtocolContext
+        const hasProtocolPath = encryption.recipients.some((r) => r.header.derivationScheme === KeyDerivationScheme.ProtocolPath);
+        const hasProtocolContext = encryption.recipients.some((r) => r.header.derivationScheme === KeyDerivationScheme.ProtocolContext);
+        if (!hasProtocolPath || hasProtocolContext) {
+            return;
+        }
+        // 1. Decrypt the DEK using the owner's ProtocolPath key
+        const keyDecrypter = yield getKeyDecrypter(agent, tenantDid);
+        // Find the ProtocolPath recipient entry
+        const pathRecipient = encryption.recipients.find((r) => r.header.derivationScheme === KeyDerivationScheme.ProtocolPath);
+        const fullDerivationPath = Records.constructKeyDerivationPathUsingProtocolPathScheme(recordsWrite.descriptor);
+        const dataEncryptionKey = yield keyDecrypter.decrypt(fullDerivationPath, {
+            encryptedKey: Encoder.base64UrlToBytes(pathRecipient.encrypted_key),
+            ephemeralPublicKey: pathRecipient.header.epk,
+        });
+        // 2. Derive the context public key — contextId = recordId for root records
+        const contextId = recordsWrite.recordId;
+        const encryptionIV = Encoder.base64UrlToBytes(encryption.iv);
+        // 3 & 4. Append the ProtocolContext recipient entry using append mode.
+        // Append mode preserves the author's identity and authorization so that
+        // signAsOwner() can be called in step 5.
+        const { encryptionInput: contextEncryptionInput, keyId, keyUri, contextDerivationPath } = yield deriveContextEncryptionInput(agent, tenantDid, contextId, dataEncryptionKey, encryptionIV);
+        // Set the authentication tag from the existing JWE encryption property
+        const fullContextInput = Object.assign(Object.assign({}, contextEncryptionInput), { authenticationTag: Encoder.base64UrlToBytes(encryption.tag) });
+        // Parse the message to get a RecordsWrite instance we can mutate
+        const recordsWriteInstance = yield dwnMessageConstructors[DwnInterface.RecordsWrite].parse(recordsWrite);
+        yield recordsWriteInstance.encryptSymmetricEncryptionKey(fullContextInput, { append: true });
+        // 5. Re-sign as owner — the author's signature is preserved but its
+        // encryptionCid is now stale; the owner's signature vouches for the
+        // updated encryption property.
+        const signer = yield getSigner(tenantDid);
+        yield recordsWriteInstance.signAsOwner(signer);
+        // Store the upgraded message directly via the message store, bypassing
+        // the handler's conflict resolution which doesn't support same-timestamp
+        // owner-augmented replacements. The data is unchanged — only the encryption
+        // metadata and authorization are updated.
+        //
+        // We must also update the state index and event stream to keep sync and
+        // real-time subscribers consistent — without this, the upgraded record
+        // would never propagate to remote DWNs or notify subscribers.
+        const { messageStore, stateIndex, eventStream } = dwn.storage;
+        // Validate the upgrade only changed encryption and authorization fields.
+        // The descriptor, recordId, contextId, and data must remain identical.
+        // Note: parse() may produce a new descriptor object, so we compare by value.
+        const upgradedMessage = recordsWriteInstance.message;
+        if (JSON.stringify(upgradedMessage.descriptor) !== JSON.stringify(recordsWrite.descriptor)) {
+            throw new Error('AgentDwnApi: upgradeExternalRootRecord() must not modify the descriptor.');
+        }
+        if (upgradedMessage.recordId !== recordsWrite.recordId) {
+            throw new Error('AgentDwnApi: upgradeExternalRootRecord() must not modify the recordId.');
+        }
+        // Fetch the stored original (which carries encodedData for small payloads)
+        const originalCid = yield Message.getCid(recordsWrite);
+        const storedOriginal = yield messageStore.get(tenantDid, originalCid);
+        // Build indexes for the upgraded message (mark as latest base state)
+        const isLatestBaseState = true;
+        const upgradedIndexes = yield recordsWriteInstance.constructIndexes(isLatestBaseState);
+        // Carry over the encoded data from the stored original (the handler
+        // base64url-encodes small payloads into encodedData during processMessage)
+        if (storedOriginal === null || storedOriginal === void 0 ? void 0 : storedOriginal.encodedData) {
+            upgradedMessage.encodedData = storedOriginal.encodedData;
+        }
+        // Use put-before-delete ordering: if a crash occurs after the put but
+        // before the delete, we end up with a duplicate (recoverable via the
+        // isLatestBaseState index) rather than data loss (unrecoverable).
+        const upgradedCid = yield Message.getCid(upgradedMessage);
+        yield messageStore.put(tenantDid, upgradedMessage, upgradedIndexes);
+        yield stateIndex.insert(tenantDid, upgradedCid, upgradedIndexes);
+        // Now remove the original message and its state index entry.
+        yield messageStore.delete(tenantDid, originalCid);
+        yield stateIndex.delete(tenantDid, [originalCid]);
+        // Notify real-time subscribers (mirrors handler behavior)
+        if (eventStream !== undefined) {
+            eventStream.emit(tenantDid, { message: upgradedMessage }, upgradedIndexes);
+        }
+        // Cache context key info for subsequent writes in this context
+        contextKeyCache.set(contextId, { keyId, keyUri, contextDerivationPath });
+    });
+}
+//# sourceMappingURL=dwn-record-upgrade.js.map

package/dist/esm/dwn-record-upgrade.js.map

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

package/dist/esm/dwn-type-guards.js

@@ -0,0 +1,23 @@
+import { DwnInterfaceName } from '@enbox/dwn-sdk-js';
+import { DwnInterface } from './types/dwn.js';
+export function isDwnRequest(dwnRequest, messageType) {
+    return dwnRequest.messageType === messageType;
+}
+export function isDwnMessage(messageType, message) {
+    const incomingMessageInterfaceName = message.descriptor.interface + message.descriptor.method;
+    return incomingMessageInterfaceName === messageType;
+}
+export function isRecordsType(messageType) {
+    return messageType === DwnInterface.RecordsDelete ||
+        messageType === DwnInterface.RecordsQuery ||
+        messageType === DwnInterface.RecordsRead ||
+        messageType === DwnInterface.RecordsSubscribe ||
+        messageType === DwnInterface.RecordsWrite;
+}
+export function isRecordPermissionScope(scope) {
+    return scope.interface === DwnInterfaceName.Records;
+}
+export function isMessagesPermissionScope(scope) {
+    return scope.interface === DwnInterfaceName.Messages;
+}
+//# sourceMappingURL=dwn-type-guards.js.map

package/dist/esm/dwn-type-guards.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"dwn-type-guards.js","sourceRoot":"","sources":["../../src/dwn-type-guards.ts"],"names":[],"mappings":"AAWA,OAAO,EAAE,gBAAgB,EAAE,MAAM,mBAAmB,CAAC;AAErD,OAAO,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAE9C,MAAM,UAAU,YAAY,CAC1B,UAA2C,EAAE,WAAc;IAE3D,OAAO,UAAU,CAAC,WAAW,KAAK,WAAW,CAAC;AAChD,CAAC;AAED,MAAM,UAAU,YAAY,CAC1B,WAAc,EAAE,OAAuB;IAEvC,MAAM,4BAA4B,GAAG,OAAO,CAAC,UAAU,CAAC,SAAS,GAAG,OAAO,CAAC,UAAU,CAAC,MAAM,CAAC;IAC9F,OAAO,4BAA4B,KAAK,WAAW,CAAC;AACtD,CAAC;AAED,MAAM,UAAU,aAAa,CAAC,WAAyB;IACrD,OAAO,WAAW,KAAK,YAAY,CAAC,aAAa;QAC/C,WAAW,KAAK,YAAY,CAAC,YAAY;QACzC,WAAW,KAAK,YAAY,CAAC,WAAW;QACxC,WAAW,KAAK,YAAY,CAAC,gBAAgB;QAC7C,WAAW,KAAK,YAAY,CAAC,YAAY,CAAC;AAC9C,CAAC;AAED,MAAM,UAAU,uBAAuB,CAAC,KAAyB;IAC/D,OAAO,KAAK,CAAC,SAAS,KAAK,gBAAgB,CAAC,OAAO,CAAC;AACtD,CAAC;AAED,MAAM,UAAU,yBAAyB,CAAC,KAAyB;IACjE,OAAO,KAAK,CAAC,SAAS,KAAK,gBAAgB,CAAC,QAAQ,CAAC;AACvD,CAAC"}

package/dist/esm/index.js

@@ -1,9 +1,15 @@
 export * from './types/dwn.js';
 export * from './agent-did-resolver-cache.js';
+export * from './anonymous-dwn-api.js';
 export * from './bearer-identity.js';
 export * from './crypto-api.js';
 export * from './did-api.js';
 export * from './dwn-api.js';
+export * from './dwn-encryption.js';
+export * from './dwn-key-delivery.js';
+export * from './dwn-record-upgrade.js';
+export * from './dwn-type-guards.js';
+export * from './protocol-utils.js';
 export * from './hd-identity-vault.js';
 export * from './identity-api.js';
 export * from './local-key-manager.js';

package/dist/esm/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AACA,cAAc,gBAAgB,CAAC;AAQ/B,cAAc,+BAA+B,CAAC;AAC9C,cAAc,sBAAsB,CAAC;AACrC,cAAc,iBAAiB,CAAC;AAChC,cAAc,cAAc,CAAC;AAC7B,cAAc,cAAc,CAAC;AAC7B,cAAc,wBAAwB,CAAC;AACvC,cAAc,mBAAmB,CAAC;AAClC,cAAc,wBAAwB,CAAC;AACvC,cAAc,sBAAsB,CAAC;AACrC,cAAc,iBAAiB,CAAC;AAChC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,qBAAqB,CAAC;AACpC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,eAAe,CAAC;AAC9B,cAAc,wBAAwB,CAAC;AACvC,cAAc,mBAAmB,CAAC;AAClC,cAAc,YAAY,CAAC;AAC3B,cAAc,cAAc,CAAC;AAC7B,cAAc,WAAW,CAAC;AAC1B,cAAc,sBAAsB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AACA,cAAc,gBAAgB,CAAC;AAQ/B,cAAc,+BAA+B,CAAC;AAC9C,cAAc,wBAAwB,CAAC;AACvC,cAAc,sBAAsB,CAAC;AACrC,cAAc,iBAAiB,CAAC;AAChC,cAAc,cAAc,CAAC;AAC7B,cAAc,cAAc,CAAC;AAC7B,cAAc,qBAAqB,CAAC;AACpC,cAAc,uBAAuB,CAAC;AACtC,cAAc,yBAAyB,CAAC;AACxC,cAAc,sBAAsB,CAAC;AACrC,cAAc,qBAAqB,CAAC;AACpC,cAAc,wBAAwB,CAAC;AACvC,cAAc,mBAAmB,CAAC;AAClC,cAAc,wBAAwB,CAAC;AACvC,cAAc,sBAAsB,CAAC;AACrC,cAAc,iBAAiB,CAAC;AAChC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,qBAAqB,CAAC;AACpC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,eAAe,CAAC;AAC9B,cAAc,wBAAwB,CAAC;AACvC,cAAc,mBAAmB,CAAC;AAClC,cAAc,YAAY,CAAC;AAC3B,cAAc,cAAc,CAAC;AAC7B,cAAc,WAAW,CAAC;AAC1B,cAAc,sBAAsB,CAAC"}

package/dist/esm/protocol-utils.js

@@ -0,0 +1,158 @@
+/**
+ * Navigates a protocol definition's structure to find the rule set at a given protocol path.
+ * @param protocolDefinition - The protocol definition to search
+ * @param protocolPath - The dot-separated protocol path (e.g. 'thread/message')
+ * @returns The rule set at the given path, or undefined if the path doesn't exist
+ */
+export function getRuleSetAtPath(protocolDefinition, protocolPath) {
+    const segments = protocolPath.split('/');
+    let ruleSet = protocolDefinition.structure;
+    for (const segment of segments) {
+        ruleSet = ruleSet[segment];
+        if (!ruleSet) {
+            return undefined;
+        }
+    }
+    return ruleSet;
+}
+/**
+ * Extracts the root context ID from a contextId or parentContextId.
+ * e.g. 'abc/def/ghi' -> 'abc', 'abc' -> 'abc'
+ * @param contextId - The context ID to extract the root from
+ * @returns The root context ID
+ */
+export function getRootContextId(contextId) {
+    return contextId.split('/')[0] || contextId;
+}
+/**
+ * Checks if a protocol path represents a multi-party context.
+ * Returns true if the root path's subtree contains $role descendants
+ * or relational who/of $actions rules that grant read access.
+ *
+ * @param protocolDefinition - The full protocol definition
+ * @param rootProtocolPath - The root protocol path to check
+ * @returns true if the protocol path represents a multi-party context
+ */
+export function isMultiPartyContext(protocolDefinition, rootProtocolPath) {
+    const ruleSet = getRuleSetAtPath(protocolDefinition, rootProtocolPath);
+    if (!ruleSet) {
+        return false;
+    }
+    // (a) Check for $role descendants in the subtree
+    function hasRoleRecursive(rs) {
+        for (const key in rs) {
+            if (!key.startsWith('$')) {
+                const child = rs[key];
+                if (child.$role === true) {
+                    return true;
+                }
+                if (hasRoleRecursive(child)) {
+                    return true;
+                }
+            }
+        }
+        return false;
+    }
+    if (hasRoleRecursive(ruleSet)) {
+        return true;
+    }
+    // (b) Check for relational who/of read rules anywhere in the protocol
+    //     that reference a path within this subtree. A rule like
+    //     { who: 'recipient', of: 'email', can: ['read'] } on any record
+    //     type means the email recipient needs a context key.
+    return hasRelationalReadAccess(undefined, rootProtocolPath, protocolDefinition);
+}
+/**
+ * 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'
+ *
+ * @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
+ */
+export function hasRelationalReadAccess(actorType, ofPath, protocolDefinition) {
+    const structure = protocolDefinition.structure;
+    function walkRuleSet(rs) {
+        var _a;
+        // Check $actions on this node
+        if (rs.$actions) {
+            for (const rule of rs.$actions) {
+                if (rule.who &&
+                    rule.who !== 'anyone' &&
+                    (actorType === undefined || rule.who === actorType) &&
+                    rule.of === ofPath &&
+                    ((_a = rule.can) === null || _a === void 0 ? void 0 : _a.includes('read'))) {
+                    return true;
+                }
+            }
+        }
+        // Recurse into child record types
+        for (const key in rs) {
+            if (!key.startsWith('$')) {
+                if (walkRuleSet(rs[key])) {
+                    return true;
+                }
+            }
+        }
+        return false;
+    }
+    return walkRuleSet(structure);
+}
+/**
+ * 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
+ * @returns Set of DIDs that need context key delivery
+ */
+export function detectNewParticipants({ protocolDefinition, protocolPath, recipient, tenantDid, authorDid }) {
+    const participants = new Set();
+    // Navigate to the rule set at the given protocol path
+    const ruleSet = getRuleSetAtPath(protocolDefinition, protocolPath);
+    if (!ruleSet) {
+        return participants;
+    }
+    // Case 1: $role record -> recipient is a participant
+    if (ruleSet.$role === true && recipient) {
+        participants.add(recipient);
+    }
+    // Case 2: Record has a recipient -> check if relational read rules exist
+    if (recipient && recipient !== tenantDid) {
+        if (hasRelationalReadAccess('recipient', protocolPath, protocolDefinition)) {
+            participants.add(recipient);
+        }
+    }
+    // Case 3: External author -> check if author-based relational read rules exist.
+    // If `{ who: 'author', of: '<path>', can: ['read'] }` is defined anywhere
+    // in the protocol, the external author needs a context key to decrypt.
+    if (authorDid && authorDid !== tenantDid) {
+        if (hasRelationalReadAccess('author', protocolPath, protocolDefinition)) {
+            participants.add(authorDid);
+        }
+    }
+    // Remove the DWN owner — they always have ProtocolPath access
+    participants.delete(tenantDid);
+    return participants;
+}
+//# sourceMappingURL=protocol-utils.js.map

package/dist/esm/protocol-utils.js.map

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

package/dist/esm/store-data-protocols.js

@@ -21,7 +21,7 @@ export const IdentityProtocolDefinition = {
     }
 };
 export const KeyDeliveryProtocolDefinition = {
-    protocol: 'https://enbox.org/protocols/key-delivery',
+    protocol: 'https://identity.foundation/protocols/key-delivery',
     published: false,
     types: {
         contextKey: {

package/dist/esm/store-data-protocols.js.map

@@ -1 +1 @@
-{"version":3,"file":"store-data-protocols.js","sourceRoot":"","sources":["../../src/store-data-protocols.ts"],"names":[],"mappings":"AAEA,MAAM,CAAC,MAAM,0BAA0B,GAAuB;IAC5D,QAAQ,EAAI,0DAA0D;IACtE,SAAS,EAAG,KAAK;IACjB,KAAK,EAAO;QACV,WAAW,EAAE;YACX,MAAM,EAAQ,uDAAuD;YACrE,WAAW,EAAG;gBACZ,kBAAkB;aACnB;SACF;QACD,gBAAgB,EAAE;YAChB,MAAM,EAAQ,4DAA4D;YAC1E,WAAW,EAAG;gBACZ,kBAAkB;aACnB;SACF;KACF;IACD,SAAS,EAAE;QACT,WAAW,EAAQ,EAAE;QACrB,gBAAgB,EAAG,EAAE;KACtB;CACF,CAAC;AAEF,MAAM,CAAC,MAAM,6BAA6B,GAAuB;IAC/D,QAAQ,EAAI,0CAA0C;IACtD,SAAS,EAAG,KAAK;IACjB,KAAK,EAAO;QACV,UAAU,EAAE;YACV,WAAW,EAAE,CAAC,kBAAkB,CAAC;SAClC;KACF;IACD,SAAS,EAAE;QACT,UAAU,EAAE;YACV,QAAQ,EAAE;gBACR,EAAE,GAAG,EAAE,WAAW,EAAE,EAAE,EAAE,YAAY,EAAE,GAAG,EAAE,CAAC,MAAM,CAAC,EAAE;aACtD;YACD,KAAK,EAAE;gBACL,aAAa,EAAS,CAAC,UAAU,EAAE,WAAW,CAAC;gBAC/C,mBAAmB,EAAG,KAAK;gBAC3B,QAAQ,EAAc,EAAE,IAAI,EAAE,QAAQ,EAAE;gBACxC,SAAS,EAAa,EAAE,IAAI,EAAE,QAAQ,EAAE;aACzC;SACF;KACF;CACF,CAAC;AAEF,MAAM,CAAC,MAAM,qBAAqB,GAAuB;IACvD,QAAQ,EAAI,qDAAqD;IACjE,SAAS,EAAG,KAAK;IACjB,KAAK,EAAO;QACV,UAAU,EAAE;YACV,MAAM,EAAe,sDAAsD;YAC3E,WAAW,EAAU,CAAC,kBAAkB,CAAC;YACzC,kBAAkB,EAAG,IAAI;SAC1B;KACF;IACD,SAAS,EAAE;QACT,UAAU,EAAE,EAAE;KACf;CACF,CAAC"}
+{"version":3,"file":"store-data-protocols.js","sourceRoot":"","sources":["../../src/store-data-protocols.ts"],"names":[],"mappings":"AAEA,MAAM,CAAC,MAAM,0BAA0B,GAAuB;IAC5D,QAAQ,EAAI,0DAA0D;IACtE,SAAS,EAAG,KAAK;IACjB,KAAK,EAAO;QACV,WAAW,EAAE;YACX,MAAM,EAAQ,uDAAuD;YACrE,WAAW,EAAG;gBACZ,kBAAkB;aACnB;SACF;QACD,gBAAgB,EAAE;YAChB,MAAM,EAAQ,4DAA4D;YAC1E,WAAW,EAAG;gBACZ,kBAAkB;aACnB;SACF;KACF;IACD,SAAS,EAAE;QACT,WAAW,EAAQ,EAAE;QACrB,gBAAgB,EAAG,EAAE;KACtB;CACF,CAAC;AAEF,MAAM,CAAC,MAAM,6BAA6B,GAAuB;IAC/D,QAAQ,EAAI,oDAAoD;IAChE,SAAS,EAAG,KAAK;IACjB,KAAK,EAAO;QACV,UAAU,EAAE;YACV,WAAW,EAAE,CAAC,kBAAkB,CAAC;SAClC;KACF;IACD,SAAS,EAAE;QACT,UAAU,EAAE;YACV,QAAQ,EAAE;gBACR,EAAE,GAAG,EAAE,WAAW,EAAE,EAAE,EAAE,YAAY,EAAE,GAAG,EAAE,CAAC,MAAM,CAAC,EAAE;aACtD;YACD,KAAK,EAAE;gBACL,aAAa,EAAS,CAAC,UAAU,EAAE,WAAW,CAAC;gBAC/C,mBAAmB,EAAG,KAAK;gBAC3B,QAAQ,EAAc,EAAE,IAAI,EAAE,QAAQ,EAAE;gBACxC,SAAS,EAAa,EAAE,IAAI,EAAE,QAAQ,EAAE;aACzC;SACF;KACF;CACF,CAAC;AAEF,MAAM,CAAC,MAAM,qBAAqB,GAAuB;IACvD,QAAQ,EAAI,qDAAqD;IACjE,SAAS,EAAG,KAAK;IACjB,KAAK,EAAO;QACV,UAAU,EAAE;YACV,MAAM,EAAe,sDAAsD;YAC3E,WAAW,EAAU,CAAC,kBAAkB,CAAC;YACzC,kBAAkB,EAAG,IAAI;SAC1B;KACF;IACD,SAAS,EAAE;QACT,UAAU,EAAE,EAAE;KACf;CACF,CAAC"}