@enbox/dwn-sdk-js 0.0.1

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

@@ -0,0 +1,88 @@
+import type { MessageStore } from '../types/message-store.js';
+import type { PermissionGrant } from '../protocols/permission-grant.js';
+import type { ProtocolPermissionScope } from '../types/permission-types.js';
+import type { ProtocolsConfigureMessage, ProtocolsQueryMessage } from '../types/protocols-types.js';
+
+import { GrantAuthorization } from './grant-authorization.js';
+import { DwnError, DwnErrorCode } from './dwn-error.js';
+
+export class ProtocolsGrantAuthorization {
+  /**
+   * Authorizes the given ProtocolsConfigure in the scope of the DID given.
+   */
+  public static async authorizeConfigure(input: {
+    protocolsConfigureMessage: ProtocolsConfigureMessage,
+    expectedGrantor: string,
+    expectedGrantee: string,
+    permissionGrant: PermissionGrant,
+    messageStore: MessageStore,
+  }): Promise<void> {
+    const {
+      protocolsConfigureMessage, expectedGrantor, expectedGrantee, permissionGrant, messageStore
+    } = input;
+
+    await GrantAuthorization.performBaseValidation({
+      incomingMessage: protocolsConfigureMessage,
+      expectedGrantor,
+      expectedGrantee,
+      permissionGrant,
+      messageStore
+    });
+
+    ProtocolsGrantAuthorization.verifyScope(protocolsConfigureMessage, permissionGrant.scope as ProtocolPermissionScope);
+  }
+
+  /**
+   * Authorizes the scope of a permission grant for a ProtocolsQuery message.
+   * @param messageStore Used to check if the grant has been revoked.
+   */
+  public static async authorizeQuery(input: {
+    expectedGrantor: string,
+    expectedGrantee: string,
+    incomingMessage: ProtocolsQueryMessage;
+    permissionGrant: PermissionGrant;
+    messageStore: MessageStore;
+  }): Promise<void> {
+    const { expectedGrantee, expectedGrantor, incomingMessage, permissionGrant, messageStore } = input;
+
+    await GrantAuthorization.performBaseValidation({
+      incomingMessage: incomingMessage,
+      expectedGrantor,
+      expectedGrantee,
+      permissionGrant,
+      messageStore
+    });
+
+    // If the grant specifies a protocol, the query must specify the same protocol.
+    const permissionScope = permissionGrant.scope as ProtocolPermissionScope;
+    const protocolInGrant = permissionScope.protocol;
+    const protocolInMessage = incomingMessage.descriptor.filter?.protocol;
+    if (protocolInGrant !== undefined && protocolInMessage !== protocolInGrant) {
+      throw new DwnError(
+        DwnErrorCode.ProtocolsGrantAuthorizationQueryProtocolScopeMismatch,
+        `Grant protocol scope ${protocolInGrant} does not match protocol in message ${protocolInMessage}`
+      );
+    }
+  }
+
+  /**
+   * Verifies a ProtocolsConfigure against the scope of the given grant.
+   */
+  private static verifyScope(
+    protocolsConfigureMessage: ProtocolsConfigureMessage,
+    grantScope: ProtocolPermissionScope
+  ): void {
+
+    // if the grant scope does not specify a protocol, then it is am unrestricted grant
+    if (grantScope.protocol === undefined) {
+      return;
+    }
+
+    if (grantScope.protocol !== protocolsConfigureMessage.descriptor.definition.protocol) {
+      throw new DwnError(
+        DwnErrorCode.ProtocolsGrantAuthorizationScopeProtocolMismatch,
+        `Grant scope specifies different protocol than what appears in the configure message.`
+      );
+    }
+  }
+}

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

@@ -0,0 +1,197 @@
+import type { MessageStore } from '../types/message-store.js';
+import type { PermissionGrant } from '../protocols/permission-grant.js';
+import type { PermissionConditions, RecordsPermissionScope } from '../types/permission-types.js';
+import type { RecordsDeleteMessage, RecordsQueryMessage, RecordsReadMessage, RecordsSubscribeMessage, RecordsWriteMessage } from '../types/records-types.js';
+
+import { GrantAuthorization } from './grant-authorization.js';
+import { PermissionConditionPublication } from '../types/permission-types.js';
+import { DwnError, DwnErrorCode } from './dwn-error.js';
+
+export class RecordsGrantAuthorization {
+  /**
+   * Authorizes the given RecordsWrite in the scope of the DID given.
+   */
+  public static async authorizeWrite(input: {
+    recordsWriteMessage: RecordsWriteMessage,
+    expectedGrantor: string,
+    expectedGrantee: string,
+    permissionGrant: PermissionGrant,
+    messageStore: MessageStore,
+  }): Promise<void> {
+    const {
+      recordsWriteMessage, expectedGrantor, expectedGrantee, permissionGrant, messageStore
+    } = input;
+
+    await GrantAuthorization.performBaseValidation({
+      incomingMessage: recordsWriteMessage,
+      expectedGrantor,
+      expectedGrantee,
+      permissionGrant,
+      messageStore
+    });
+
+    // NOTE: validated the invoked permission is for Records in GrantAuthorization.performBaseValidation()
+    RecordsGrantAuthorization.verifyScope(recordsWriteMessage, permissionGrant.scope as RecordsPermissionScope);
+
+    RecordsGrantAuthorization.verifyConditions(recordsWriteMessage, permissionGrant.conditions);
+  }
+
+  /**
+   * Authorizes a RecordsReadMessage using the given permission grant.
+   * @param messageStore Used to check if the given grant has been revoked.
+   */
+  public static async authorizeRead(input: {
+    recordsReadMessage: RecordsReadMessage,
+    recordsWriteMessageToBeRead: RecordsWriteMessage,
+    expectedGrantor: string,
+    expectedGrantee: string,
+    permissionGrant: PermissionGrant,
+    messageStore: MessageStore,
+  }): Promise<void> {
+    const {
+      recordsReadMessage, recordsWriteMessageToBeRead, expectedGrantor, expectedGrantee, permissionGrant, messageStore
+    } = input;
+
+    await GrantAuthorization.performBaseValidation({
+      incomingMessage: recordsReadMessage,
+      expectedGrantor,
+      expectedGrantee,
+      permissionGrant,
+      messageStore
+    });
+
+    // NOTE: validated the invoked permission is for Records in GrantAuthorization.performBaseValidation()
+    RecordsGrantAuthorization.verifyScope(recordsWriteMessageToBeRead, permissionGrant.scope as RecordsPermissionScope);
+  }
+
+  /**
+   * Authorizes the scope of a permission grant for RecordsQuery or RecordsSubscribe.
+   * @param messageStore Used to check if the grant has been revoked.
+   */
+  public static async authorizeQueryOrSubscribe(input: {
+    incomingMessage: RecordsQueryMessage | RecordsSubscribeMessage,
+    expectedGrantor: string,
+    expectedGrantee: string,
+    permissionGrant: PermissionGrant,
+    messageStore: MessageStore,
+  }): Promise<void> {
+    const {
+      incomingMessage, expectedGrantor, expectedGrantee, permissionGrant, messageStore
+    } = input;
+
+    await GrantAuthorization.performBaseValidation({
+      incomingMessage,
+      expectedGrantor,
+      expectedGrantee,
+      permissionGrant,
+      messageStore
+    });
+
+    // If the grant specifies a protocol, the subscribe or query must specify the same 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) {
+      throw new DwnError(
+        DwnErrorCode.RecordsGrantAuthorizationQueryOrSubscribeProtocolScopeMismatch,
+        `Grant protocol scope ${protocolInGrant} does not match protocol in message ${protocolInMessage}`
+      );
+    }
+  }
+
+  /**
+   * Authorizes the scope of a permission grant for RecordsDelete.
+   * @param messageStore Used to check if the grant has been revoked.
+   */
+  public static async authorizeDelete(input: {
+    recordsDeleteMessage: RecordsDeleteMessage,
+    recordsWriteToDelete: RecordsWriteMessage,
+    expectedGrantor: string,
+    expectedGrantee: string,
+    permissionGrant: PermissionGrant,
+    messageStore: MessageStore,
+  }): Promise<void> {
+    const {
+      recordsDeleteMessage, recordsWriteToDelete, expectedGrantor, expectedGrantee, permissionGrant, messageStore
+    } = input;
+
+    await GrantAuthorization.performBaseValidation({
+      incomingMessage: recordsDeleteMessage,
+      expectedGrantor,
+      expectedGrantee,
+      permissionGrant,
+      messageStore
+    });
+
+    // If the grant specifies a protocol, the delete must be deleting a record with the same protocol.
+    // 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) {
+      throw new DwnError(
+        DwnErrorCode.RecordsGrantAuthorizationDeleteProtocolScopeMismatch,
+        `Grant protocol scope ${protocolInGrant} does not match protocol in record to delete ${protocolOfRecordToDelete}`
+      );
+    }
+  }
+
+  /**
+   * Verifies a record against the scope of the given grant.
+   */
+  private static verifyScope(
+    recordsWriteMessage: RecordsWriteMessage,
+    grantScope: RecordsPermissionScope
+  ): void {
+
+    // The record's protocol must match the protocol specified in the record
+    if (grantScope.protocol !== recordsWriteMessage.descriptor.protocol) {
+      throw new DwnError(
+        DwnErrorCode.RecordsGrantAuthorizationScopeProtocolMismatch,
+        `Grant scope specifies different protocol than what appears in the record`
+      );
+    }
+
+    // If grant specifies a contextId, check that record falls under that contextId
+    if (grantScope.contextId !== undefined) {
+      if (recordsWriteMessage.contextId === undefined || !recordsWriteMessage.contextId.startsWith(grantScope.contextId)) {
+        throw new DwnError(
+          DwnErrorCode.RecordsGrantAuthorizationScopeContextIdMismatch,
+          `Grant scope specifies different contextId than what appears in the record`
+        );
+      }
+    }
+
+    // If grant specifies protocolPath, check that record is at that protocolPath
+    if (grantScope.protocolPath !== undefined && grantScope.protocolPath !== recordsWriteMessage.descriptor.protocolPath) {
+      throw new DwnError(
+        DwnErrorCode.RecordsGrantAuthorizationScopeProtocolPathMismatch,
+        `Grant scope specifies different protocolPath than what appears in the record`
+      );
+    }
+  }
+
+  /**
+   * Verifies grant `conditions`.
+   * Currently the only condition is `published` which only applies to RecordsWrites
+   */
+  private static verifyConditions(recordsWriteMessage: RecordsWriteMessage, conditions: PermissionConditions | undefined): void {
+
+    // If conditions require publication, RecordsWrite must have `published` === true
+    if (conditions?.publication === PermissionConditionPublication.Required && !recordsWriteMessage.descriptor.published) {
+      throw new DwnError(
+        DwnErrorCode.RecordsGrantAuthorizationConditionPublicationRequired,
+        'Permission grant requires message to be published'
+      );
+    }
+
+    // if conditions prohibit publication, RecordsWrite must have published === false or undefined
+    if (conditions?.publication === PermissionConditionPublication.Prohibited && recordsWriteMessage.descriptor.published) {
+      throw new DwnError(
+        DwnErrorCode.RecordsGrantAuthorizationConditionPublicationProhibited,
+        'Permission grant prohibits message from being published'
+      );
+    }
+  }
+}

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

@@ -0,0 +1,114 @@
+import type { StorageController } from '../store/storage-controller.js';
+import type { ManagedResumableTask, ResumableTaskStore } from '../types/resumable-task-store.js';
+
+export enum ResumableTaskName {
+  RecordsDelete = 'RecordsDelete',
+}
+
+export type ResumableTask = {
+  name: ResumableTaskName;
+  data: any;
+};
+
+
+export class ResumableTaskManager {
+
+  /**
+   * The frequency at which the automatic timeout extension is requested for a resumable task.
+   */
+  public static readonly timeoutExtensionFrequencyInSeconds = 30;
+
+  private resumableTaskBatchSize = 100;
+  private resumableTaskHandlers: { [key:string]: (taskData: any) => Promise<void> };
+
+  public constructor(private resumableTaskStore: ResumableTaskStore, storageController: StorageController) {
+    // assign resumable task handlers
+    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),
+    };
+  }
+
+  /**
+   * Runs a new resumable task.
+   */
+  public async run(task: ResumableTask): Promise<void> {
+    const timeoutInSeconds = ResumableTaskManager.timeoutExtensionFrequencyInSeconds * 2; // give ample time for extension to take place
+
+    // register the new resumable task before running it so that it can be resumed if it times out for any reason
+    const managedResumableTask = await this.resumableTaskStore.register(task, timeoutInSeconds);
+    await this.runWithAutomaticTimeoutExtension(managedResumableTask);
+  }
+
+  /**
+   * Runs a resumable task with automatic timeout extension.
+   * Deletes the task from the resumable task store once it is completed.
+   */
+  private async runWithAutomaticTimeoutExtension(managedTask: ManagedResumableTask): Promise<void> {
+    const timeoutInSeconds = ResumableTaskManager.timeoutExtensionFrequencyInSeconds * 2; // give ample time for extension to take place
+
+    let timer!: ReturnType<typeof setInterval>;
+    try {
+      // start a timer loop to keep extending the timeout of the task until it is completed
+      timer = setInterval(() => {
+        this.resumableTaskStore.extend(managedTask.id, timeoutInSeconds);
+      }, ResumableTaskManager.timeoutExtensionFrequencyInSeconds * 1000);
+
+      const handler = this.resumableTaskHandlers[managedTask.task.name];
+      await handler(managedTask.task.data);
+      await this.resumableTaskStore.delete(managedTask.id);
+    } finally {
+      ResumableTaskManager.clearTimeoutExtensionTimer(timer);
+    }
+  }
+
+  /**
+   * Removes the specified timeout extension loop timer.
+   * NOTE: created mainly for testing purposes so we can spy on this specific method without needing to filter out other `clearInterval` calls.
+   * NOTE: using `ReturnType` utility type to avoid using node.js specific type, because `setInterval` returns a `number` in browser environments.
+   */
+  public static clearTimeoutExtensionTimer(timer: ReturnType<typeof setInterval>): void {
+    clearInterval(timer);
+  }
+
+  /**
+   * Resumes the execution of resumable tasks until all are completed successfully.
+   */
+  public async resumeTasksAndWaitForCompletion(): Promise<void> {
+    while (true) {
+      const resumableTasks = await this.resumableTaskStore.grab(this.resumableTaskBatchSize);
+
+      if (resumableTasks === undefined || resumableTasks.length === 0) {
+        break;
+      }
+
+      // Handle this batch of tasks before grabbing the next batch.
+      await this.retryTasksUntilCompletion(resumableTasks);
+    }
+  }
+
+  /**
+   * Repeatedly retry the given tasks until all are completed successfully.
+   */
+  private async retryTasksUntilCompletion(resumableTasks: ManagedResumableTask[]): Promise<void> {
+
+    let managedTasks = resumableTasks;
+    while (managedTasks.length > 0) {
+      const managedTasksCopy = managedTasks;
+      managedTasks = [];
+
+      const allTaskPromises = managedTasksCopy.map(async (managedTask) => {
+        try {
+          await this.runWithAutomaticTimeoutExtension(managedTask);
+        } catch (error) {
+          console.error('Error while running resumable task:', error);
+          console.error('Resumable task:', resumableTasks);
+          managedTasks.push(managedTask);
+        }
+      });
+
+      await Promise.all(allTaskPromises);
+    }
+  }
+}

package/src/core/tenant-gate.ts

@@ -0,0 +1,33 @@
+/**
+ * The result of the isActiveTenant() call.
+ */
+export type ActiveTenantCheckResult = {
+  /**
+   * `true` if the given DID is an active tenant of the DWN; `false` otherwise.
+   */
+  isActiveTenant: boolean;
+
+  /**
+   * An optional detail message if the given DID is not an active tenant of the DWN.
+   */
+  detail?: string;
+};
+
+/**
+ * An interface that gates tenant access to the DWN.
+ */
+export interface TenantGate {
+  /**
+   * @returns `true` if the given DID is an active tenant of the DWN; `false` otherwise
+   */
+  isActiveTenant(did: string): Promise<ActiveTenantCheckResult>;
+}
+
+/**
+ * A tenant gate that treats every DID as an active tenant.
+ */
+export class AllowAllTenantGate implements TenantGate {
+  public async isActiveTenant(_did: string): Promise<ActiveTenantCheckResult> {
+    return { isActiveTenant: true };
+  }
+}