@enbox/dwn-server 0.0.3 → 0.0.5

package/src/registration/jwt-provider-auth-plugin.ts

@@ -0,0 +1,119 @@
+import type { ProviderAuthPlugin, ProviderAuthValidationResult } from './provider-auth-plugin.js';
+
+import * as jose from 'jose';
+import log from 'loglevel';
+
+/**
+ * Options for creating a {@link JwtProviderAuthPlugin}.
+ * Exactly one of `secret` or `jwksUrl` must be provided.
+ */
+export type JwtProviderAuthPluginOptions = {
+  /** HMAC shared secret for HS256/HS384/HS512 tokens. */
+  secret? : string;
+  /** JWKS endpoint URL for RS256/ES256/EdDSA tokens. */
+  jwksUrl? : string;
+  /** Expected JWT `iss` claim. If set, tokens without a matching issuer are rejected. */
+  issuer? : string;
+  /** Expected JWT `aud` claim. If set, tokens without a matching audience are rejected. */
+  audience? : string;
+};
+
+/**
+ * Built-in {@link ProviderAuthPlugin} that validates JWT registration tokens.
+ *
+ * Supports two modes:
+ * - **HMAC secret** (`DWN_PROVIDER_AUTH_JWT_SECRET`): symmetric HS256 verification.
+ * - **JWKS URL** (`DWN_PROVIDER_AUTH_JWT_JWKS_URL`): asymmetric verification via
+ *   a remote JWKS endpoint (RS256, ES256, EdDSA, etc.). Keys are cached and
+ *   rotated automatically by `jose`.
+ *
+ * The JWT payload may include:
+ * - `sub` — mapped to `accountId` in the validation result.
+ * - `metadata` — arbitrary provider-defined object stored with the tenant.
+ *
+ * This plugin ships with `@enbox/dwn-server` and requires no external code.
+ * Providers who need custom validation logic can implement their own
+ * {@link ProviderAuthPlugin} instead.
+ */
+export class JwtProviderAuthPlugin implements ProviderAuthPlugin {
+  #getKey: Uint8Array | jose.JWTVerifyGetKey;
+  #issuer: string | undefined;
+  #audience: string | undefined;
+
+  private constructor(
+    getKey: Uint8Array | jose.JWTVerifyGetKey,
+    issuer?: string,
+    audience?: string,
+  ) {
+    this.#getKey = getKey;
+    this.#issuer = issuer;
+    this.#audience = audience;
+  }
+
+  /**
+   * Create a {@link JwtProviderAuthPlugin} from options.
+   *
+   * @param options - Must include exactly one of `secret` or `jwksUrl`.
+   * @throws If neither `secret` nor `jwksUrl` is provided.
+   */
+  public static async create(options: JwtProviderAuthPluginOptions): Promise<JwtProviderAuthPlugin> {
+    if (!options.secret && !options.jwksUrl) {
+      throw new Error(
+        'JwtProviderAuthPlugin: exactly one of `secret` or `jwksUrl` must be provided.',
+      );
+    }
+
+    let getKey: any;
+    if (options.secret) {
+      getKey = new TextEncoder().encode(options.secret);
+    } else {
+      getKey = jose.createRemoteJWKSet(new URL(options.jwksUrl!));
+    }
+
+    return new JwtProviderAuthPlugin(getKey, options.issuer, options.audience);
+  }
+
+  /**
+   * Create a {@link JwtProviderAuthPlugin} from environment variables.
+   *
+   * Reads `DWN_PROVIDER_AUTH_JWT_SECRET`, `DWN_PROVIDER_AUTH_JWT_JWKS_URL`,
+   * and optionally `DWN_PROVIDER_AUTH_JWT_ISSUER` / `DWN_PROVIDER_AUTH_JWT_AUDIENCE`.
+   */
+  public static async fromEnv(): Promise<JwtProviderAuthPlugin> {
+    return JwtProviderAuthPlugin.create({
+      secret   : process.env.DWN_PROVIDER_AUTH_JWT_SECRET,
+      jwksUrl  : process.env.DWN_PROVIDER_AUTH_JWT_JWKS_URL,
+      issuer   : process.env.DWN_PROVIDER_AUTH_JWT_ISSUER,
+      audience : process.env.DWN_PROVIDER_AUTH_JWT_AUDIENCE,
+    });
+  }
+
+  /** @inheritdoc */
+  public async validateRegistrationToken(token: string): Promise<ProviderAuthValidationResult> {
+    try {
+      const verifyOptions: jose.JWTVerifyOptions = {};
+      if (this.#issuer !== undefined) {
+        verifyOptions.issuer = this.#issuer;
+      }
+      if (this.#audience !== undefined) {
+        verifyOptions.audience = this.#audience;
+      }
+
+      const { payload } = await jose.jwtVerify(token, this.#getKey as any, verifyOptions);
+
+      return {
+        isValid   : true,
+        accountId : typeof payload.sub === 'string' ? payload.sub : undefined,
+        metadata  : typeof payload.metadata === 'object' && payload.metadata !== null
+          ? payload.metadata as Record<string, unknown>
+          : undefined,
+      };
+    } catch (error) {
+      log.debug('JWT validation failed:', (error as Error).message);
+      return {
+        isValid : false,
+        detail  : (error as Error).message,
+      };
+    }
+  }
+}

package/src/registration/open-auth-handler.ts

@@ -0,0 +1,263 @@
+import * as jose from 'jose';
+import log from 'loglevel';
+
+/**
+ * Built-in "open auth" handler for DWN servers that want registration
+ * without any user authentication (open-to-all).
+ *
+ * Implements the provider-auth-v0 authorize / token / refresh endpoints
+ * locally on the DWN server. The authorize endpoint immediately returns
+ * an authorization code (no user interaction), the token endpoint exchanges
+ * it for a JWT registration token, and the refresh endpoint issues a new token.
+ *
+ * This is the simplest possible auth backend — suitable for free/public DWN
+ * providers. Providers who want real authentication (passkey, OIDC, etc.)
+ * host their own auth service and point `providerAuth.authorizeUrl` /
+ * `tokenUrl` to it instead.
+ *
+ * The JWTs issued here are verified by {@link JwtProviderAuthPlugin} using
+ * the same shared secret (`DWN_PROVIDER_AUTH_JWT_SECRET`).
+ */
+/**
+ * Maximum number of pending authorization codes held in memory.
+ * When the limit is reached, new authorize requests are rejected with 503.
+ */
+const MAX_PENDING_CODES = 10_000;
+
+/** Interval (ms) at which expired authorization codes are purged. */
+const CLEANUP_INTERVAL_MS = 60_000;
+
+export class OpenAuthHandler {
+  #secret: Uint8Array;
+  #issuer: string;
+  /** Pending authorization codes. Maps code → { redirectUri, expiresAt }. */
+  #pendingCodes: Map<string, { redirectUri: string; expiresAt: number }>;
+  /** Registration token TTL in seconds. Default: 1 year. */
+  #tokenTtlSeconds: number;
+  /** Periodic cleanup timer for expired codes. */
+  #cleanupTimer: ReturnType<typeof setInterval>;
+
+  private constructor(secret: Uint8Array, issuer: string, tokenTtlSeconds: number) {
+    this.#secret = secret;
+    this.#issuer = issuer;
+    this.#pendingCodes = new Map();
+    this.#tokenTtlSeconds = tokenTtlSeconds;
+
+    // Periodically purge expired codes so memory does not grow unbounded
+    // even when no new authorize requests arrive.
+    this.#cleanupTimer = setInterval(() => this.#cleanExpiredCodes(), CLEANUP_INTERVAL_MS);
+    // Allow the process to exit even if the timer is still running.
+    if (this.#cleanupTimer.unref) {
+      this.#cleanupTimer.unref();
+    }
+  }
+
+  /**
+   * Create an {@link OpenAuthHandler}.
+   *
+   * @param secret - HMAC shared secret (same as `DWN_PROVIDER_AUTH_JWT_SECRET`).
+   * @param issuer - JWT issuer claim (typically the DWN server's base URL).
+   * @param tokenTtlSeconds - Registration token lifetime in seconds. Default: 1 year.
+   */
+  public static create(secret: string, issuer: string, tokenTtlSeconds = 365 * 24 * 60 * 60): OpenAuthHandler {
+    return new OpenAuthHandler(
+      new TextEncoder().encode(secret),
+      issuer,
+      tokenTtlSeconds,
+    );
+  }
+
+  /**
+   * Handle `GET /provider-auth/authorize`.
+   *
+   * In open-auth mode this immediately generates a code and redirects back
+   * to the `redirect_uri` with `code` and `state` query parameters.
+   * No user interaction is required.
+   */
+  public handleAuthorize(url: URL): Response {
+    const redirectUri = url.searchParams.get('redirect_uri');
+    const state = url.searchParams.get('state');
+
+    if (!redirectUri) {
+      return Response.json(
+        { error: 'missing redirect_uri parameter' },
+        { status: 400 },
+      );
+    }
+
+    // Reject new codes when the map is at capacity to prevent memory exhaustion.
+    if (this.#pendingCodes.size >= MAX_PENDING_CODES) {
+      log.warn(`OpenAuthHandler: pending codes map is full (${MAX_PENDING_CODES}), rejecting authorize request`);
+      return Response.json(
+        { error: 'server is busy, try again later' },
+        { status: 503 },
+      );
+    }
+
+    // Generate a random authorization code.
+    const code = crypto.randomUUID();
+
+    // Store the code with a 10-minute expiry.
+    this.#pendingCodes.set(code, {
+      redirectUri,
+      expiresAt: Date.now() + 10 * 60 * 1000,
+    });
+
+    // Periodically clean up expired codes (simple inline sweep).
+    this.#cleanExpiredCodes();
+
+    // Build redirect URL.
+    const redirect = new URL(redirectUri);
+    redirect.searchParams.set('code', code);
+    if (state) {
+      redirect.searchParams.set('state', state);
+    }
+
+    log.debug(`OpenAuthHandler: issued code ${code.slice(0, 8)}… for redirect to ${redirectUri}`);
+
+    return Response.json({
+      code,
+      state       : state ?? undefined,
+      redirectUri : redirect.toString(),
+    });
+  }
+
+  /**
+   * Handle `POST /provider-auth/token`.
+   *
+   * Exchanges an authorization code for a JWT registration token.
+   * Request body: `{ code: string, redirectUri: string }`.
+   */
+  public async handleToken(req: Request): Promise<Response> {
+    let body: { code?: string; redirectUri?: string };
+    try {
+      body = await req.json() as { code?: string; redirectUri?: string };
+    } catch {
+      return Response.json({ error: 'invalid JSON body' }, { status: 400 });
+    }
+
+    const { code, redirectUri } = body;
+    if (!code || !redirectUri) {
+      return Response.json(
+        { error: 'missing code or redirectUri' },
+        { status: 400 },
+      );
+    }
+
+    // Validate the authorization code.
+    const pending = this.#pendingCodes.get(code);
+    if (!pending) {
+      return Response.json({ error: 'invalid or expired code' }, { status: 400 });
+    }
+
+    if (pending.redirectUri !== redirectUri) {
+      return Response.json({ error: 'redirect_uri mismatch' }, { status: 400 });
+    }
+
+    if (Date.now() > pending.expiresAt) {
+      this.#pendingCodes.delete(code);
+      return Response.json({ error: 'code expired' }, { status: 400 });
+    }
+
+    // Consume the code (one-time use).
+    this.#pendingCodes.delete(code);
+
+    // Generate an account ID for this session (open auth = anonymous accounts).
+    const accountId = crypto.randomUUID();
+
+    // Issue JWT registration token.
+    const registrationToken = await this.#signToken(accountId, this.#tokenTtlSeconds);
+
+    // Issue refresh token with longer TTL (2x).
+    const refreshToken = await this.#signToken(accountId, this.#tokenTtlSeconds * 2, 'refresh');
+
+    log.debug(`OpenAuthHandler: exchanged code for account ${accountId.slice(0, 8)}…`);
+
+    return Response.json({
+      registrationToken,
+      refreshToken,
+      expiresIn : this.#tokenTtlSeconds,
+      tokenType : 'bearer',
+    });
+  }
+
+  /**
+   * Handle `POST /provider-auth/refresh`.
+   *
+   * Exchanges a refresh token for a new registration token.
+   * Request body: `{ refreshToken: string }`.
+   */
+  public async handleRefresh(req: Request): Promise<Response> {
+    let body: { refreshToken?: string };
+    try {
+      body = await req.json() as { refreshToken?: string };
+    } catch {
+      return Response.json({ error: 'invalid JSON body' }, { status: 400 });
+    }
+
+    if (!body.refreshToken) {
+      return Response.json({ error: 'missing refreshToken' }, { status: 400 });
+    }
+
+    // Verify the refresh token.
+    let payload: jose.JWTPayload;
+    try {
+      const result = await jose.jwtVerify(body.refreshToken, this.#secret, {
+        issuer: this.#issuer,
+      });
+      payload = result.payload;
+    } catch (error) {
+      return Response.json(
+        { error: `invalid refresh token: ${(error as Error).message}` },
+        { status: 400 },
+      );
+    }
+
+    if (payload.purpose !== 'refresh') {
+      return Response.json({ error: 'token is not a refresh token' }, { status: 400 });
+    }
+
+    const accountId = payload.sub ?? crypto.randomUUID();
+
+    // Issue new tokens.
+    const registrationToken = await this.#signToken(accountId, this.#tokenTtlSeconds);
+    const refreshToken = await this.#signToken(accountId, this.#tokenTtlSeconds * 2, 'refresh');
+
+    log.debug(`OpenAuthHandler: refreshed token for account ${accountId.slice(0, 8)}…`);
+
+    return Response.json({
+      registrationToken,
+      refreshToken,
+      expiresIn : this.#tokenTtlSeconds,
+      tokenType : 'bearer',
+    });
+  }
+
+  /** Sign a JWT with the shared secret. */
+  async #signToken(accountId: string, ttlSeconds: number, purpose = 'registration'): Promise<string> {
+    return new jose.SignJWT({ purpose })
+      .setProtectedHeader({ alg: 'HS256' })
+      .setIssuer(this.#issuer)
+      .setAudience(this.#issuer)
+      .setSubject(accountId)
+      .setIssuedAt()
+      .setExpirationTime(`${ttlSeconds}s`)
+      .sign(this.#secret);
+  }
+
+  /** Stops the periodic cleanup timer and clears all pending codes. */
+  public destroy(): void {
+    clearInterval(this.#cleanupTimer);
+    this.#pendingCodes.clear();
+  }
+
+  /** Remove expired authorization codes from the pending map. */
+  #cleanExpiredCodes(): void {
+    const now = Date.now();
+    for (const [code, data] of this.#pendingCodes) {
+      if (now > data.expiresAt) {
+        this.#pendingCodes.delete(code);
+      }
+    }
+  }
+}

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

@@ -1,4 +1,4 @@
-import type { ProofOfWorkChallengeModel } from './proof-of-work-types.js';
+import type { ProofOfWorkChallengeModel } from '@enbox/dwn-clients';
 
 import { ProofOfWork } from './proof-of-work.js';
 import { DwnServerError, DwnServerErrorCode } from '../dwn-error.js';

package/src/registration/provider-auth-plugin.ts

@@ -0,0 +1,84 @@
+import { DwnServerError, DwnServerErrorCode } from '../dwn-error.js';
+
+/**
+ * Interface for validating provider auth registration tokens.
+ * DWN server operators implement this to integrate with their auth service.
+ *
+ * The token is intentionally opaque — it could be a JWT, blind RSA token,
+ * ecash token, or any other format. The plugin is responsible for all
+ * validation logic.
+ */
+export interface ProviderAuthPlugin {
+  /**
+   * Validate a registration token presented during DID registration.
+   *
+   * @param token - The opaque registration token from the client
+   * @returns Validation result with optional account metadata
+   */
+  validateRegistrationToken(token: string): Promise<ProviderAuthValidationResult>;
+}
+
+/**
+ * Result of validating a provider auth registration token.
+ */
+export type ProviderAuthValidationResult = {
+  /** Whether the token is valid and the registration should proceed. */
+  isValid : boolean;
+
+  /**
+   * Optional account identifier that this DID registration is associated with.
+   * Omit for privacy-preserving providers where DID-to-account correlation
+   * should not be stored.
+   */
+  accountId? : string;
+
+  /**
+   * Optional provider-defined metadata to store with the tenant registration.
+   * Can include plan details, quotas, or any other provider-specific data.
+   * Stored as JSON in the registeredTenants table.
+   */
+  metadata? : Record<string, unknown>;
+
+  /** Error detail message when isValid is false. */
+  detail? : string;
+};
+
+/**
+ * Load a ProviderAuthPlugin from a file path.
+ * The module must export a default class or object that implements ProviderAuthPlugin.
+ *
+ * Follows the same pattern as the existing PluginLoader.
+ */
+export async function loadProviderAuthPlugin(pluginPath: string): Promise<ProviderAuthPlugin> {
+  let module: any;
+  try {
+    module = await import(pluginPath);
+  } catch (error) {
+    throw new DwnServerError(
+      DwnServerErrorCode.ProviderAuthPluginLoadFailed,
+      `Failed to load provider auth plugin at ${pluginPath}: ${(error as Error).message}`,
+    );
+  }
+
+  const plugin = module.default;
+  if (plugin === undefined) {
+    throw new DwnServerError(
+      DwnServerErrorCode.ProviderAuthPluginLoadFailed,
+      `Provider auth plugin at ${pluginPath} does not have a default export.`,
+    );
+  }
+
+  // Support both class (instantiate) and plain object exports.
+  const instance: ProviderAuthPlugin = typeof plugin === 'function'
+    ? new plugin() as ProviderAuthPlugin
+    : plugin as ProviderAuthPlugin;
+
+  if (typeof instance.validateRegistrationToken !== 'function') {
+    throw new DwnServerError(
+      DwnServerErrorCode.ProviderAuthPluginLoadFailed,
+      `Provider auth plugin at ${pluginPath} does not implement validateRegistrationToken().`,
+    );
+  }
+
+  return instance;
+}

package/src/registration/registration-manager.ts

@@ -1,6 +1,6 @@
-import type { ProofOfWorkChallengeModel } from './proof-of-work-types.js';
+import type { ProviderAuthPlugin } from './provider-auth-plugin.js';
 import type { ActiveTenantCheckResult, TenantGate } from '@enbox/dwn-sdk-js';
-import type { RegistrationData, RegistrationRequest } from './registration-types.js';
+import type { ProofOfWorkChallengeModel, RegistrationRequest } from '@enbox/dwn-clients';
 
 import { readFileSync } from 'fs';
 
@@ -16,6 +16,7 @@ import { DwnServerError, DwnServerErrorCode } from '../dwn-error.js';
  */
 export class RegistrationManager implements TenantGate {
   private proofOfWorkManager: ProofOfWorkManager;
+  private providerAuthPlugin?: ProviderAuthPlugin;
   private registrationStore: RegistrationStore;
 
   private termsOfServiceHash?: string;
@@ -51,9 +52,10 @@ export class RegistrationManager implements TenantGate {
    */
   public static async create(input: {
     registrationStoreUrl?: string,
-    termsOfServiceFilePath?: string
+    termsOfServiceFilePath?: string,
     proofOfWorkChallengeNonceSeed?: string,
     proofOfWorkInitialMaximumAllowedHash?: string,
+    providerAuthPlugin?: ProviderAuthPlugin,
   }): Promise<RegistrationManager> {
     const { termsOfServiceFilePath, registrationStoreUrl } = input;
 
@@ -83,6 +85,11 @@ export class RegistrationManager implements TenantGate {
     const registrationStore = await RegistrationStore.create(sqlDialect);
     registrationManager.registrationStore = registrationStore;
 
+    // Store optional provider auth plugin.
+    if (input.providerAuthPlugin !== undefined) {
+      registrationManager.providerAuthPlugin = input.providerAuthPlugin;
+    }
+
     return registrationManager;
   }
 
@@ -95,17 +102,79 @@ export class RegistrationManager implements TenantGate {
   }
 
   /**
-   * Handles a registration request.
+   * Handles a registration request by dispatching to the appropriate handler
+   * based on the credentials provided.
    */
   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}.`
+    if (registrationRequest.providerAuth?.registrationToken !== undefined) {
+      await this.handleProviderAuthRegistration(registrationRequest);
+    } else if (registrationRequest.proofOfWork !== undefined) {
+      await this.handleProofOfWorkRegistration(registrationRequest);
+    } else {
+      throw new DwnServerError(
+        DwnServerErrorCode.RegistrationRequestMissingCredentials,
+        'Registration request must include either providerAuth or proofOfWork credentials.',
+      );
+    }
+  }
+
+  /**
+   * Handles a provider-auth registration request.
+   */
+  private async handleProviderAuthRegistration(registrationRequest: RegistrationRequest): Promise<void> {
+    if (this.providerAuthPlugin === undefined) {
+      throw new DwnServerError(
+        DwnServerErrorCode.ProviderAuthNotEnabled,
+        'Provider auth registration is not enabled on this server.',
       );
     }
 
-    const { challengeNonce, responseNonce } = registrationRequest.proofOfWork;
+    const token = registrationRequest.providerAuth!.registrationToken;
+    const validationResult = await this.providerAuthPlugin.validateRegistrationToken(token);
+
+    if (!validationResult.isValid) {
+      throw new DwnServerError(
+        DwnServerErrorCode.ProviderAuthTokenInvalid,
+        validationResult.detail ?? 'Provider auth registration token is invalid.',
+      );
+    }
+
+    // Validate ToS only when the server has ToS configured AND the request includes a hash.
+    if (this.termsOfServiceHash !== undefined && registrationRequest.registrationData.termsOfServiceHash !== undefined) {
+      if (registrationRequest.registrationData.termsOfServiceHash !== this.termsOfServiceHash) {
+        throw new DwnServerError(DwnServerErrorCode.RegistrationManagerInvalidOrOutdatedTermsOfServiceHash,
+          `Expecting terms-of-service hash ${this.termsOfServiceHash}, ` +
+          `but got ${registrationRequest.registrationData.termsOfServiceHash}.`,
+        );
+      }
+    }
+
+    await this.registrationStore.insertOrUpdateTenantRegistration({
+      did                : registrationRequest.registrationData.did,
+      termsOfServiceHash : registrationRequest.registrationData.termsOfServiceHash,
+      accountId          : validationResult.accountId,
+      registrationType   : 'provider-auth',
+      metadata           : validationResult.metadata !== undefined
+        ? JSON.stringify(validationResult.metadata)
+        : undefined,
+    });
+  }
+
+  /**
+   * Handles a proof-of-work registration request.
+   */
+  private async handleProofOfWorkRegistration(registrationRequest: RegistrationRequest): Promise<void> {
+    // Validate ToS only when the server has ToS configured.
+    if (this.termsOfServiceHash !== undefined) {
+      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,
@@ -114,14 +183,24 @@ export class RegistrationManager implements TenantGate {
     });
 
     // Store tenant registration data in database.
-    await this.recordTenantRegistration(registrationRequest.registrationData);
+    await this.recordTenantRegistration({
+      did                : registrationRequest.registrationData.did,
+      termsOfServiceHash : registrationRequest.registrationData.termsOfServiceHash,
+      registrationType   : 'proof-of-work',
+    });
   }
 
   /**
    * Records the given registration data in the database.
    * Exposed as a public method for testing purposes.
    */
-  public async recordTenantRegistration(registrationData: RegistrationData): Promise<void> {
+  public async recordTenantRegistration(registrationData: {
+    did: string;
+    termsOfServiceHash?: string;
+    accountId?: string;
+    registrationType?: string;
+    metadata?: string;
+  }): Promise<void> {
     await this.registrationStore.insertOrUpdateTenantRegistration(registrationData);
   }
 
@@ -143,7 +222,16 @@ export class RegistrationManager implements TenantGate {
       };
     }
 
-    if (tenantRegistration.termsOfServiceHash !== this.termsOfServiceHash) {
+    if (tenantRegistration.suspended) {
+      return {
+        isActiveTenant : false,
+        detail         : 'Tenant is suspended.'
+      };
+    }
+
+    // Only enforce ToS hash check when the server has a ToS configured.
+    if (this.termsOfServiceHash !== undefined &&
+      tenantRegistration.termsOfServiceHash !== this.termsOfServiceHash) {
       return {
         isActiveTenant : false,
         detail         : 'Agreed terms-of-service is outdated.'
@@ -152,4 +240,12 @@ export class RegistrationManager implements TenantGate {
 
     return { isActiveTenant: true };
   }
+
+  /**
+   * Returns the underlying RegistrationStore, if initialized.
+   * Used by the admin API to access tenant data.
+   */
+  public getRegistrationStore(): RegistrationStore | undefined {
+    return this.registrationStore;
+  }
 }