@enbox/dwn-sdk-js 0.4.1 → 0.4.3

package/dist/types/src/utils/protocol-tags.d.ts

@@ -0,0 +1,15 @@
+import type { ProtocolTagsDefinition } from '../types/protocols-types.js';
+/**
+ * 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 declare function validateProtocolTagSchemaDefinition(schema: unknown, dataVar: string): string | undefined;
+/**
+ * Validates a record's `descriptor.tags` against a protocol rule set `$tags` definition.
+ */
+export declare function validateProtocolTags(tagsDefinition: ProtocolTagsDefinition, tags: Record<string, unknown>, dataVar: string): string | undefined;
+//# sourceMappingURL=protocol-tags.d.ts.map

package/dist/types/src/utils/protocol-tags.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"protocol-tags.d.ts","sourceRoot":"","sources":["../../../../src/utils/protocol-tags.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAqB,sBAAsB,EAAE,MAAM,6BAA6B,CAAC;AAuH7F;;;;;;;GAOG;AACH,wBAAgB,mCAAmC,CACjD,MAAM,EAAE,OAAO,EACf,OAAO,EAAE,MAAM,GACd,MAAM,GAAG,SAAS,CAgBpB;AAgLD;;GAEG;AACH,wBAAgB,oBAAoB,CAClC,cAAc,EAAE,sBAAsB,EACtC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC7B,OAAO,EAAE,MAAM,GACd,MAAM,GAAG,SAAS,CA0BpB"}

package/dist/types/tests/features/author-delegated-grant.spec.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"author-delegated-grant.spec.d.ts","sourceRoot":"","sources":["../../../../tests/features/author-delegated-grant.spec.ts"],"names":[],"mappings":"AA2BA,wBAAgB,wBAAwB,IAAI,IAAI,CA0iD/C"}
+{"version":3,"file":"author-delegated-grant.spec.d.ts","sourceRoot":"","sources":["../../../../tests/features/author-delegated-grant.spec.ts"],"names":[],"mappings":"AA2BA,wBAAgB,wBAAwB,IAAI,IAAI,CAurD/C"}

package/dist/types/tests/handlers/records-read.spec.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"records-read.spec.d.ts","sourceRoot":"","sources":["../../../../tests/handlers/records-read.spec.ts"],"names":[],"mappings":"AAkCA,wBAAgB,sBAAsB,IAAI,IAAI,CAqnE7C"}
+{"version":3,"file":"records-read.spec.d.ts","sourceRoot":"","sources":["../../../../tests/handlers/records-read.spec.ts"],"names":[],"mappings":"AAkCA,wBAAgB,sBAAsB,IAAI,IAAI,CA2nE7C"}

package/dist/types/tests/utils/protocol-tags.spec.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=protocol-tags.spec.d.ts.map

package/dist/types/tests/utils/protocol-tags.spec.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"protocol-tags.spec.d.ts","sourceRoot":"","sources":["../../../../tests/utils/protocol-tags.spec.ts"],"names":[],"mappings":""}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@enbox/dwn-sdk-js",
-  "version": "0.4.1",
+  "version": "0.4.3",
   "description": "A reference implementation of https://identity.foundation/decentralized-web-node/spec/",
   "repository": {
     "type": "git",

package/src/core/grant-authorization.ts

@@ -119,7 +119,8 @@ export class GrantAuthorization {
    * Verify that the `interface` and `method` grant scopes match the incoming message.
    *
    * For the Messages interface, a `Read` scope is treated as a unified scope that also authorizes
-   * `Query`, `Subscribe`, and `Sync` operations.
+   * `Query` and `Subscribe` operations. For Records, `Read` is likewise the canonical read-like
+   * scope and authorizes `Read`, `Query`, `Subscribe`, and `Count` operations.
    *
    * @throws {DwnError} if the `interface` and `method` of the incoming message do not match the scope of the permission grant.
    */
@@ -155,6 +156,22 @@ export class GrantAuthorization {
       return;
     }
 
+    // Records.Read is the only valid read-like Records scope and covers Read, Query,
+    // Subscribe, and Count operations. Reject malformed Records Query/Subscribe/Count
+    // grants instead of treating them as compatible with the canonical Read scope.
+    if (dwnInterface === DwnInterfaceName.Records) {
+      const readLikeMethods = [DwnMethodName.Read, DwnMethodName.Query, DwnMethodName.Subscribe, DwnMethodName.Count];
+      if (readLikeMethods.includes(dwnMethod as DwnMethodName)) {
+        if (permissionGrant.scope.method !== DwnMethodName.Read) {
+          throw new DwnError(
+            DwnErrorCode.GrantAuthorizationMethodMismatch,
+            `records read-like permission grant must have method 'Read', got '${permissionGrant.scope.method}' for grant ${permissionGrant.id}`
+          );
+        }
+        return;
+      }
+    }
+
     if (dwnMethod !== permissionGrant.scope.method) {
       throw new DwnError(
         DwnErrorCode.GrantAuthorizationMethodMismatch,

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

@@ -5,8 +5,8 @@ import type { ProtocolDefinition, ProtocolRuleSet, ProtocolType, ProtocolTypes }
 
 import { ProtocolRecordLimitStrategy } from '../types/protocols-types.js';
 
-import Ajv from 'ajv/dist/2020.js';
 import { Records } from '../utils/records.js';
+import { validateProtocolTags } from '../utils/protocol-tags.js';
 import { DwnError, DwnErrorCode } from './dwn-error.js';
 import { getTypeName, parseCrossProtocolRef } from '../utils/protocols.js';
 
@@ -282,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(
@@ -291,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}`);
     }
   }

package/src/interfaces/protocols-configure.ts

@@ -7,12 +7,12 @@ import type {
 } from '../types/protocols-types.js';
 
 import { AbstractMessage } from '../core/abstract-message.js';
-import Ajv from 'ajv/dist/2020.js';
 import { DwnConstant } from '../core/dwn-constant.js';
 import { Message } from '../core/message.js';
 import { PermissionGrant } from '../protocols/permission-grant.js';
 import { ProtocolsGrantAuthorization } from '../core/protocols-grant-authorization.js';
 import { Time } from '../utils/time.js';
+import { validateProtocolTagSchemaDefinition } from '../utils/protocol-tags.js';
 import { DwnError, DwnErrorCode } from '../core/dwn-error.js';
 import { DwnInterfaceName, DwnMethodName } from '../enums/dwn-interface-method.js';
 import { isCrossProtocolRef, parseCrossProtocolRef } from '../utils/protocols.js';
@@ -265,16 +265,18 @@ export class ProtocolsConfigure extends AbstractMessage<ProtocolsConfigureMessag
       }
     }
 
-    if (ruleSet.$tags) {
-      const ajv = new Ajv.default();
+    if (ruleSet.$tags !== undefined) {
       const { $allowUndefinedTags, $requiredTags, ...tagProperties } = ruleSet.$tags;
 
-      // we validate each tag's expected schema to ensure it is a valid JSON schema
+      // validate each tag's schema against the DWN-supported tag schema subset
       for (const tag in tagProperties) {
         const tagSchemaDefinition = tagProperties[tag];
+        const schemaError = validateProtocolTagSchemaDefinition(
+          tagSchemaDefinition,
+          `${ruleSetProtocolPath}/$tags/${tag}`,
+        );
 
-        if (!ajv.validateSchema(tagSchemaDefinition as Record<string, unknown>)) {
-          const schemaError = ajv.errorsText(ajv.errors, { dataVar: `${ruleSetProtocolPath}/$tags/${tag}` });
+        if (schemaError !== undefined) {
           throw new DwnError(DwnErrorCode.ProtocolsConfigureInvalidTagSchema, `tags schema validation error: ${schemaError}`);
         }
       }

package/src/types/permission-types.ts

@@ -104,10 +104,13 @@ export type MessagesPermissionScope = {
 
 /**
  * The data model for a permission scope that is specific to the Records interface.
+ *
+ * `Read` is the only valid read-like Records permission scope and authorizes
+ * `RecordsRead`, `RecordsQuery`, `RecordsSubscribe`, and `RecordsCount` operations.
  */
 export type RecordsPermissionScope = {
   interface: DwnInterfaceName.Records;
-  method: DwnMethodName.Count | DwnMethodName.Read | DwnMethodName.Write | DwnMethodName.Query | DwnMethodName.Subscribe | DwnMethodName.Delete;
+  method: DwnMethodName.Read | DwnMethodName.Write | DwnMethodName.Delete;
   protocol: string;
   /** May only be present when `protocol` is defined and `protocolPath` is undefined */
   contextId?: 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(', ');
+}