@enbox/dwn-sdk-js 0.4.0 → 0.4.2

package/src/core/protocol-authorization-validation.ts

@@ -1,21 +1,15 @@
-import type { Filter } from '../types/query-types.js';
-import type { MessageStore } from '../types/message-store.js';
+import type { RecordsWrite } from '../interfaces/records-write.js';
 import type { RecordsWriteMessage } from '../types/records-types.js';
+import type { ValidationStateReader } from '../types/validation-state-reader.js';
 import type { ProtocolDefinition, ProtocolRuleSet, ProtocolType, ProtocolTypes } from '../types/protocols-types.js';
 
 import { ProtocolRecordLimitStrategy } from '../types/protocols-types.js';
 
-import type { RecordsWrite } from '../interfaces/records-write.js';
-
-import Ajv from 'ajv/dist/2020.js';
-import { FilterUtility } from '../utils/filter.js';
 import { Records } from '../utils/records.js';
+import { validateProtocolTags } from '../utils/protocol-tags.js';
 import { DwnError, DwnErrorCode } from './dwn-error.js';
-import { DwnInterfaceName, DwnMethodName } from '../enums/dwn-interface-method.js';
 import { getTypeName, parseCrossProtocolRef } from '../utils/protocols.js';
 
-import type { FetchProtocolDefinitionFn } from './protocol-authorization.js';
-
 /**
  * Verifies the `protocolPath` declared in the given message matches the path of actual record chain.
  * For cross-protocol composition, the parent record may belong to a different protocol (resolved via `$ref` in the composing protocol).
@@ -24,9 +18,8 @@ import type { FetchProtocolDefinitionFn } from './protocol-authorization.js';
 export async function verifyProtocolPathAndContextId(
   tenant: string,
   inboundMessage: RecordsWrite,
-  messageStore: MessageStore,
-  fetchProtocolDefinition: FetchProtocolDefinitionFn,
-  governingTimestamp?: string,
+  validationStateReader: ValidationStateReader,
+  protocolDefinitionTimestamp?: string,
 ): Promise<void> {
   const declaredProtocolPath = inboundMessage.message.descriptor.protocolPath;
   const declaredTypeName = getTypeName(declaredProtocolPath);
@@ -49,19 +42,15 @@ export async function verifyProtocolPathAndContextId(
   // If the parent path segment has a `$ref` in the composing protocol, the parent lives in a different protocol.
   const childProtocol = inboundMessage.message.descriptor.protocol;
   const parentProtocolUri = await resolveParentProtocolUri(
-    tenant, childProtocol, declaredProtocolPath, messageStore, fetchProtocolDefinition, governingTimestamp
+    tenant, childProtocol, declaredProtocolPath, validationStateReader, protocolDefinitionTimestamp
   );
 
   // fetch the parent message
-  const query: Filter = {
-    isLatestBaseState : true, // NOTE: this filter is critical, to ensure are are not returning a deleted parent
-    interface         : DwnInterfaceName.Records,
-    method            : DwnMethodName.Write,
-    protocol          : parentProtocolUri,
-    recordId          : parentId
-  };
-  const { messages: parentMessages } = await messageStore.query(tenant, [query]);
-  const parentMessage = (parentMessages as RecordsWriteMessage[])[0];
+  const parentMessage = await validationStateReader.fetchParentRecord({
+    tenant,
+    parentProtocolUri,
+    parentId,
+  });
 
   if (parentMessage === undefined) {
     // if this is a cross-protocol composition lookup, use a more descriptive error
@@ -117,9 +106,8 @@ export async function resolveParentProtocolUri(
   tenant: string,
   childProtocolUri: string,
   childProtocolPath: string,
-  messageStore: MessageStore,
-  fetchProtocolDefinition: FetchProtocolDefinitionFn,
-  governingTimestamp?: string,
+  validationStateReader: ValidationStateReader,
+  protocolDefinitionTimestamp?: string,
 ): Promise<string> {
   const segments = childProtocolPath.split('/');
 
@@ -128,9 +116,9 @@ export async function resolveParentProtocolUri(
     return childProtocolUri;
   }
 
-  // Fetch the composing protocol's definition at the governing timestamp
-  const composingDefinition = await fetchProtocolDefinition(
-    tenant, childProtocolUri, messageStore, governingTimestamp
+  // Fetch the composing protocol's definition at the incoming message timestamp
+  const composingDefinition = await validationStateReader.fetchProtocolDefinition(
+    tenant, childProtocolUri, protocolDefinitionTimestamp
   );
 
   // Walk the structure to find the parent's path segment
@@ -170,9 +158,8 @@ export async function verifyTypeWithComposition(
   tenant: string,
   inboundMessage: RecordsWriteMessage,
   protocolDefinition: ProtocolDefinition,
-  messageStore: MessageStore,
-  fetchProtocolDefinition: FetchProtocolDefinitionFn,
-  governingTimestamp?: string,
+  validationStateReader: ValidationStateReader,
+  protocolDefinitionTimestamp?: string,
 ): Promise<void> {
   const declaredProtocolPath = inboundMessage.descriptor.protocolPath;
   const declaredTypeName = getTypeName(declaredProtocolPath);
@@ -180,7 +167,7 @@ export async function verifyTypeWithComposition(
   // Resolve which protocol types map to use.
   // If the first path segment has `$ref`, this record's type might be defined in a referenced protocol.
   const protocolTypes = await resolveProtocolTypesForPath(
-    tenant, declaredProtocolPath, protocolDefinition, messageStore, fetchProtocolDefinition, governingTimestamp
+    tenant, declaredProtocolPath, protocolDefinition, validationStateReader, protocolDefinitionTimestamp
   );
 
   verifyType(inboundMessage, protocolTypes, declaredTypeName);
@@ -195,9 +182,8 @@ export async function resolveProtocolTypesForPath(
   tenant: string,
   protocolPath: string,
   protocolDefinition: ProtocolDefinition,
-  messageStore: MessageStore,
-  fetchProtocolDefinition: FetchProtocolDefinitionFn,
-  governingTimestamp?: string,
+  validationStateReader: ValidationStateReader,
+  protocolDefinitionTimestamp?: string,
 ): Promise<ProtocolTypes> {
   const segments = protocolPath.split('/');
 
@@ -209,8 +195,8 @@ export async function resolveProtocolTypesForPath(
     if (parsed !== undefined && protocolDefinition.uses !== undefined) {
       const refProtocolUri = protocolDefinition.uses[parsed.alias];
       if (refProtocolUri !== undefined) {
-        const refDefinition = await fetchProtocolDefinition(
-          tenant, refProtocolUri, messageStore, governingTimestamp
+        const refDefinition = await validationStateReader.fetchProtocolDefinition(
+          tenant, refProtocolUri, protocolDefinitionTimestamp
         );
         return refDefinition.types;
       }
@@ -296,7 +282,7 @@ export function verifySizeLimit(
 }
 
 /**
- * Verifies record tags against the `$tags` schema in the rule set using JSON Schema (Ajv).
+ * Verifies record tags against the `$tags` schema in the rule set.
  * Checks required tags, additional properties, and schema conformance.
  */
 export function verifyTagsIfNeeded(
@@ -305,30 +291,13 @@ export function verifyTagsIfNeeded(
 ): void {
   if (ruleSet.$tags !== undefined) {
     const { tags = {}, protocol, protocolPath } = incomingMessage.message.descriptor;
+    const schemaError = validateProtocolTags(
+      ruleSet.$tags,
+      tags,
+      `${protocol}/${protocolPath}/$tags`,
+    );
 
-    const { $allowUndefinedTags, $requiredTags, ...properties } = ruleSet.$tags;
-
-    // if $allowUndefinedTags is set to false and there are properties not defined in the schema, an error is thrown
-    const additionalProperties = $allowUndefinedTags || false;
-
-    // if $requiredTags is set, all required tags must be present
-    const required = $requiredTags || [];
-
-    const ajv = new Ajv.default();
-    const compiledTags = ajv.compile({
-      type: 'object',
-      properties,
-      required,
-      additionalProperties,
-    });
-
-    const validSchema = compiledTags(tags);
-    if (!validSchema) {
-      // the `dataVar` is used to add a qualifier to the error message.
-      // For example. If the error is related to a tag `status` in a protocol `https://example.protocol` with the protocolPath `example/path`
-      // the error would be described as `https://example.protocol/example/path/$tags/status'
-      // without this decorator it would show up as `data/status` which may be confusing.
-      const schemaError = ajv.errorsText(compiledTags.errors, { dataVar: `${protocol}/${protocolPath}/$tags` });
+    if (schemaError !== undefined) {
       throw new DwnError(DwnErrorCode.ProtocolAuthorizationTagsInvalidSchema, `tags schema validation error: ${schemaError}`);
     }
   }
@@ -344,7 +313,7 @@ export async function verifyAsRoleRecordIfNeeded(
   tenant: string,
   incomingMessage: RecordsWrite,
   ruleSet: ProtocolRuleSet,
-  messageStore: MessageStore,
+  validationStateReader: ValidationStateReader,
 ): Promise<void> {
   if (!ruleSet.$role) {
     return;
@@ -362,25 +331,17 @@ export async function verifyAsRoleRecordIfNeeded(
   }
 
   const protocolPath = incomingRecordsWrite.message.descriptor.protocolPath;
-  const filter: Filter = {
-    interface         : DwnInterfaceName.Records,
-    method            : DwnMethodName.Write,
-    isLatestBaseState : true,
-    protocol          : incomingRecordsWrite.message.descriptor.protocol,
-    protocolPath,
-    recipient,
-  };
-
   const parentContextId = Records.getParentContextFromOfContextId(incomingRecordsWrite.message.contextId)!;
 
-  // if this is not the root record, add a prefix filter to the query
-  if (parentContextId !== '') {
-    const prefixFilter = FilterUtility.constructPrefixFilterAsRangeFilter(parentContextId);
-    filter.contextId = prefixFilter;
-  }
+  // if this is not the root record, scope the role-record query to the parent context
+  const matchingRecords = await validationStateReader.queryLatestRoleRecords({
+    tenant,
+    protocol        : incomingRecordsWrite.message.descriptor.protocol,
+    protocolPath,
+    recipient,
+    contextIdPrefix : parentContextId === '' ? undefined : parentContextId,
+  });
 
-  const { messages: matchingMessages } = await messageStore.query(tenant, [filter]);
-  const matchingRecords = matchingMessages as RecordsWriteMessage[];
   const matchingRecordsExceptIncomingRecordId = matchingRecords.filter((recordsWriteMessage: RecordsWriteMessage): boolean =>
     recordsWriteMessage.recordId !== incomingRecordsWrite.message.recordId
   );
@@ -393,65 +354,30 @@ export async function verifyAsRoleRecordIfNeeded(
 }
 
 /**
- * Verifies that a new record creation does not exceed the `$recordLimit` defined in the rule set.
+ * Verifies that the `$recordLimit` strategy is supported for a new record creation.
  *
- * This check only applies to initial writes (new records). Updates to existing records are not counted.
- * The count is scoped to the same `protocol + protocolPath` within the parent context:
- * - For root-level records: counted across the entire protocol for the tenant.
- * - For nested records: counted within the parent record's context.
+ * This check only applies to initial writes (new records). Updates to existing records do not
+ * affect record-limit occupancy. The supported `reject` strategy admits every candidate and
+ * projects the visible occupant set at read time, so validation stays independent of arrival order.
  *
- * @throws {DwnError} with `ProtocolAuthorizationRecordLimitExceeded` if the limit is reached and strategy is `reject`.
- * @throws {DwnError} with `ProtocolAuthorizationRecordLimitStrategyNotImplemented` if strategy is not yet implemented.
+ * @throws {DwnError} with `ProtocolAuthorizationRecordLimitStrategyNotImplemented` if strategy is not implemented.
  */
 export async function verifyRecordLimit(
-  tenant: string,
   incomingMessage: RecordsWrite,
   ruleSet: ProtocolRuleSet,
-  messageStore: MessageStore,
 ): Promise<void> {
   if (ruleSet.$recordLimit === undefined) {
     return;
   }
 
-  // Only enforce on initial writes — updates to existing records do not count as new records.
+  // Only initial writes can introduce a new record-limit candidate.
   const isInitialWrite = await incomingMessage.isInitialWrite();
   if (!isInitialWrite) {
     return;
   }
 
-  const { max, strategy } = ruleSet.$recordLimit;
-
-  // Build a filter to count existing records at the same protocol path and parent context.
-  const protocolPath = incomingMessage.message.descriptor.protocolPath;
-  const filter: Filter = {
-    interface         : DwnInterfaceName.Records,
-    method            : DwnMethodName.Write,
-    isLatestBaseState : true,
-    protocol          : incomingMessage.message.descriptor.protocol,
-    protocolPath,
-  };
-
-  // Scope by parent context for nested records.
-  const parentContextId = Records.getParentContextFromOfContextId(incomingMessage.message.contextId)!;
-  if (parentContextId !== '') {
-    const prefixFilter = FilterUtility.constructPrefixFilterAsRangeFilter(parentContextId);
-    filter.contextId = prefixFilter;
-  }
-
-  const existingCount = await messageStore.count(tenant, [filter]);
-
-  if (existingCount >= max) {
-    if (strategy === ProtocolRecordLimitStrategy.Reject) {
-      throw new DwnError(
-        DwnErrorCode.ProtocolAuthorizationRecordLimitExceeded,
-        `record limit of ${max} reached at protocol path '${protocolPath}'` +
-        `${parentContextId === '' ? '' : ` under parent context '${parentContextId}'`}` +
-        `: new records are rejected until existing records are deleted.`
-      );
-    }
-
-    // Future strategies (e.g. purgeOldest) will be implemented here.
-    // For now, any non-reject strategy that somehow passes schema validation is rejected.
+  const { strategy } = ruleSet.$recordLimit;
+  if (strategy !== ProtocolRecordLimitStrategy.Reject) {
     throw new DwnError(
       DwnErrorCode.ProtocolAuthorizationRecordLimitStrategyNotImplemented,
       `record limit strategy '${strategy}' is not yet implemented.`