@enbox/dwn-server 0.0.1

package/src/registration/proof-of-work-manager.ts

@@ -0,0 +1,317 @@
+import { DwnServerError, DwnServerErrorCode } from "../dwn-error.js";
+import type { ProofOfWorkChallengeModel } from "./proof-of-work-types.js";
+import { ProofOfWork } from "./proof-of-work.js";
+
+/**
+ * Manages proof-of-work challenge difficulty and lifecycle based on solve rate.
+ * Can have multiple instances each having their own desired solve rate and difficulty.
+ */
+export class ProofOfWorkManager {
+  // Takes from seconds to ~1 minute to solve on an M1 MacBook.
+  public static readonly defaultMaximumAllowedHashValue = '000000FFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFF';
+
+  // Challenge nonces that can be used for proof-of-work.
+  private challengeNonces: {
+    previousChallengeNonce?: string,
+    currentChallengeNonce: string,
+    nextChallengeNonce?: string
+  };
+
+  // There is opportunity to improve implementation here.
+  // TODO: https://github.com/TBD54566975/dwn-server/issues/101
+  private proofOfWorkOfLastMinute: Map<string, number> = new Map(); // proofOfWorkId -> timestamp of proof-of-work
+
+  // Seed to generate the challenge nonce from, this allows all DWN instances in a cluster to generate the same challenge.
+  private challengeSeed?: string;
+  private difficultyIncreaseMultiplier: number;
+  private currentMaximumAllowedHashValueAsBigInt: bigint;
+  private initialMaximumAllowedHashValueAsBigInt: bigint;
+  private desiredSolveCountPerMinute: number;
+
+  /**
+   * How often the challenge nonce is refreshed.
+   */
+  public challengeRefreshFrequencyInSeconds: number;
+
+  /**
+   * How often the difficulty is reevaluated.
+   */
+  public difficultyReevaluationFrequencyInSeconds: number;
+
+  /**
+   * The current maximum allowed hash value.
+   */
+  public get currentMaximumAllowedHashValue(): bigint {
+    return this.currentMaximumAllowedHashValueAsBigInt;
+  }
+
+  /**
+   * The current proof-of-work solve rate.
+   */
+  public get currentSolveCountPerMinute(): number {
+    return this.proofOfWorkOfLastMinute.size;
+  }
+
+  private constructor (input: {
+    desiredSolveCountPerMinute: number,
+    initialMaximumAllowedHashValue: string,
+    difficultyIncreaseMultiplier: number,
+    challengeSeed?: string,
+    challengeRefreshFrequencyInSeconds: number,
+    difficultyReevaluationFrequencyInSeconds: number
+  }) {
+    const { desiredSolveCountPerMinute, initialMaximumAllowedHashValue } = input;
+
+    this.challengeSeed = input.challengeSeed;
+    this.challengeNonces = { currentChallengeNonce: ProofOfWork.generateNonce() };
+    this.currentMaximumAllowedHashValueAsBigInt = BigInt(`0x${initialMaximumAllowedHashValue}`);
+    this.initialMaximumAllowedHashValueAsBigInt = BigInt(`0x${initialMaximumAllowedHashValue}`);
+    this.desiredSolveCountPerMinute = desiredSolveCountPerMinute;
+    this.difficultyIncreaseMultiplier = input.difficultyIncreaseMultiplier;
+    this.challengeRefreshFrequencyInSeconds = input.challengeRefreshFrequencyInSeconds;
+    this.difficultyReevaluationFrequencyInSeconds = input.difficultyReevaluationFrequencyInSeconds;
+  }
+
+  /**
+   * Creates a new ProofOfWorkManager instance.
+   * @param input.difficultyIncreaseMultiplier How fast to increase difficulty when solve rate is higher than desired. Must be >= 1.
+   *   Defaults to 1 which means if the solve rate is 2x the desired solve rate, the difficulty will increase by 2x.
+   *   If set to 2, it means if the solve rate is 2x the desired solve rate, the difficulty will increase by 4x.
+   * @param input.challengeRefreshFrequencyInSeconds How often the challenge nonce is refreshed. Defaults to 10 minutes.
+   * @param input.difficultyReevaluationFrequencyInSeconds How often the difficulty is reevaluated. Defaults to 10 seconds.
+   */
+  public static async create(input: {
+    desiredSolveCountPerMinute: number,
+    autoStart: boolean,
+    initialMaximumAllowedHashValue?: string,
+    difficultyIncreaseMultiplier?: number,
+    challengeSeed?: string,
+    challengeRefreshFrequencyInSeconds?: number,
+    difficultyReevaluationFrequencyInSeconds?: number
+  }): Promise<ProofOfWorkManager> {
+    const { desiredSolveCountPerMinute } = input;
+
+    const initialMaximumAllowedHashValue = input.initialMaximumAllowedHashValue ?? ProofOfWorkManager.defaultMaximumAllowedHashValue;
+    const difficultyIncreaseMultiplier = input.difficultyIncreaseMultiplier ?? 1; // 1x default
+    const challengeRefreshFrequencyInSeconds = input.challengeRefreshFrequencyInSeconds ?? 10 * 60; // 10 minutes default
+    const difficultyReevaluationFrequencyInSeconds = input.difficultyReevaluationFrequencyInSeconds ?? 10; // 10 seconds default
+
+    const proofOfWorkManager = new ProofOfWorkManager({
+      desiredSolveCountPerMinute,
+      initialMaximumAllowedHashValue,
+      difficultyIncreaseMultiplier,
+      challengeSeed: input.challengeSeed,
+      challengeRefreshFrequencyInSeconds,
+      difficultyReevaluationFrequencyInSeconds
+    });
+
+    if (input.autoStart) {
+      proofOfWorkManager.start();
+    }
+
+    return proofOfWorkManager;
+  }
+
+  /**
+   * Starts the proof-of-work manager by starting the challenge nonce and difficulty refresh timers.
+   */
+  public start(): void {
+    this.periodicallyRefreshChallengeNonce();
+    this.periodicallyRefreshProofOfWorkDifficulty();
+  }
+
+  public getProofOfWorkChallenge(): ProofOfWorkChallengeModel {
+    return {
+      challengeNonce: this.challengeNonces.currentChallengeNonce,
+      maximumAllowedHashValue: ProofOfWorkManager.bigIntToHexString(this.currentMaximumAllowedHashValue),
+    };
+  }
+
+  /**
+   * Verifies the proof-of-work meets the difficulty requirement.
+   */
+  public async verifyProofOfWork(proofOfWork: {
+    challengeNonce: string;
+    responseNonce: string;
+    requestData: string;
+  }): Promise<void> {
+    const { challengeNonce, responseNonce, requestData } = proofOfWork;
+
+    if (this.proofOfWorkOfLastMinute.has(responseNonce)) {
+      throw new DwnServerError(
+        DwnServerErrorCode.ProofOfWorkManagerResponseNonceReused,
+        `Not allowed to reused response nonce: ${responseNonce}.`
+      );
+    }
+
+    // Verify response nonce is a HEX string that represents a 256 bit value.
+    if (!ProofOfWorkManager.isHexString(responseNonce) || responseNonce.length !== 64) {
+      throw new DwnServerError(
+        DwnServerErrorCode.ProofOfWorkManagerInvalidResponseNonceFormat,
+        `Response nonce not a HEX string representing a 256 bit value: ${responseNonce}.`
+      );
+    }
+
+    // Verify challenge nonce is valid.
+    const { previousChallengeNonce, currentChallengeNonce, nextChallengeNonce } = this.challengeNonces;
+    const acceptableChallengeNonces = [previousChallengeNonce, currentChallengeNonce, nextChallengeNonce].filter(nonce => nonce !== undefined && nonce !== '');
+    if (!acceptableChallengeNonces.includes(challengeNonce)) {
+      throw new DwnServerError(
+        DwnServerErrorCode.ProofOfWorkManagerInvalidChallengeNonce,
+        `Unknown or expired challenge nonce: ${challengeNonce}.`
+      );
+    }
+
+    const maximumAllowedHashValue = this.currentMaximumAllowedHashValue;
+    ProofOfWork.verifyResponseNonce({ challengeNonce, responseNonce, requestData, maximumAllowedHashValue });
+
+    this.recordProofOfWork(responseNonce);
+  }
+
+  /**
+   * Records a successful proof-of-work.
+   * Exposed for testing purposes.
+   */
+  public async recordProofOfWork(proofOfWorkId: string): Promise<void> {
+    this.proofOfWorkOfLastMinute.set(proofOfWorkId, Date.now());
+  }
+
+  private periodicallyRefreshChallengeNonce (): void {
+    try {
+      this.refreshChallengeNonce();
+    } catch (error) {
+      console.error(`Encountered error while refreshing challenge nonce: ${error}`);
+    } finally {
+      setTimeout(async () => this.periodicallyRefreshChallengeNonce(), this.challengeRefreshFrequencyInSeconds * 1000);
+    }
+  }
+
+  private periodicallyRefreshProofOfWorkDifficulty (): void {
+    try {
+      this.refreshMaximumAllowedHashValue();
+    } catch (error) {
+      console.error(`Encountered error while updating proof of work difficulty: ${error}`);
+    } finally {
+      setTimeout(async () => this.periodicallyRefreshProofOfWorkDifficulty(), this.difficultyReevaluationFrequencyInSeconds * 1000);
+    }
+  }
+
+  private removeProofOfWorkOlderThanOneMinute (): void {
+    const oneMinuteAgo = Date.now() - 60 * 1000;
+    for (const proofOfWorkId of this.proofOfWorkOfLastMinute.keys()) {
+      if (this.proofOfWorkOfLastMinute.get(proofOfWorkId) < oneMinuteAgo) {
+        this.proofOfWorkOfLastMinute.delete(proofOfWorkId);
+      }
+    }
+  }
+
+  private refreshChallengeNonce(): void {
+    // If challenge seed is supplied, use it to deterministically generate the challenge nonces.
+    if (this.challengeSeed !== undefined) {
+      const currentRefreshIntervalId = Math.floor(Date.now() / (this.challengeRefreshFrequencyInSeconds * 1000));
+      const previousRefreshIntervalId = currentRefreshIntervalId - 1;
+      const nextRefreshIntervalId = currentRefreshIntervalId + 1;
+
+      const previousChallengeNonce = ProofOfWork.hashAsHexString([this.challengeSeed, previousRefreshIntervalId.toString(), this.challengeSeed]);
+      const currentChallengeNonce = ProofOfWork.hashAsHexString([this.challengeSeed, currentRefreshIntervalId.toString(), this.challengeSeed]);
+      const nextChallengeNonce = ProofOfWork.hashAsHexString([this.challengeSeed, nextRefreshIntervalId.toString(), this.challengeSeed]);
+
+      this.challengeNonces = { previousChallengeNonce, currentChallengeNonce, nextChallengeNonce };
+    } else {
+      const newChallengeNonce = ProofOfWork.generateNonce();
+
+      this.challengeNonces.previousChallengeNonce = this.challengeNonces.currentChallengeNonce;
+      this.challengeNonces.currentChallengeNonce = newChallengeNonce;
+    }
+  }
+
+  /**
+   * Refreshes the difficulty by changing the max hash value.
+   * The higher the number, the easier. Scale 1 (hardest) to 2^256 (easiest), represented in HEX.
+   * 
+   * If solve rate rate is higher than expected, the difficulty will increase rapidly.
+   * If solve rate is lower than expected, the difficulty will decrease gradually.
+   * The difficulty will never be lower than the initial difficulty.
+   */
+  private async refreshMaximumAllowedHashValue (): Promise<void> {
+    // Cleanup proof-of-work cache and update solve rate.
+    this.removeProofOfWorkOlderThanOneMinute();
+
+    const latestSolveCountPerMinute = this.proofOfWorkOfLastMinute.size;
+
+    // NOTE: bigint arithmetic does NOT work with decimals, so we work with "full numbers" by multiplying by a scale factor.
+    const scaleFactor = 1_000_000;
+    const difficultyEvaluationsPerMinute = 60000 / (this.difficultyReevaluationFrequencyInSeconds * 1000); // assumed to be >= 1;
+
+    // NOTE: easier difficulty is represented by a larger max allowed hash value
+    //       and harder difficulty is represented by a smaller max allowed hash value.
+    if (latestSolveCountPerMinute > this.desiredSolveCountPerMinute) {
+      // if solve rate is higher than desired, make difficulty harder by making the max allowed hash value smaller
+      
+      const currentSolveRateInFractionOfDesiredSolveRate = latestSolveCountPerMinute / this.desiredSolveCountPerMinute;
+      const newMaximumAllowedHashValueAsBigIntPriorToMultiplierAdjustment
+        = (this.currentMaximumAllowedHashValueAsBigInt * BigInt(scaleFactor)) / 
+          (BigInt(Math.floor(currentSolveRateInFractionOfDesiredSolveRate * this.difficultyIncreaseMultiplier * scaleFactor)));
+
+      const hashValueDecreaseAmountPriorToEvaluationFrequencyAdjustment
+        = (this.currentMaximumAllowedHashValueAsBigInt - newMaximumAllowedHashValueAsBigIntPriorToMultiplierAdjustment) *
+          (BigInt(Math.floor(this.difficultyIncreaseMultiplier * scaleFactor)) / BigInt(scaleFactor));
+          
+      // Adjustment based on the reevaluation frequency to provide more-or-less consistent behavior regardless of the reevaluation frequency.
+      const hashValueDecreaseAmount = hashValueDecreaseAmountPriorToEvaluationFrequencyAdjustment / BigInt(difficultyEvaluationsPerMinute);
+
+      this.currentMaximumAllowedHashValueAsBigInt -= hashValueDecreaseAmount;
+
+      // Resetting to allow hash increment to be recalculated when difficulty needs to be reduced (in `else` block below)
+      this.hashValueIncrementPerEvaluation = undefined;
+    } else {
+      // if solve rate is lower than desired, make difficulty easier by making the max allowed hash value larger
+
+      if (this.currentMaximumAllowedHashValueAsBigInt === this.initialMaximumAllowedHashValueAsBigInt) {
+        // if current difficulty is already at initial difficulty, nothing to do
+        return;
+      }
+
+      if (this.hashValueIncrementPerEvaluation === undefined) {
+        const backToInitialDifficultyInMinutes = 10;
+        const differenceBetweenInitialAndCurrentDifficulty
+          = this.initialMaximumAllowedHashValueAsBigInt - this.currentMaximumAllowedHashValueAsBigInt;
+        this.hashValueIncrementPerEvaluation
+          = differenceBetweenInitialAndCurrentDifficulty / BigInt(backToInitialDifficultyInMinutes * difficultyEvaluationsPerMinute);
+      }
+
+      // if newly calculated difficulty is lower than initial difficulty, just use the initial difficulty
+      const newMaximumAllowedHashValueAsBigInt = this.currentMaximumAllowedHashValueAsBigInt + this.hashValueIncrementPerEvaluation;
+      if (newMaximumAllowedHashValueAsBigInt >= this.initialMaximumAllowedHashValueAsBigInt) {
+        this.currentMaximumAllowedHashValueAsBigInt = this.initialMaximumAllowedHashValueAsBigInt;
+      } else {
+        this.currentMaximumAllowedHashValueAsBigInt = newMaximumAllowedHashValueAsBigInt;
+      }
+    }
+  }
+
+  /**
+   * Only used by refreshMaximumAllowedHashValue() to reduce the challenge difficulty gradually.
+   */
+  private hashValueIncrementPerEvaluation = BigInt(1);
+
+  /**
+   * Verifies that the supplied string is a HEX string.
+   */
+  public static isHexString(str: string): boolean {
+    const regexp = /^[0-9a-fA-F]+$/;
+    return regexp.test(str);
+  }
+
+  /**
+   * Converts a BigInt to a 256 bit HEX string with padded preceding zeros (64 characters).
+   */
+  private static bigIntToHexString (int: BigInt): string {
+    let hex = int.toString(16).toUpperCase();
+    const stringLength = hex.length;
+    for (let pad = stringLength; pad < 64; pad++) {
+      hex = '0' + hex;
+    }
+    return hex;
+  }
+}

package/src/registration/proof-of-work-types.ts

@@ -0,0 +1,7 @@
+/**
+ * Proof-of-work challenge model returned by the /registration/proof-of-work API.
+ */
+export type ProofOfWorkChallengeModel = {
+  challengeNonce: string;
+  maximumAllowedHashValue: string;
+};

package/src/registration/proof-of-work.ts

@@ -0,0 +1,100 @@
+import { createHash, randomBytes } from 'crypto';
+
+import { DwnServerError, DwnServerErrorCode } from '../dwn-error.js';
+
+/**
+ * Utility methods related to proof-of-work.
+ */
+export class ProofOfWork {
+  /**
+   * Computes the resulting hash of the given proof-of-work input.
+   */
+  public static computeHash(input: {
+    challengeNonce: string;
+    responseNonce: string;
+    requestData: string;
+  }): string {
+    const hashInput = [input.challengeNonce, input.responseNonce, input.requestData];
+    return this.hashAsHexString(hashInput);
+  }
+
+  /**
+   * Computes the hash of the given array of strings.
+   */
+  public static hashAsHexString(input: string[]): string {
+    const hash = createHash('sha256');
+    for (const item of input) {
+      hash.update(item);
+    }
+
+    return hash.digest('hex');
+  }
+
+  /**
+   * Verifies that the response nonce meets the proof-of-work difficulty requirement.
+   */
+  public static verifyResponseNonce(input: {
+    maximumAllowedHashValue: bigint;
+    challengeNonce: string;
+    responseNonce: string;
+    requestData: string;
+  }): void {
+    const computedHash = this.computeHash(input);
+    const computedHashAsBigInt = BigInt(`0x${computedHash}`);
+
+    if (computedHashAsBigInt > input.maximumAllowedHashValue) {
+      throw new DwnServerError(
+        DwnServerErrorCode.ProofOfWorkInsufficientSolutionNonce,
+        `Insufficient computed hash ${computedHashAsBigInt}, needs to be <= ${input.maximumAllowedHashValue}.`,
+      );
+    }
+  }
+
+  /**
+   * Finds a response nonce that qualifies the difficulty requirement for the given proof-of-work challenge and request data.
+   * NOTE: mainly for demonstrating the procedure to find a qualified response nonce.
+   * Will need to artificially introduce asynchrony to allow other tasks to run if this method is to be used in a real-world client.
+   */
+  public static findQualifiedResponseNonce(input: {
+    maximumAllowedHashValue: string;
+    challengeNonce: string;
+    requestData: string;
+  }): string {
+    const startTime = Date.now();
+
+    const { maximumAllowedHashValue, challengeNonce, requestData } = input;
+    const maximumAllowedHashValueAsBigInt = BigInt(`0x${maximumAllowedHashValue}`);
+
+    let iterations = 1;
+    let randomNonce;
+    let qualifiedSolutionNonceFound = false;
+    do {
+      randomNonce = this.generateNonce();
+      const computedHash = this.computeHash({
+        challengeNonce,
+        responseNonce: randomNonce,
+        requestData,
+      });
+      const computedHashAsBigInt = BigInt(`0x${computedHash}`);
+
+      qualifiedSolutionNonceFound = computedHashAsBigInt <= maximumAllowedHashValueAsBigInt;
+
+      iterations++;
+    } while (!qualifiedSolutionNonceFound);
+
+    // Log final/successful iteration.
+    console.log(
+      `iterations: ${iterations}, time lapsed: ${Date.now() - startTime} ms`,
+    );
+
+    return randomNonce;
+  }
+
+  /**
+   * Generates 32 random bytes expressed as a HEX string.
+   */
+  public static generateNonce(): string {
+    const hexString = randomBytes(32).toString('hex').toUpperCase();
+    return hexString;
+  }
+}

package/src/registration/registration-manager.ts

@@ -0,0 +1,153 @@
+import { ProofOfWorkManager } from "./proof-of-work-manager.js";
+import { ProofOfWork } from "./proof-of-work.js";
+import { RegistrationStore } from "./registration-store.js";
+import type { RegistrationData, RegistrationRequest } from "./registration-types.js";
+import type { ProofOfWorkChallengeModel } from "./proof-of-work-types.js";
+import { DwnServerError, DwnServerErrorCode } from "../dwn-error.js";
+import type { ActiveTenantCheckResult, TenantGate } from "@enbox/dwn-sdk-js";
+import { getDialectFromUrl } from "../storage.js";
+import { readFileSync } from "fs";
+
+/**
+ * The RegistrationManager is responsible for managing the registration of tenants.
+ * It handles tenant registration requests and provides the corresponding `TenantGate` implementation.
+ */
+export class RegistrationManager implements TenantGate {
+  private proofOfWorkManager: ProofOfWorkManager;
+  private registrationStore: RegistrationStore;
+
+  private termsOfServiceHash?: string;
+  private termsOfService?: string;
+
+  /**
+   * The terms-of-service.
+   */
+  public getTermsOfService(): string | undefined {
+    return this.termsOfService;
+  }
+
+  /**
+   * The terms-of-service hash. 
+   */
+  public getTermsOfServiceHash(): string | undefined {
+    return this.termsOfServiceHash;
+  }
+
+  /**
+   * Updates the terms-of-service. Exposed for testing purposes.
+   */
+  public updateTermsOfService(termsOfService: string): void {
+    this.termsOfServiceHash = ProofOfWork.hashAsHexString([termsOfService]);
+    this.termsOfService = termsOfService;
+  }
+
+  /**
+   * Creates a new RegistrationManager instance.
+   * @param input.registrationStoreUrl - The URL of the registration store.
+   * Set to `undefined` or empty string if tenant registration is not required (ie. DWN is open for all).
+   * 
+   */
+  public static async create(input: {
+    registrationStoreUrl?: string,
+    termsOfServiceFilePath?: string
+    proofOfWorkChallengeNonceSeed?: string,
+    proofOfWorkInitialMaximumAllowedHash?: string,
+  }): Promise<RegistrationManager> {
+    const { termsOfServiceFilePath, registrationStoreUrl } = input;
+
+    const registrationManager = new RegistrationManager();
+
+    // short-circuit if tenant registration is not required.
+    if (!registrationStoreUrl) {
+      return registrationManager;
+    }
+
+    // Initialize terms-of-service.
+    if (termsOfServiceFilePath !== undefined) {
+      const termsOfService = readFileSync(termsOfServiceFilePath).toString();
+      registrationManager.updateTermsOfService(termsOfService);
+    }
+
+    // Initialize and start ProofOfWorkManager.
+    registrationManager.proofOfWorkManager = await ProofOfWorkManager.create({
+      autoStart: true,
+      desiredSolveCountPerMinute: 10,
+      initialMaximumAllowedHashValue: input.proofOfWorkInitialMaximumAllowedHash,
+      challengeSeed: input.proofOfWorkChallengeNonceSeed,
+    });
+
+    // Initialize RegistrationStore.
+    const sqlDialect = getDialectFromUrl(new URL(registrationStoreUrl));
+    const registrationStore = await RegistrationStore.create(sqlDialect);
+    registrationManager.registrationStore = registrationStore;
+    
+    return registrationManager;
+  }
+
+  /**
+   * Gets the proof-of-work challenge.
+   */
+  public getProofOfWorkChallenge(): ProofOfWorkChallengeModel {
+    const proofOfWorkChallenge = this.proofOfWorkManager.getProofOfWorkChallenge();
+    return proofOfWorkChallenge;
+  }
+
+  /**
+   * Handles a registration request.
+   */
+  public async handleRegistrationRequest(registrationRequest: RegistrationRequest): Promise<void> {
+    // Ensure the supplied terms of service hash matches the one we require.
+    if (registrationRequest.registrationData.termsOfServiceHash !== this.termsOfServiceHash) {
+      throw new DwnServerError(DwnServerErrorCode.RegistrationManagerInvalidOrOutdatedTermsOfServiceHash,
+        `Expecting terms-of-service hash ${this.termsOfServiceHash}, but got ${registrationRequest.registrationData.termsOfServiceHash}.`
+      );
+    }
+
+    const { challengeNonce, responseNonce } = registrationRequest.proofOfWork;
+
+    await this.proofOfWorkManager.verifyProofOfWork({
+      challengeNonce,
+      responseNonce,
+      requestData: JSON.stringify(registrationRequest.registrationData),
+    });
+
+    // Store tenant registration data in database.
+    await this.recordTenantRegistration(registrationRequest.registrationData);
+  }
+
+  /**
+   * Records the given registration data in the database.
+   * Exposed as a public method for testing purposes.
+   */
+  public async recordTenantRegistration(registrationData: RegistrationData): Promise<void> {
+    await this.registrationStore.insertOrUpdateTenantRegistration(registrationData);
+  }
+
+  /**
+   * The TenantGate implementation.
+   */
+  public async isActiveTenant(tenant: string): Promise<ActiveTenantCheckResult> {
+    // If there is no registration store initialized, then DWN is open for all.
+    if (this.registrationStore === undefined) {
+      return { isActiveTenant: true };
+    }
+
+    const tenantRegistration = await this.registrationStore.getTenantRegistration(tenant);
+
+    if (tenantRegistration === undefined) {
+      return {
+        isActiveTenant: false,
+        detail: 'Not a registered tenant.'
+      };
+    }
+
+    if (tenantRegistration.termsOfServiceHash !== this.termsOfServiceHash) {
+      return {
+        isActiveTenant: false,
+        detail: 'Agreed terms-of-service is outdated.'
+      };
+    }
+
+    return { isActiveTenant: true }
+  }
+}

package/src/registration/registration-store.ts

@@ -0,0 +1,79 @@
+import { Kysely } from 'kysely';
+import type { RegistrationData } from './registration-types.js';
+import type { Dialect } from '@enbox/dwn-sql-store';
+
+/**
+ * The RegistrationStore is responsible for storing and retrieving tenant registration information.
+ */
+export class RegistrationStore {
+  private static readonly registeredTenantTableName = 'registeredTenants';
+
+  private db: Kysely<RegistrationDatabase>;
+
+  private constructor (sqlDialect: Dialect) {
+    this.db = new Kysely<RegistrationDatabase>({ dialect: sqlDialect });
+  }
+
+  /**
+   * Creates a new RegistrationStore instance.
+   */
+  public static async create(sqlDialect: Dialect): Promise<RegistrationStore> {
+    const proofOfWorkManager = new RegistrationStore(sqlDialect);
+
+    await proofOfWorkManager.initialize();
+
+    return proofOfWorkManager;
+  }
+
+  private async initialize(): Promise<void> {
+    await this.db.schema
+    .createTable(RegistrationStore.registeredTenantTableName)
+    .ifNotExists()
+    .addColumn('did', 'text', (column) => column.primaryKey())
+    .addColumn('termsOfServiceHash', 'text')
+    .execute();
+  }
+
+  /**
+   * Inserts or updates the tenant registration information.
+   */
+  public async insertOrUpdateTenantRegistration(registrationData: RegistrationData): Promise<void> {
+    await this.db
+      .insertInto(RegistrationStore.registeredTenantTableName)
+      .values(registrationData)
+      .onConflict((oc) =>
+        oc.column('did').doUpdateSet((eb) => ({
+          termsOfServiceHash: eb.ref('excluded.termsOfServiceHash'),
+        })),
+      )
+      // Executes the query. No error is thrown if the query doesn’t affect any rows (ie. if the insert or update didn’t change anything).
+      .executeTakeFirst();
+  }
+
+  /**
+   * Retrieves the tenant registration information.
+   */
+  public async getTenantRegistration(tenantDid: string): Promise<RegistrationData | undefined> {
+    const result = await this.db
+      .selectFrom(RegistrationStore.registeredTenantTableName)
+      .select('did')
+      .select('termsOfServiceHash')
+      .where('did', '=', tenantDid)
+      .execute();
+
+    if (result.length === 0) {
+      return undefined;
+    }
+
+    return result[0];
+  }
+}
+
+interface RegisteredTenants {
+  did: string;
+  termsOfServiceHash: string;
+}
+
+interface RegistrationDatabase {
+  registeredTenants: RegisteredTenants;
+}

package/src/registration/registration-types.ts

@@ -0,0 +1,18 @@
+/**
+ * Registration data model to be included as a parameter in the /registration POST request.
+ */
+export type RegistrationData = {
+  did: string;
+  termsOfServiceHash: string;
+};
+
+/**
+ * Registration request model of the /registration POST API.
+ */
+export type RegistrationRequest = {
+  proofOfWork: {
+    challengeNonce: string;
+    responseNonce: string;
+  },
+  registrationData: RegistrationData
+};