@enbox/dwn-server 0.0.2 → 0.0.4

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,6 +1,7 @@
-import { DwnServerError, DwnServerErrorCode } from "../dwn-error.js";
-import type { ProofOfWorkChallengeModel } from "./proof-of-work-types.js";
-import { ProofOfWork } from "./proof-of-work.js";
+import type { ProofOfWorkChallengeModel } from '@enbox/dwn-clients';
+
+import { ProofOfWork } from './proof-of-work.js';
+import { DwnServerError, DwnServerErrorCode } from '../dwn-error.js';
 
 /**
  * Manages proof-of-work challenge difficulty and lifecycle based on solve rate.
@@ -18,7 +19,7 @@ export class ProofOfWorkManager {
   };
 
   // There is opportunity to improve implementation here.
-  // TODO: https://github.com/TBD54566975/dwn-server/issues/101
+  // TODO: https://github.com/enboxorg/enbox/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.
@@ -122,8 +123,8 @@ export class ProofOfWorkManager {
 
   public getProofOfWorkChallenge(): ProofOfWorkChallengeModel {
     return {
-      challengeNonce: this.challengeNonces.currentChallengeNonce,
-      maximumAllowedHashValue: ProofOfWorkManager.bigIntToHexString(this.currentMaximumAllowedHashValue),
+      challengeNonce          : this.challengeNonces.currentChallengeNonce,
+      maximumAllowedHashValue : ProofOfWorkManager.bigIntToHexString(this.currentMaximumAllowedHashValue),
     };
   }
 
@@ -228,7 +229,7 @@ export class ProofOfWorkManager {
   /**
    * 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.
@@ -247,16 +248,16 @@ export class ProofOfWorkManager {
     //       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)) / 
+        = (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);
 

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;
+}