@enbox/dwn-sdk-js 0.0.6 → 0.0.8

package/dist/esm/src/protocols/permissions.js

@@ -1,16 +1,11 @@
-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 { DwnConstant } from '../core/dwn-constant.js';
 import { Encoder } from '../utils/encoder.js';
+import { FilterUtility } from '../utils/filter.js';
+import { Message } from '../core/message.js';
 import { PermissionGrant } from './permission-grant.js';
 import { PermissionRequest } from './permission-request.js';
-import { RecordsWrite } from '../../src/interfaces/records-write.js';
+import { Records } from '../utils/records.js';
+import { RecordsWrite } from '../interfaces/records-write.js';
 import { Time } from '../utils/time.js';
 import { validateJsonSchema } from '../schema-validator.js';
 import { DwnError, DwnErrorCode } from '../core/dwn-error.js';
@@ -18,135 +13,312 @@ import { DwnInterfaceName, DwnMethodName } from '../enums/dwn-interface-method.j
 import { normalizeProtocolUrl, validateProtocolUrlNormalized } from '../utils/url.js';
 /**
  * This is a first-class DWN protocol for managing permission grants of a given DWN.
+ *
+ * It implements the `CoreProtocol` interface so that its lifecycle hooks
+ * (validation, pre-processing, post-processing) are dispatched generically
+ * by the `CoreProtocolRegistry` rather than being hardcoded in handlers.
  */
 export class PermissionsProtocol {
+    /**
+     * The URI of the DWN Permissions protocol.
+     */
+    static uri = 'https://identity.foundation/dwn/permissions';
+    /**
+     * The protocol path of the `request` record.
+     */
+    static requestPath = 'request';
+    /**
+     * The protocol path of the `grant` record.
+     */
+    static grantPath = 'grant';
+    /**
+     * The protocol path of the `revocation` record.
+     */
+    static revocationPath = 'grant/revocation';
+    /**
+     * The definition of the Permissions protocol.
+     */
+    static definition = {
+        published: true,
+        protocol: PermissionsProtocol.uri,
+        types: {
+            request: {
+                dataFormats: ['application/json']
+            },
+            grant: {
+                dataFormats: ['application/json']
+            },
+            revocation: {
+                dataFormats: ['application/json']
+            }
+        },
+        structure: {
+            request: {
+                $size: {
+                    max: 10000
+                },
+                $actions: [
+                    {
+                        who: 'anyone',
+                        can: ['create']
+                    }
+                ]
+            },
+            grant: {
+                $size: {
+                    max: 10000
+                },
+                $actions: [
+                    {
+                        who: 'recipient',
+                        of: 'grant',
+                        can: ['read']
+                    }
+                ],
+                revocation: {
+                    $size: {
+                        max: 10000
+                    },
+                    $actions: [
+                        {
+                            who: 'anyone',
+                            can: ['read']
+                        }
+                    ]
+                }
+            }
+        }
+    };
+    // ---------- CoreProtocol instance accessors ----------
+    /** @inheritdoc */
+    get uri() {
+        return PermissionsProtocol.uri;
+    }
+    /** @inheritdoc */
+    get definition() {
+        return PermissionsProtocol.definition;
+    }
+    // ---------- CoreProtocol lifecycle hooks ----------
+    /** @inheritdoc */
+    validateRecord(message, dataBytes) {
+        PermissionsProtocol.validateSchema(message, dataBytes);
+    }
+    /**
+     * Pre-processing hook for permission revocation records.
+     * Validates that the revocation's `tags.protocol` matches the grant's scoped protocol.
+     */
+    async preProcessWrite(tenant, message, messageStore) {
+        if (message.descriptor.protocolPath !== PermissionsProtocol.revocationPath) {
+            return;
+        }
+        // fetch the parent grant to compare the scoped protocol against the revocation tag
+        const permissionGrantId = message.descriptor.parentId;
+        const grant = await PermissionsProtocol.fetchGrant(tenant, messageStore, permissionGrantId);
+        const revokeTagProtocol = message.descriptor.tags?.protocol;
+        const grantProtocol = 'protocol' in grant.scope ? grant.scope.protocol : undefined;
+        if (grantProtocol !== revokeTagProtocol) {
+            throw new DwnError(DwnErrorCode.PermissionsProtocolValidateRevocationProtocolTagMismatch, `Revocation protocol ${revokeTagProtocol} does not match grant protocol ${grantProtocol}`);
+        }
+    }
+    /**
+     * Post-processing hook for permission revocation records.
+     * When a grant is revoked, all messages authorized by that grant and created
+     * after the revocation timestamp are deleted from all stores.
+     *
+     * Deletion order is deliberate to avoid orphaned data in case of crash:
+     *   1. data store  (large blobs first)
+     *   2. state index (SMT entries)
+     *   3. message store
+     */
+    async postProcessWrite(tenant, recordsWrite, stores) {
+        if (recordsWrite.message.descriptor.protocolPath !== PermissionsProtocol.revocationPath) {
+            return;
+        }
+        const permissionGrantId = recordsWrite.message.descriptor.parentId;
+        const grantAuthorizedMessagesQuery = {
+            permissionGrantId,
+            dateCreated: { gte: recordsWrite.message.descriptor.messageTimestamp },
+        };
+        const { messages: grantAuthorizedMessages } = await stores.messageStore.query(tenant, [grantAuthorizedMessagesQuery]);
+        if (grantAuthorizedMessages.length === 0) {
+            return;
+        }
+        // 1. Delete data from the data store first to avoid orphaned data blobs in case of crash.
+        //    Only RecordsWrite messages with data larger than maxDataSizeAllowedToBeEncoded have data in the data store.
+        for (const message of grantAuthorizedMessages) {
+            if (message.descriptor.method === DwnMethodName.Write) {
+                const recordsWriteMessage = message;
+                if (recordsWriteMessage.descriptor.dataSize > DwnConstant.maxDataSizeAllowedToBeEncoded) {
+                    await stores.dataStore.delete(tenant, recordsWriteMessage.recordId, recordsWriteMessage.descriptor.dataCid);
+                }
+            }
+        }
+        // 2. Compute CIDs and delete from state index before message store to avoid orphaned state entries.
+        const messageCids = await Promise.all(grantAuthorizedMessages.map((message) => Message.getCid(message)));
+        await stores.stateIndex.delete(tenant, messageCids);
+        // 3. Finally delete all messages from the message store.
+        await Promise.all(messageCids.map((cid) => stores.messageStore.delete(tenant, cid)));
+    }
+    /** @inheritdoc */
+    mapErrorToStatusCode(errorCode) {
+        if (errorCode.startsWith('PermissionsProtocolValidate')) {
+            return 400;
+        }
+        return undefined;
+    }
+    /**
+     * Constructs an additional filter for protocol-scoped message queries so that
+     * permission records (grants, requests, revocations) tagged with the target
+     * protocol appear alongside that protocol's own records in sync/subscribe/read results.
+     */
+    constructAdditionalMessageFilter(filter) {
+        const { protocol, messageTimestamp } = filter;
+        if (protocol === undefined) {
+            return undefined;
+        }
+        const taggedFilter = {
+            protocol: PermissionsProtocol.uri,
+            ...Records.convertTagsFilter({ protocol }),
+        };
+        if (messageTimestamp !== undefined) {
+            const messageTimestampFilter = FilterUtility.convertRangeCriterion(messageTimestamp);
+            if (messageTimestampFilter) {
+                taggedFilter.messageTimestamp = messageTimestampFilter;
+            }
+        }
+        return taggedFilter;
+    }
+    // ---------- Static utility methods ----------
     static parseRequest(base64UrlEncodedRequest) {
         return Encoder.base64UrlToObject(base64UrlEncodedRequest);
     }
     /**
      * Convenience method to create a permission request.
      */
-    static createRequest(options) {
-        return __awaiter(this, void 0, void 0, function* () {
-            if (this.isRecordPermissionScope(options.scope) && options.scope.protocol === undefined) {
-                throw new DwnError(DwnErrorCode.PermissionsProtocolCreateRequestRecordsScopeMissingProtocol, 'Permission request for Records must have a scope with a `protocol` property');
-            }
-            const scope = PermissionsProtocol.normalizePermissionScope(options.scope);
-            const permissionRequestData = {
-                description: options.description,
-                delegated: options.delegated,
-                scope,
-                conditions: options.conditions,
-            };
-            // If the request is scoped to a protocol, the protocol tag must be included with the record.
-            // This is done in order to ensure a subset message query filtered to a protocol includes the permission requests associated with it.
-            let permissionTags = undefined;
-            if (this.hasProtocolScope(scope)) {
-                permissionTags = {
-                    protocol: scope.protocol
-                };
-            }
-            const permissionRequestBytes = Encoder.objectToBytes(permissionRequestData);
-            const recordsWrite = yield RecordsWrite.create({
-                signer: options.signer,
-                messageTimestamp: options.dateRequested,
-                protocol: PermissionsProtocol.uri,
-                protocolPath: PermissionsProtocol.requestPath,
-                dataFormat: 'application/json',
-                data: permissionRequestBytes,
-                tags: permissionTags,
-            });
-            const dataEncodedMessage = Object.assign(Object.assign({}, recordsWrite.message), { encodedData: Encoder.bytesToBase64Url(permissionRequestBytes) });
-            return {
-                recordsWrite,
-                permissionRequestData,
-                permissionRequestBytes,
-                dataEncodedMessage
+    static async createRequest(options) {
+        if (this.isRecordPermissionScope(options.scope) && options.scope.protocol === undefined) {
+            throw new DwnError(DwnErrorCode.PermissionsProtocolCreateRequestRecordsScopeMissingProtocol, 'Permission request for Records must have a scope with a `protocol` property');
+        }
+        const scope = PermissionsProtocol.normalizePermissionScope(options.scope);
+        const permissionRequestData = {
+            description: options.description,
+            delegated: options.delegated,
+            scope,
+            conditions: options.conditions,
+        };
+        // If the request is scoped to a protocol, the protocol tag must be included with the record.
+        // This is done in order to ensure a subset message query filtered to a protocol includes the permission requests associated with it.
+        let permissionTags = undefined;
+        if (this.hasProtocolScope(scope)) {
+            permissionTags = {
+                protocol: scope.protocol
             };
+        }
+        const permissionRequestBytes = Encoder.objectToBytes(permissionRequestData);
+        const recordsWrite = await RecordsWrite.create({
+            signer: options.signer,
+            messageTimestamp: options.dateRequested,
+            protocol: PermissionsProtocol.uri,
+            protocolPath: PermissionsProtocol.requestPath,
+            dataFormat: 'application/json',
+            data: permissionRequestBytes,
+            tags: permissionTags,
         });
+        const dataEncodedMessage = {
+            ...recordsWrite.message,
+            encodedData: Encoder.bytesToBase64Url(permissionRequestBytes)
+        };
+        return {
+            recordsWrite,
+            permissionRequestData,
+            permissionRequestBytes,
+            dataEncodedMessage
+        };
     }
     /**
      * Convenience method to create a permission grant.
      */
-    static createGrant(options) {
-        return __awaiter(this, void 0, void 0, function* () {
-            if (this.isRecordPermissionScope(options.scope) && options.scope.protocol === undefined) {
-                throw new DwnError(DwnErrorCode.PermissionsProtocolCreateGrantRecordsScopeMissingProtocol, 'Permission grants for Records must have a scope with a `protocol` property');
-            }
-            const scope = PermissionsProtocol.normalizePermissionScope(options.scope);
-            const permissionGrantData = {
-                dateExpires: options.dateExpires,
-                requestId: options.requestId,
-                description: options.description,
-                delegated: options.delegated,
-                scope,
-                conditions: options.conditions,
-            };
-            // If the grant is scoped to a protocol, the protocol tag must be included with the record.
-            // This is done in order to ensure a subset message query filtered to a protocol includes the permission grants associated with it.
-            let permissionTags = undefined;
-            if (this.hasProtocolScope(scope)) {
-                permissionTags = {
-                    protocol: scope.protocol
-                };
-            }
-            const permissionGrantBytes = Encoder.objectToBytes(permissionGrantData);
-            const recordsWrite = yield RecordsWrite.create({
-                signer: options.signer,
-                messageTimestamp: options.dateGranted,
-                dateCreated: options.dateGranted,
-                recipient: options.grantedTo,
-                protocol: PermissionsProtocol.uri,
-                protocolPath: PermissionsProtocol.grantPath,
-                dataFormat: 'application/json',
-                data: permissionGrantBytes,
-                tags: permissionTags,
-            });
-            const dataEncodedMessage = Object.assign(Object.assign({}, recordsWrite.message), { encodedData: Encoder.bytesToBase64Url(permissionGrantBytes) });
-            return {
-                recordsWrite,
-                permissionGrantData,
-                permissionGrantBytes,
-                dataEncodedMessage
+    static async createGrant(options) {
+        if (this.isRecordPermissionScope(options.scope) && options.scope.protocol === undefined) {
+            throw new DwnError(DwnErrorCode.PermissionsProtocolCreateGrantRecordsScopeMissingProtocol, 'Permission grants for Records must have a scope with a `protocol` property');
+        }
+        const scope = PermissionsProtocol.normalizePermissionScope(options.scope);
+        const permissionGrantData = {
+            dateExpires: options.dateExpires,
+            requestId: options.requestId,
+            description: options.description,
+            delegated: options.delegated,
+            scope,
+            conditions: options.conditions,
+        };
+        // If the grant is scoped to a protocol, the protocol tag must be included with the record.
+        // This is done in order to ensure a subset message query filtered to a protocol includes the permission grants associated with it.
+        let permissionTags = undefined;
+        if (this.hasProtocolScope(scope)) {
+            permissionTags = {
+                protocol: scope.protocol
             };
+        }
+        const permissionGrantBytes = Encoder.objectToBytes(permissionGrantData);
+        const recordsWrite = await RecordsWrite.create({
+            signer: options.signer,
+            messageTimestamp: options.dateGranted,
+            dateCreated: options.dateGranted,
+            recipient: options.grantedTo,
+            protocol: PermissionsProtocol.uri,
+            protocolPath: PermissionsProtocol.grantPath,
+            dataFormat: 'application/json',
+            data: permissionGrantBytes,
+            tags: permissionTags,
         });
+        const dataEncodedMessage = {
+            ...recordsWrite.message,
+            encodedData: Encoder.bytesToBase64Url(permissionGrantBytes)
+        };
+        return {
+            recordsWrite,
+            permissionGrantData,
+            permissionGrantBytes,
+            dataEncodedMessage
+        };
     }
     /**
      * Convenience method to create a permission revocation.
      */
-    static createRevocation(options) {
-        return __awaiter(this, void 0, void 0, function* () {
-            const permissionRevocationData = {
-                description: options.description,
-            };
-            const grantId = options.grant.id;
-            // if the grant was scoped to a protocol, the protocol tag must be included in the revocation
-            // This is done in order to ensure a subset message query filtered to a protocol includes the permission revocations associated with it.
-            //
-            // NOTE: the added tag is validated against the original grant when the revocation is processed by the DWN.
-            let permissionTags = undefined;
-            if (this.hasProtocolScope(options.grant.scope)) {
-                const protocol = normalizeProtocolUrl(options.grant.scope.protocol);
-                permissionTags = { protocol };
-            }
-            const permissionRevocationBytes = Encoder.objectToBytes(permissionRevocationData);
-            const recordsWrite = yield RecordsWrite.create({
-                signer: options.signer,
-                parentContextId: grantId, // NOTE: since the grant is the root record, its record ID is also the context ID
-                protocol: PermissionsProtocol.uri,
-                protocolPath: PermissionsProtocol.revocationPath,
-                dataFormat: 'application/json',
-                data: permissionRevocationBytes,
-                tags: permissionTags,
-            });
-            const dataEncodedMessage = Object.assign(Object.assign({}, recordsWrite.message), { encodedData: Encoder.bytesToBase64Url(permissionRevocationBytes) });
-            return {
-                recordsWrite,
-                permissionRevocationData,
-                permissionRevocationBytes,
-                dataEncodedMessage
-            };
+    static async createRevocation(options) {
+        const permissionRevocationData = {
+            description: options.description,
+        };
+        const grantId = options.grant.id;
+        // if the grant was scoped to a protocol, the protocol tag must be included in the revocation
+        // This is done in order to ensure a subset message query filtered to a protocol includes the permission revocations associated with it.
+        //
+        // NOTE: the added tag is validated against the original grant when the revocation is processed by the DWN.
+        let permissionTags = undefined;
+        if (this.hasProtocolScope(options.grant.scope)) {
+            const protocol = normalizeProtocolUrl(options.grant.scope.protocol);
+            permissionTags = { protocol };
+        }
+        const permissionRevocationBytes = Encoder.objectToBytes(permissionRevocationData);
+        const recordsWrite = await RecordsWrite.create({
+            signer: options.signer,
+            parentContextId: grantId, // NOTE: since the grant is the root record, its record ID is also the context ID
+            protocol: PermissionsProtocol.uri,
+            protocolPath: PermissionsProtocol.revocationPath,
+            dataFormat: 'application/json',
+            data: permissionRevocationBytes,
+            tags: permissionTags,
         });
+        const dataEncodedMessage = {
+            ...recordsWrite.message,
+            encodedData: Encoder.bytesToBase64Url(permissionRevocationBytes)
+        };
+        return {
+            recordsWrite,
+            permissionRevocationData,
+            permissionRevocationBytes,
+            dataEncodedMessage
+        };
     }
     /**
      * Validates the given Permissions protocol RecordsWrite. It can be a request, grant, or revocation.
@@ -180,25 +352,23 @@ export class PermissionsProtocol {
      * @returns the PermissionGrant matching the `recordId` specified.
      * @throws {Error} if PermissionGrant does not exist
      */
-    static fetchGrant(tenant, messageStore, permissionGrantId) {
-        return __awaiter(this, void 0, void 0, function* () {
-            const grantQuery = {
-                recordId: permissionGrantId,
-                isLatestBaseState: true
-            };
-            const { messages } = yield messageStore.query(tenant, [grantQuery]);
-            const possibleGrantMessage = messages[0];
-            const dwnInterface = possibleGrantMessage === null || possibleGrantMessage === void 0 ? void 0 : possibleGrantMessage.descriptor.interface;
-            const dwnMethod = possibleGrantMessage === null || possibleGrantMessage === void 0 ? void 0 : possibleGrantMessage.descriptor.method;
-            if (dwnInterface !== DwnInterfaceName.Records ||
-                dwnMethod !== DwnMethodName.Write ||
-                possibleGrantMessage.descriptor.protocolPath !== PermissionsProtocol.grantPath) {
-                throw new DwnError(DwnErrorCode.GrantAuthorizationGrantMissing, `Could not find permission grant with record ID ${permissionGrantId}.`);
-            }
-            const permissionGrantMessage = possibleGrantMessage;
-            const permissionGrant = yield PermissionGrant.parse(permissionGrantMessage);
-            return permissionGrant;
-        });
+    static async fetchGrant(tenant, messageStore, permissionGrantId) {
+        const grantQuery = {
+            recordId: permissionGrantId,
+            isLatestBaseState: true
+        };
+        const { messages } = await messageStore.query(tenant, [grantQuery]);
+        const possibleGrantMessage = messages[0];
+        const dwnInterface = possibleGrantMessage?.descriptor.interface;
+        const dwnMethod = possibleGrantMessage?.descriptor.method;
+        if (dwnInterface !== DwnInterfaceName.Records ||
+            dwnMethod !== DwnMethodName.Write ||
+            possibleGrantMessage.descriptor.protocolPath !== PermissionsProtocol.grantPath) {
+            throw new DwnError(DwnErrorCode.GrantAuthorizationGrantMissing, `Could not find permission grant with record ID ${permissionGrantId}.`);
+        }
+        const permissionGrantMessage = possibleGrantMessage;
+        const permissionGrant = PermissionGrant.parse(permissionGrantMessage);
+        return permissionGrant;
     }
     /**
      * Gets the scope from the given permission record.
@@ -206,32 +376,30 @@ export class PermissionsProtocol {
      *
      * @param messageStore The message store to fetch the grant for a revocation.
      */
-    static getScopeFromPermissionRecord(tenant, messageStore, incomingMessage) {
-        return __awaiter(this, void 0, void 0, function* () {
-            if (incomingMessage.descriptor.protocol !== PermissionsProtocol.uri) {
-                throw new DwnError(DwnErrorCode.PermissionsProtocolGetScopeInvalidProtocol, `Unexpected protocol for permission record: ${incomingMessage.descriptor.protocol}`);
-            }
-            if (incomingMessage.descriptor.protocolPath === PermissionsProtocol.revocationPath) {
-                const grant = yield PermissionsProtocol.fetchGrant(tenant, messageStore, incomingMessage.descriptor.parentId);
-                return grant.scope;
-            }
-            else if (incomingMessage.descriptor.protocolPath === PermissionsProtocol.grantPath) {
-                const grant = yield PermissionGrant.parse(incomingMessage);
-                return grant.scope;
-            }
-            else {
-                // if the record is not a grant or revocation, it must be a request
-                const request = yield PermissionRequest.parse(incomingMessage);
-                return request.scope;
-            }
-        });
+    static async getScopeFromPermissionRecord(tenant, messageStore, incomingMessage) {
+        if (incomingMessage.descriptor.protocol !== PermissionsProtocol.uri) {
+            throw new DwnError(DwnErrorCode.PermissionsProtocolGetScopeInvalidProtocol, `Unexpected protocol for permission record: ${incomingMessage.descriptor.protocol}`);
+        }
+        if (incomingMessage.descriptor.protocolPath === PermissionsProtocol.revocationPath) {
+            const grant = await PermissionsProtocol.fetchGrant(tenant, messageStore, incomingMessage.descriptor.parentId);
+            return grant.scope;
+        }
+        else if (incomingMessage.descriptor.protocolPath === PermissionsProtocol.grantPath) {
+            const grant = PermissionGrant.parse(incomingMessage);
+            return grant.scope;
+        }
+        else {
+            // if the record is not a grant or revocation, it must be a request
+            const request = PermissionRequest.parse(incomingMessage);
+            return request.scope;
+        }
     }
     /**
      * Normalizes the given permission scope if needed.
      * @returns The normalized permission scope.
      */
     static normalizePermissionScope(permissionScope) {
-        const scope = Object.assign({}, permissionScope);
+        const scope = { ...permissionScope };
         if (PermissionsProtocol.hasProtocolScope(scope)) {
             scope.protocol = normalizeProtocolUrl(scope.protocol);
         }
@@ -283,75 +451,5 @@ export class PermissionsProtocol {
         }
     }
 }
-/**
- * The URI of the DWN Permissions protocol.
- */
-PermissionsProtocol.uri = 'https://tbd.website/dwn/permissions';
-/**
- * The protocol path of the `request` record.
- */
-PermissionsProtocol.requestPath = 'request';
-/**
- * The protocol path of the `grant` record.
- */
-PermissionsProtocol.grantPath = 'grant';
-/**
- * The protocol path of the `revocation` record.
- */
-PermissionsProtocol.revocationPath = 'grant/revocation';
-/**
- * The definition of the Permissions protocol.
- */
-PermissionsProtocol.definition = {
-    published: true,
-    protocol: PermissionsProtocol.uri,
-    types: {
-        request: {
-            dataFormats: ['application/json']
-        },
-        grant: {
-            dataFormats: ['application/json']
-        },
-        revocation: {
-            dataFormats: ['application/json']
-        }
-    },
-    structure: {
-        request: {
-            $size: {
-                max: 10000
-            },
-            $actions: [
-                {
-                    who: 'anyone',
-                    can: ['create']
-                }
-            ]
-        },
-        grant: {
-            $size: {
-                max: 10000
-            },
-            $actions: [
-                {
-                    who: 'recipient',
-                    of: 'grant',
-                    can: ['read']
-                }
-            ],
-            revocation: {
-                $size: {
-                    max: 10000
-                },
-                $actions: [
-                    {
-                        who: 'anyone',
-                        can: ['read']
-                    }
-                ]
-            }
-        }
-    }
-};
 ;
 //# sourceMappingURL=permissions.js.map