@enbox/dwn-sdk-js 0.0.7 → 0.1.0

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

@@ -3,6 +3,8 @@ import type { MessageStore } from '../types/message-store.js';
 import type { RecordsWriteMessage } from '../types/records-types.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';
@@ -389,3 +391,134 @@ export async function verifyAsRoleRecordIfNeeded(
     );
   }
 }
+
+/**
+ * Verifies that a new record creation does not exceed the `$recordLimit` defined in the rule set.
+ *
+ * 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.
+ *
+ * @throws {DwnError} with `ProtocolAuthorizationRecordLimitExceeded` if the limit is reached and strategy is `reject`.
+ * @throws {DwnError} with `ProtocolAuthorizationRecordLimitStrategyNotImplemented` if strategy is not yet 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.
+  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.
+    throw new DwnError(
+      DwnErrorCode.ProtocolAuthorizationRecordLimitStrategyNotImplemented,
+      `record limit strategy '${strategy}' is not yet implemented.`
+    );
+  }
+}
+
+/**
+ * Verifies that a `RecordsWrite` with `squash: true` is eligible:
+ * 1. The protocol rule set at the record's `protocolPath` must have `$squash: true`.
+ * 2. The squash write must be an initial write (a new record, not an update).
+ *
+ * @throws {DwnError} with `ProtocolAuthorizationSquashNotEnabled` if `$squash` is not enabled.
+ * @throws {DwnError} with `ProtocolAuthorizationSquashNotInitialWrite` if the squash write is not an initial write.
+ */
+export async function verifySquashEligibility(
+  incomingMessage: RecordsWrite,
+  ruleSet: ProtocolRuleSet,
+): Promise<void> {
+  const squash = incomingMessage.message.descriptor.squash;
+
+  if (squash !== true) {
+    return;
+  }
+
+  // squash write must be at a protocol path with $squash: true
+  if (ruleSet.$squash !== true) {
+    throw new DwnError(
+      DwnErrorCode.ProtocolAuthorizationSquashNotEnabled,
+      `squash writes are not enabled at protocol path '${incomingMessage.message.descriptor.protocolPath}': ` +
+      `rule set must have $squash: true.`
+    );
+  }
+
+  // squash write must be an initial write (a new record, not an update)
+  const isInitialWrite = await incomingMessage.isInitialWrite();
+  if (!isInitialWrite) {
+    throw new DwnError(
+      DwnErrorCode.ProtocolAuthorizationSquashNotInitialWrite,
+      `squash write must be an initial write (a new record): updates cannot be squash writes.`
+    );
+  }
+}
+
+/**
+ * Verifies that an update is not attempted on a record whose protocol path has `$immutable: true`.
+ *
+ * Only non-initial writes (updates) are rejected — initial writes are always allowed.
+ * `RecordsDelete` is not affected by this check; immutability prevents data mutation, not removal.
+ *
+ * @throws {DwnError} with `ProtocolAuthorizationImmutableRecord` if an update is attempted on an immutable record.
+ */
+export async function verifyImmutability(
+  incomingMessage: RecordsWrite,
+  ruleSet: ProtocolRuleSet,
+): Promise<void> {
+  if (ruleSet.$immutable !== true) {
+    return;
+  }
+
+  const isInitialWrite = await incomingMessage.isInitialWrite();
+  if (isInitialWrite) {
+    return;
+  }
+
+  throw new DwnError(
+    DwnErrorCode.ProtocolAuthorizationImmutableRecord,
+    `record at protocol path '${incomingMessage.message.descriptor.protocolPath}' is immutable: updates are not allowed.`
+  );
+}

package/src/core/protocol-authorization.ts

@@ -1,6 +1,6 @@
+import type { CoreProtocolRegistry } from './core-protocol.js';
 import type { Filter } from '../types/query-types.js';
 import type { MessageStore } from '../types/message-store.js';
-import type { ProtocolAction } from '../types/protocols-types.js';
 import type { RecordsCount } from '../interfaces/records-count.js';
 import type { RecordsDelete } from '../interfaces/records-delete.js';
 import type { RecordsQuery } from '../interfaces/records-query.js';
@@ -11,17 +11,19 @@ import type { RecordsWriteMessage } from '../types/records-types.js';
 import type { ProtocolDefinition, ProtocolRuleSet, ProtocolsConfigureMessage } from '../types/protocols-types.js';
 
 import { getRuleSetAtPath } from '../utils/protocols.js';
-import { PermissionsProtocol } from '../protocols/permissions.js';
 import { SortDirection } from '../types/query-types.js';
 import { DwnError, DwnErrorCode } from './dwn-error.js';
 import { DwnInterfaceName, DwnMethodName } from '../enums/dwn-interface-method.js';
 
-import { authorizeAgainstAllowedActions, getActionsSeekingARuleMatch, verifyInvokedRole } from './protocol-authorization-action.js';
+import { authorizeAgainstAllowedActions, verifyInvokedRole } from './protocol-authorization-action.js';
 import { constructRecordChain, fetchInitialWrite, getGoverningTimestamp } from './record-chain.js';
 import {
   verifyAsRoleRecordIfNeeded,
+  verifyImmutability,
   verifyProtocolPathAndContextId,
+  verifyRecordLimit,
   verifySizeLimit,
+  verifySquashEligibility,
   verifyTagsIfNeeded,
   verifyTypeWithComposition,
 } from './protocol-authorization-validation.js';
@@ -47,6 +49,7 @@ export class ProtocolAuthorization {
     tenant: string,
     incomingMessage: RecordsWrite,
     messageStore: MessageStore,
+    coreProtocols?: CoreProtocolRegistry,
   ): Promise<void> {
     // Determine the governing timestamp for protocol definition lookup.
     // For an initial write, this is the message's own timestamp.
@@ -61,19 +64,23 @@ export class ProtocolAuthorization {
       incomingMessage.message.descriptor.protocol!,
       messageStore,
       governingTimestamp,
+      coreProtocols,
     );
 
+    // Create a bound fetch function that captures the registry for downstream callbacks.
+    const boundFetchDefinition = ProtocolAuthorization.createBoundFetchDefinition(coreProtocols);
+
     // verify declared protocol type exists in protocol and that it conforms to type specification.
     // For cross-protocol composition, the type may be defined in a referenced protocol.
     await verifyTypeWithComposition(
       tenant, incomingMessage.message, protocolDefinition, messageStore,
-      ProtocolAuthorization.fetchProtocolDefinition, governingTimestamp
+      boundFetchDefinition, governingTimestamp
     );
 
     // validate `protocolPath`
     await verifyProtocolPathAndContextId(
       tenant, incomingMessage, messageStore,
-      ProtocolAuthorization.fetchProtocolDefinition, governingTimestamp,
+      boundFetchDefinition, governingTimestamp,
     );
 
     // get the rule set for the inbound message
@@ -95,6 +102,15 @@ export class ProtocolAuthorization {
 
     // Verify protocol tags
     verifyTagsIfNeeded(incomingMessage, ruleSet);
+
+    // Verify immutability — reject updates to write-once records
+    await verifyImmutability(incomingMessage, ruleSet);
+
+    // Verify squash eligibility — ensure squash writes are at $squash: true paths and are initial writes
+    await verifySquashEligibility(incomingMessage, ruleSet);
+
+    // Verify record count limit
+    await verifyRecordLimit(tenant, incomingMessage, ruleSet, messageStore);
   }
 
   /**
@@ -105,6 +121,7 @@ export class ProtocolAuthorization {
     tenant: string,
     incomingMessage: RecordsWrite,
     messageStore: MessageStore,
+    coreProtocols?: CoreProtocolRegistry,
   ): Promise<void> {
     const existingInitialWrite = await fetchInitialWrite(tenant, incomingMessage.message.recordId, messageStore);
 
@@ -129,6 +146,7 @@ export class ProtocolAuthorization {
       incomingMessage.message.descriptor.protocol!,
       messageStore,
       governingTimestamp,
+      coreProtocols,
     );
 
     // get the rule set for the inbound message
@@ -137,6 +155,8 @@ export class ProtocolAuthorization {
       protocolDefinition,
     );
 
+    const boundFetchDefinition = ProtocolAuthorization.createBoundFetchDefinition(coreProtocols);
+
     // If the incoming message has `protocolRole` in the descriptor, validate the invoked role
     await verifyInvokedRole(
       tenant,
@@ -145,7 +165,7 @@ export class ProtocolAuthorization {
       incomingMessage.message.contextId!,
       protocolDefinition,
       messageStore,
-      ProtocolAuthorization.fetchProtocolDefinition,
+      boundFetchDefinition,
       governingTimestamp,
     );
 
@@ -170,6 +190,7 @@ export class ProtocolAuthorization {
     incomingMessage: RecordsRead,
     newestRecordsWrite: RecordsWrite,
     messageStore: MessageStore,
+    coreProtocols?: CoreProtocolRegistry,
   ): Promise<void> {
     // fetch record chain
     const recordChain: RecordsWriteMessage[] =
@@ -190,6 +211,7 @@ export class ProtocolAuthorization {
       newestRecordsWrite.message.descriptor.protocol!,
       messageStore,
       governingTimestamp,
+      coreProtocols,
     );
 
     // get the rule set for the inbound message
@@ -198,6 +220,8 @@ export class ProtocolAuthorization {
       protocolDefinition,
     );
 
+    const boundFetchDefinition = ProtocolAuthorization.createBoundFetchDefinition(coreProtocols);
+
     // If the incoming message has `protocolRole` in the descriptor, validate the invoked role
     await verifyInvokedRole(
       tenant,
@@ -206,7 +230,7 @@ export class ProtocolAuthorization {
       newestRecordsWrite.message.contextId!,
       protocolDefinition,
       messageStore,
-      ProtocolAuthorization.fetchProtocolDefinition,
+      boundFetchDefinition,
       governingTimestamp,
     );
 
@@ -225,6 +249,7 @@ export class ProtocolAuthorization {
     tenant: string,
     incomingMessage: RecordsCount | RecordsQuery | RecordsSubscribe,
     messageStore: MessageStore,
+    coreProtocols?: CoreProtocolRegistry,
   ): Promise<void> {
     const { protocol, protocolPath, contextId } = incomingMessage.message.descriptor.filter;
 
@@ -233,6 +258,8 @@ export class ProtocolAuthorization {
       tenant,
       protocol!, // `authorizeQueryOrSubscribe` is only called if `protocol` is present
       messageStore,
+      undefined,
+      coreProtocols,
     );
 
     // get the rule set for the inbound message
@@ -241,6 +268,8 @@ export class ProtocolAuthorization {
       protocolDefinition,
     );
 
+    const boundFetchDefinition = ProtocolAuthorization.createBoundFetchDefinition(coreProtocols);
+
     // If the incoming message has `protocolRole` in the descriptor, validate the invoked role
     await verifyInvokedRole(
       tenant,
@@ -249,7 +278,7 @@ export class ProtocolAuthorization {
       contextId,
       protocolDefinition,
       messageStore,
-      ProtocolAuthorization.fetchProtocolDefinition,
+      boundFetchDefinition,
     );
 
     // verify method invoked against the allowed actions in the rule set
@@ -272,6 +301,7 @@ export class ProtocolAuthorization {
     incomingMessage: RecordsDelete,
     recordsWrite: RecordsWrite,
     messageStore: MessageStore,
+    coreProtocols?: CoreProtocolRegistry,
   ): Promise<void> {
 
     // fetch record chain
@@ -292,6 +322,7 @@ export class ProtocolAuthorization {
       recordsWrite.message.descriptor.protocol!,
       messageStore,
       governingTimestamp,
+      coreProtocols,
     );
 
     // get the rule set for the inbound message
@@ -300,6 +331,8 @@ export class ProtocolAuthorization {
       protocolDefinition,
     );
 
+    const boundFetchDefinition = ProtocolAuthorization.createBoundFetchDefinition(coreProtocols);
+
     // If the incoming message has `protocolRole` in the descriptor, validate the invoked role
     await verifyInvokedRole(
       tenant,
@@ -308,7 +341,7 @@ export class ProtocolAuthorization {
       recordsWrite.message.contextId!,
       protocolDefinition,
       messageStore,
-      ProtocolAuthorization.fetchProtocolDefinition,
+      boundFetchDefinition,
       governingTimestamp,
     );
 
@@ -328,16 +361,25 @@ export class ProtocolAuthorization {
    * When `messageTimestamp` is provided, returns the protocol definition that was active at that
    * point in time — i.e. the ProtocolsConfigure with the greatest `messageTimestamp` that is <= the
    * given timestamp. When not provided, returns the latest (current) protocol definition.
+   *
+   * When `coreProtocols` is provided, core protocol definitions are returned directly from the
+   * registry without a message store query. The extra parameter does not affect the
+   * `FetchProtocolDefinitionFn` callback type — callers that pass this function as a callback
+   * should bind the registry via a closure (see `createBoundFetchDefinition`).
    */
   public static async fetchProtocolDefinition(
     tenant: string,
     protocolUri: string,
     messageStore: MessageStore,
     messageTimestamp?: string,
+    coreProtocols?: CoreProtocolRegistry,
   ): Promise<ProtocolDefinition> {
-    // if first-class protocol, return the definition from const object directly without going to data store
-    if (protocolUri === PermissionsProtocol.uri) {
-      return PermissionsProtocol.definition;
+    // if the protocol is a registered core protocol, return the definition directly without a store query
+    if (coreProtocols !== undefined) {
+      const coreDefinition = coreProtocols.getDefinition(protocolUri);
+      if (coreDefinition !== undefined) {
+        return coreDefinition;
+      }
     }
 
     // fetch the corresponding protocol definition
@@ -370,6 +412,23 @@ export class ProtocolAuthorization {
     return protocolMessage.descriptor.definition;
   }
 
+  /**
+   * Creates a `FetchProtocolDefinitionFn` closure that binds the given `CoreProtocolRegistry`.
+   * This allows core protocol definitions to be resolved from the registry without changing
+   * the `FetchProtocolDefinitionFn` type signature — zero ripple to downstream consumers
+   * like `protocol-authorization-action.ts` and `protocol-authorization-validation.ts`.
+   */
+  private static createBoundFetchDefinition(coreProtocols?: CoreProtocolRegistry): FetchProtocolDefinitionFn {
+    return (
+      tenant: string,
+      protocolUri: string,
+      messageStore: MessageStore,
+      messageTimestamp?: string,
+    ): Promise<ProtocolDefinition> => {
+      return ProtocolAuthorization.fetchProtocolDefinition(tenant, protocolUri, messageStore, messageTimestamp, coreProtocols);
+    };
+  }
+
   /**
    * Gets the rule set corresponding to the given protocolPath.
    */
@@ -385,15 +444,4 @@ export class ProtocolAuthorization {
     return ruleSet;
   }
 
-  /**
-   * Returns all the ProtocolActions that would authorize the incoming message.
-   * Delegates to the standalone function in `protocol-authorization-action.ts`.
-   */
-  private static async getActionsSeekingARuleMatch(
-    tenant: string,
-    incomingMessage: RecordsCount | RecordsDelete | RecordsQuery | RecordsRead | RecordsSubscribe | RecordsWrite,
-    messageStore: MessageStore,
-  ): Promise<ProtocolAction[]> {
-    return getActionsSeekingARuleMatch(tenant, incomingMessage, messageStore);
-  }
 }

package/src/core/records-grant-authorization.ts

@@ -87,15 +87,14 @@ export class RecordsGrantAuthorization {
       messageStore
     });
 
-    // If the grant specifies a protocol, the subscribe or query must specify the same protocol.
+    // The grant's protocol must match the query/subscribe filter's protocol.
     // NOTE: validated the invoked permission is for Records in GrantAuthorization.performBaseValidation()
     const permissionScope = permissionGrant.scope as RecordsPermissionScope;
-    const protocolInGrant = permissionScope.protocol;
     const protocolInMessage = incomingMessage.descriptor.filter.protocol;
-    if (protocolInGrant !== undefined && protocolInMessage !== protocolInGrant) {
+    if (protocolInMessage !== permissionScope.protocol) {
       throw new DwnError(
         DwnErrorCode.RecordsGrantAuthorizationQueryOrSubscribeProtocolScopeMismatch,
-        `Grant protocol scope ${protocolInGrant} does not match protocol in message ${protocolInMessage}`
+        `Grant protocol scope ${permissionScope.protocol} does not match protocol in message ${protocolInMessage}`
       );
     }
   }
@@ -124,15 +123,14 @@ export class RecordsGrantAuthorization {
       messageStore
     });
 
-    // If the grant specifies a protocol, the delete must be deleting a record with the same protocol.
+    // The grant's protocol must match the protocol of the record being deleted.
     // NOTE: validated the invoked permission is for Records in GrantAuthorization.performBaseValidation()
     const permissionScope = permissionGrant.scope as RecordsPermissionScope;
-    const protocolInGrant = permissionScope.protocol;
     const protocolOfRecordToDelete = recordsWriteToDelete.descriptor.protocol;
-    if (protocolInGrant !== undefined && protocolOfRecordToDelete !== protocolInGrant) {
+    if (protocolOfRecordToDelete !== permissionScope.protocol) {
       throw new DwnError(
         DwnErrorCode.RecordsGrantAuthorizationDeleteProtocolScopeMismatch,
-        `Grant protocol scope ${protocolInGrant} does not match protocol in record to delete ${protocolOfRecordToDelete}`
+        `Grant protocol scope ${permissionScope.protocol} does not match protocol in record to delete ${protocolOfRecordToDelete}`
       );
     }
   }

package/src/core/resumable-task-manager.ts

@@ -3,6 +3,7 @@ import type { ManagedResumableTask, ResumableTaskStore } from '../types/resumabl
 
 export enum ResumableTaskName {
   RecordsDelete = 'RecordsDelete',
+  RecordsSquash = 'RecordsSquash',
 }
 
 export type ResumableTask = {
@@ -26,7 +27,8 @@ export class ResumableTaskManager {
     this.resumableTaskHandlers = {
       // NOTE: The arrow function is IMPORTANT here, else the `this` context will be lost within the invoked method.
       // e.g. code within performRecordsDelete() won't know `this` refers to the `storageController` instance.
-      [ResumableTaskName.RecordsDelete]: async (task): Promise<void> => await storageController.performRecordsDelete(task),
+      [ResumableTaskName.RecordsDelete] : async (task): Promise<void> => await storageController.performRecordsDelete(task),
+      [ResumableTaskName.RecordsSquash] : async (task): Promise<void> => await storageController.performRecordsSquash(task),
     };
   }