@enbox/dwn-sdk-js 0.4.0 → 0.4.2

package/src/types/validation-state-reader.ts

@@ -0,0 +1,127 @@
+import type { GenericMessage } from './message-types.js';
+import type { PermissionGrant } from '../protocols/permission-grant.js';
+import type { ProtocolDefinition } from './protocols-types.js';
+import type { RecordsWrite } from '../interfaces/records-write.js';
+import type { RecordsWriteMessage } from './records-types.js';
+
+/**
+ * The single narrow surface through which validation logic reads state.
+ *
+ * Every validation-time state read performed during message admission routes through this
+ * interface, so the replay basis (initial writes ∪ latest states ∪ tombstones ∪ protocol-config
+ * history ∪ permission records) provably stays closed under admission's read set. Validation
+ * modules (`core/protocol-authorization*`, `protocols/permissions*`) are lint-banned from
+ * importing `MessageStore` directly; a new protocol-engine feature that needs new state must add
+ * a reader method here.
+ */
+export interface ValidationStateReader {
+  /**
+   * Fetches a record's initial `RecordsWrite` by entry ID, parsed.
+   * @returns the initial write, or `undefined` when no message carries the entry ID.
+   */
+  fetchInitialRecordsWrite(tenant: string, recordId: string): Promise<RecordsWrite | undefined>;
+
+  /**
+   * Fetches a record's initial write from among all of the record's writes.
+   * @returns the initial write message, or `undefined` when the record has no messages at all.
+   * @throws {DwnError} with `RecordsWriteGetInitialWriteNotFound` when writes exist for the
+   *         record but none of them is the initial write.
+   */
+  fetchInitialWrite(tenant: string, recordId: string): Promise<RecordsWriteMessage | undefined>;
+
+  /**
+   * Constructs the chain of existing records from the root to the given
+   * descendant, each represented by its initial `RecordsWrite`.
+   * @returns the chain root-first; an empty array when `descendantRecordId` is `undefined`.
+   * @throws {DwnError} with `ProtocolAuthorizationParentNotFoundConstructingRecordChain` when any
+   *         link in the chain is missing.
+   */
+  constructRecordChain(tenant: string, descendantRecordId: string | undefined): Promise<RecordsWriteMessage[]>;
+
+  /**
+   * Fetches the immediate parent record for protocolPath/contextId verification.
+   *
+   * Queries the latest-state write first — the fast path that excludes deleted parents. If no
+   * latest write exists, a retained initial write is sufficient for immutable parent facts
+   * (protocolPath/contextId) provided no local tombstone exists for that record.
+   * @returns the parent write, or `undefined` when the parent is absent (or deleted).
+   */
+  fetchParentRecord(input: {
+    tenant: string;
+    parentProtocolUri: string;
+    parentId: string;
+  }): Promise<RecordsWriteMessage | undefined>;
+
+  /**
+   * Checks whether a role record matching the invoked-role selector exists.
+   * Filter-only — role validation never reads record data. The latest-state match is the fast
+   * path. If no latest match exists, a retained initial role write is sufficient for immutable
+   * role facts (recipient/path/context) provided no local tombstone exists for that role record.
+   */
+  hasMatchingRoleRecord(input: {
+    tenant: string;
+    protocol: string;
+    protocolPath: string;
+    recipient: string;
+    contextIdPrefix?: string;
+  }): Promise<boolean>;
+
+  /**
+   * Queries the latest-state role records matching the given
+   * selector, used to reject duplicate role assignments to the same recipient. Filter-only.
+   */
+  queryLatestRoleRecords(input: {
+    tenant: string;
+    protocol: string;
+    protocolPath: string;
+    recipient: string;
+    contextIdPrefix?: string;
+  }): Promise<RecordsWriteMessage[]>;
+
+  /**
+   * Fetches the permission grant with the given record ID, with its scope parsed from grant data.
+   * @throws {DwnError} with `GrantAuthorizationGrantMissing` when the grant does not exist.
+   */
+  fetchGrant(tenant: string, permissionGrantId: string): Promise<PermissionGrant>;
+
+  /**
+   * Fetches the oldest latest-state revocation record for the given permission grant, if any.
+   * Grant activity checks compare the oldest revocation timestamp to the incoming message timestamp.
+   */
+  fetchOldestGrantRevocation(tenant: string, permissionGrantId: string): Promise<GenericMessage | undefined>;
+
+  /**
+   * Fetches the newest `RecordsWrite` associated with a record, used to authorize `Messages.Read`
+   * access to `RecordsDelete` messages by projecting the delete back to the deleted record's
+   * protocol scope.
+   * @throws {DwnError} with `RecordsWriteGetNewestWriteRecordNotFound` when no write exists.
+   */
+  fetchNewestRecordsWrite(tenant: string, recordId: string): Promise<RecordsWriteMessage>;
+
+  /**
+   * Fetches the protocol definition for the given protocol URI.
+   * When `messageTimestamp` is provided, returns the definition active at that point in time —
+   * the `ProtocolsConfigure` with the greatest `messageTimestamp` that is <= the given timestamp,
+   * read from retained config history. When not provided, returns the latest definition.
+   * Core protocol definitions are returned from the registry without a store read.
+   * @throws {DwnError} with `ProtocolAuthorizationProtocolNotFound` when no definition exists.
+   */
+  fetchProtocolDefinition(tenant: string, protocolUri: string, messageTimestamp?: string): Promise<ProtocolDefinition>;
+
+  /**
+   * Fetches the latest `$squash: true` record at a protocol path within the parent context.
+   * This is the temporal floor used by the squash backstop.
+   */
+  fetchLatestSquashRecordAtScope(input: {
+    tenant: string;
+    protocol: string;
+    protocolPath: string;
+    contextIdPrefix?: string;
+  }): Promise<RecordsWriteMessage | undefined>;
+
+  /**
+   * Checks whether the data with the given CID is present in the `DataStore` for the given record.
+   * This is the prior-data integrity check for dataless non-initial writes.
+   */
+  hasStoredData(tenant: string, recordId: string, dataCid: string): Promise<boolean>;
+}

package/src/utils/messages.ts

@@ -1,11 +1,15 @@
 import type { CoreProtocolRegistry } from '../core/core-protocol.js';
 import type { Filter } from '../types/query-types.js';
+import type { GenericMessage } from '../types/message-types.js';
 import type { MessagesFilter } from '../types/messages-types.js';
 
 import { FilterUtility } from './filter.js';
 import { normalizeProtocolUrl } from './url.js';
+import { Records } from './records.js';
 import { isEmptyObject, removeUndefinedProperties } from '@enbox/common';
 
+type StoredMessageWithEncodedData = GenericMessage & { encodedData?: string };
+
 
 /**
  * Class containing Messages related utility methods.
@@ -95,6 +99,22 @@ export class Messages {
     return messagesQueryFilters;
   }
 
+  /**
+   * Returns a copy of a RecordsWrite message without inline encodedData, and the
+   * detached encodedData value for wire surfaces that carry data beside the message.
+   */
+  public static detachEncodedData(message: GenericMessage): { message: GenericMessage; encodedData?: string } {
+    if (!Records.isRecordsWrite(message) || !Messages.hasEncodedData(message)) {
+      return { message };
+    }
+
+    const messageWithoutEncodedData: StoredMessageWithEncodedData = { ...message };
+    const { encodedData } = messageWithoutEncodedData;
+    delete messageWithoutEncodedData.encodedData;
+
+    return { message: messageWithoutEncodedData, encodedData };
+  }
+
   /**
    * Converts an external-facing filter model into an internal-facing filer model used by data store.
    */
@@ -132,4 +152,8 @@ export class Messages {
 
     return filterCopy;
   }
-}
+
+  private static hasEncodedData(message: GenericMessage): message is StoredMessageWithEncodedData {
+    return 'encodedData' in message && typeof message.encodedData === 'string';
+  }
+}

package/src/utils/protocol-tags.ts

@@ -0,0 +1,366 @@
+import type { ProtocolTagSchema, ProtocolTagsDefinition } from '../types/protocols-types.js';
+
+type TagSchema = ProtocolTagSchema | Record<string, unknown>;
+
+type TagValidationError = {
+  instancePath: string;
+  message: string;
+};
+
+const allowedTagTypes = new Set(['string', 'number', 'integer', 'boolean', 'array']);
+const allowedArrayItemTypes = new Set(['string', 'number', 'integer']);
+const numericConstraintKeywords = [ 'minimum', 'maximum', 'exclusiveMinimum', 'exclusiveMaximum' ];
+const stringConstraintKeywords = [ 'minLength', 'maxLength' ];
+const arrayConstraintKeywords = [ 'minItems', 'maxItems', 'minContains', 'maxContains' ];
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+
+function pathSegment(segment: string | number): string {
+  return String(segment).replaceAll('~', '~0').replaceAll('/', '~1');
+}
+
+function appendPath(path: string, segment: string | number): string {
+  return `${path}/${pathSegment(segment)}`;
+}
+
+function hasOwnProperty(value: Record<string, unknown>, property: string): boolean {
+  return Object.hasOwn(value, property);
+}
+
+function addError(errors: TagValidationError[], instancePath: string, message: string): void {
+  errors.push({ instancePath, message });
+}
+
+function isNumber(value: unknown): value is number {
+  return typeof value === 'number' && Number.isFinite(value);
+}
+
+function valuesEqual(left: unknown, right: unknown): boolean {
+  if (Object.is(left, right)) {
+    return true;
+  }
+
+  if (Array.isArray(left) && Array.isArray(right)) {
+    return left.length === right.length && left.every((value, index) => valuesEqual(value, right[index]));
+  }
+
+  if (isRecord(left) && isRecord(right)) {
+    const leftKeys = Object.keys(left);
+    const rightKeys = Object.keys(right);
+
+    return leftKeys.length === rightKeys.length
+      && leftKeys.every(key => Object.hasOwn(right, key) && valuesEqual(left[key], right[key]));
+  }
+
+  return false;
+}
+
+function getTagSchemas(tagsDefinition: ProtocolTagsDefinition): Record<string, TagSchema> {
+  const schemas: Record<string, TagSchema> = {};
+
+  for (const [ tag, schema ] of Object.entries(tagsDefinition)) {
+    if (tag === '$requiredTags' || tag === '$allowUndefinedTags') {
+      continue;
+    }
+
+    schemas[tag] = schema as TagSchema;
+  }
+
+  return schemas;
+}
+
+function validateSchemaConstraintTypes(
+  schema: Record<string, unknown>,
+  dataPath: string,
+  errors: TagValidationError[],
+): void {
+  if (schema.enum !== undefined) {
+    if (!Array.isArray(schema.enum) || schema.enum.length === 0) {
+      addError(errors, appendPath(dataPath, 'enum'), 'must be non-empty array');
+    }
+  }
+
+  for (const keyword of numericConstraintKeywords) {
+    if (schema[keyword] !== undefined && !isNumber(schema[keyword])) {
+      addError(errors, appendPath(dataPath, keyword), 'must be number');
+    }
+  }
+
+  for (const keyword of [ ...stringConstraintKeywords, ...arrayConstraintKeywords ]) {
+    if (schema[keyword] !== undefined && (!Number.isInteger(schema[keyword]) || (schema[keyword] as number) < 0)) {
+      addError(errors, appendPath(dataPath, keyword), 'must be integer');
+    }
+  }
+
+  if (schema.uniqueItems !== undefined && typeof schema.uniqueItems !== 'boolean') {
+    addError(errors, appendPath(dataPath, 'uniqueItems'), 'must be boolean');
+  }
+}
+
+function validateTagSubschemaDefinition(
+  schema: unknown,
+  dataPath: string,
+  allowedTypes: Set<string>,
+  errors: TagValidationError[],
+): void {
+  if (!isRecord(schema)) {
+    addError(errors, dataPath, 'must be object');
+    return;
+  }
+
+  if (schema.type !== undefined && (typeof schema.type !== 'string' || !allowedTypes.has(schema.type))) {
+    addError(errors, appendPath(dataPath, 'type'), 'must be equal to one of the allowed values');
+  }
+
+  validateSchemaConstraintTypes(schema, dataPath, errors);
+}
+
+/**
+ * Validates DWN protocol tag schema definitions without invoking Ajv's runtime compiler.
+ *
+ * The broader protocol message shape is already checked by the precompiled
+ * ProtocolRuleSet validator. This function covers the tag-schema constraints
+ * that are deliberately modeled as a small DWN subset rather than arbitrary
+ * JSON Schema.
+ */
+export function validateProtocolTagSchemaDefinition(
+  schema: unknown,
+  dataVar: string,
+): string | undefined {
+  const errors: TagValidationError[] = [];
+
+  validateTagSubschemaDefinition(schema, '', allowedTagTypes, errors);
+
+  if (isRecord(schema)) {
+    if (schema.items !== undefined) {
+      validateTagSubschemaDefinition(schema.items, '/items', allowedArrayItemTypes, errors);
+    }
+
+    if (schema.contains !== undefined) {
+      validateTagSubschemaDefinition(schema.contains, '/contains', allowedArrayItemTypes, errors);
+    }
+  }
+
+  return formatTagValidationErrors(errors, dataVar);
+}
+
+function validateType(type: unknown, value: unknown, dataPath: string, errors: TagValidationError[]): boolean {
+  switch (type) {
+  case undefined:
+    return true;
+  case 'string':
+    if (typeof value === 'string') {
+      return true;
+    }
+    addError(errors, dataPath, 'must be string');
+    return false;
+  case 'number':
+    if (isNumber(value)) {
+      return true;
+    }
+    addError(errors, dataPath, 'must be number');
+    return false;
+  case 'integer':
+    if (isNumber(value) && Number.isInteger(value)) {
+      return true;
+    }
+    addError(errors, dataPath, 'must be integer');
+    return false;
+  case 'boolean':
+    if (typeof value === 'boolean') {
+      return true;
+    }
+    addError(errors, dataPath, 'must be boolean');
+    return false;
+  case 'array':
+    if (Array.isArray(value)) {
+      return true;
+    }
+    addError(errors, dataPath, 'must be array');
+    return false;
+  default:
+    addError(errors, dataPath, 'must match a supported tag schema type');
+    return false;
+  }
+}
+
+function validateEnum(schema: Record<string, unknown>, value: unknown, dataPath: string, errors: TagValidationError[]): void {
+  if (Array.isArray(schema.enum) && !schema.enum.some(allowed => valuesEqual(allowed, value))) {
+    addError(errors, dataPath, 'must be equal to one of the allowed values');
+  }
+}
+
+function validateNumberConstraints(
+  schema: Record<string, unknown>,
+  value: unknown,
+  dataPath: string,
+  errors: TagValidationError[],
+): void {
+  if (!isNumber(value)) {
+    return;
+  }
+
+  if (isNumber(schema.minimum) && value < schema.minimum) {
+    addError(errors, dataPath, `must be >= ${schema.minimum}`);
+  }
+
+  if (isNumber(schema.maximum) && value > schema.maximum) {
+    addError(errors, dataPath, `must be <= ${schema.maximum}`);
+  }
+
+  if (isNumber(schema.exclusiveMinimum) && value <= schema.exclusiveMinimum) {
+    addError(errors, dataPath, `must be > ${schema.exclusiveMinimum}`);
+  }
+
+  if (isNumber(schema.exclusiveMaximum) && value >= schema.exclusiveMaximum) {
+    addError(errors, dataPath, `must be < ${schema.exclusiveMaximum}`);
+  }
+}
+
+function validateStringConstraints(
+  schema: Record<string, unknown>,
+  value: unknown,
+  dataPath: string,
+  errors: TagValidationError[],
+): void {
+  if (typeof value !== 'string') {
+    return;
+  }
+
+  if (Number.isInteger(schema.minLength) && value.length < (schema.minLength as number)) {
+    addError(errors, dataPath, `must NOT have fewer than ${schema.minLength} characters`);
+  }
+
+  if (Number.isInteger(schema.maxLength) && value.length > (schema.maxLength as number)) {
+    addError(errors, dataPath, `must NOT have more than ${schema.maxLength} characters`);
+  }
+}
+
+function validateArrayConstraints(
+  schema: Record<string, unknown>,
+  value: unknown,
+  dataPath: string,
+  errors: TagValidationError[],
+): void {
+  if (!Array.isArray(value)) {
+    return;
+  }
+
+  if (Number.isInteger(schema.minItems) && value.length < (schema.minItems as number)) {
+    addError(errors, dataPath, `must NOT have fewer than ${schema.minItems} items`);
+  }
+
+  if (Number.isInteger(schema.maxItems) && value.length > (schema.maxItems as number)) {
+    addError(errors, dataPath, `must NOT have more than ${schema.maxItems} items`);
+  }
+
+  if (schema.uniqueItems === true) {
+    for (let i = 0; i < value.length; i++) {
+      for (let j = i + 1; j < value.length; j++) {
+        if (valuesEqual(value[i], value[j])) {
+          addError(errors, dataPath, 'must NOT have duplicate items');
+          return;
+        }
+      }
+    }
+  }
+}
+
+function validateTagValue(
+  schema: unknown,
+  value: unknown,
+  dataPath: string,
+  errors: TagValidationError[],
+): void {
+  if (!isRecord(schema)) {
+    addError(errors, dataPath, 'must match a supported tag schema');
+    return;
+  }
+
+  const validType = validateType(schema.type, value, dataPath, errors);
+  if (!validType) {
+    return;
+  }
+
+  validateEnum(schema, value, dataPath, errors);
+  validateNumberConstraints(schema, value, dataPath, errors);
+  validateStringConstraints(schema, value, dataPath, errors);
+  validateArrayConstraints(schema, value, dataPath, errors);
+
+  if (Array.isArray(value) && isRecord(schema.items)) {
+    value.forEach((item, index) => validateTagValue(schema.items, item, appendPath(dataPath, index), errors));
+  }
+
+  if (Array.isArray(value) && isRecord(schema.contains)) {
+    validateContains(schema, value, dataPath, errors);
+  }
+}
+
+function validateContains(
+  schema: Record<string, unknown>,
+  value: unknown[],
+  dataPath: string,
+  errors: TagValidationError[],
+): void {
+  const minimumCount = Number.isInteger(schema.minContains) ? schema.minContains as number : 1;
+  const maximumCount = Number.isInteger(schema.maxContains) ? schema.maxContains as number : undefined;
+  const validItemCount = value.filter(item => {
+    const itemErrors: TagValidationError[] = [];
+    validateTagValue(schema.contains, item, dataPath, itemErrors);
+    return itemErrors.length === 0;
+  }).length;
+
+  if (validItemCount < minimumCount || (maximumCount !== undefined && validItemCount > maximumCount)) {
+    const message = maximumCount === undefined
+      ? `must contain at least ${minimumCount} valid item(s)`
+      : `must contain at least ${minimumCount} and no more than ${maximumCount} valid item(s)`;
+    addError(errors, dataPath, message);
+  }
+}
+
+/**
+ * Validates a record's `descriptor.tags` against a protocol rule set `$tags` definition.
+ */
+export function validateProtocolTags(
+  tagsDefinition: ProtocolTagsDefinition,
+  tags: Record<string, unknown>,
+  dataVar: string,
+): string | undefined {
+  const errors: TagValidationError[] = [];
+  const tagSchemas = getTagSchemas(tagsDefinition);
+  const requiredTags = Array.isArray(tagsDefinition.$requiredTags) ? tagsDefinition.$requiredTags : [];
+
+  for (const requiredTag of requiredTags) {
+    if (!hasOwnProperty(tags, requiredTag)) {
+      addError(errors, '', `must have required property '${requiredTag}'`);
+    }
+  }
+
+  if (tagsDefinition.$allowUndefinedTags !== true) {
+    for (const tag of Object.keys(tags)) {
+      if (tagSchemas[tag] === undefined) {
+        addError(errors, '', 'must NOT have additional properties');
+      }
+    }
+  }
+
+  for (const [ tag, schema ] of Object.entries(tagSchemas)) {
+    if (hasOwnProperty(tags, tag)) {
+      validateTagValue(schema, tags[tag], appendPath('', tag), errors);
+    }
+  }
+
+  return formatTagValidationErrors(errors, dataVar);
+}
+
+function formatTagValidationErrors(errors: TagValidationError[], dataVar: string): string | undefined {
+  if (errors.length === 0) {
+    return undefined;
+  }
+
+  return errors
+    .map(error => `${dataVar}${error.instancePath} ${error.message}`)
+    .join(', ');
+}