Credential Stuffing in Hapi with Api Keys

Credential stuffing is an automated attack technique in which previously breached username and password pairs are systematically tried against a login endpoint to exploit reused credentials. When an API uses only static Api Keys for authentication in a Hapi server, the attack surface shifts from user credentials to the secrecy of the keys themselves. If an Api Key is embedded in client-side code, JavaScript bundles, or configuration files that are exposed in source control or logs, an attacker can harvest it and use it to authenticate as a service or impersonate a specific scope of access.

In Hapi, authentication schemes such as api-key-in-headers or api-key-in-query typically validate the presence and value of a key without additional context like IP restrictions, rotating nonces, or per-request signatures. A credential stuffing campaign targeting such an endpoint does not need to crack passwords; it simply needs a valid key. If the key is long-lived and lacks binding to a particular user agent, session, or rate context, a single leaked key can be reused across many requests, enabling large-scale enumeration of protected resources or unauthorized data access.

The risk is compounded when Hapi routes rely solely on Api Key validation without layered checks such as scope verification, contextual rate limiting, or correlation with request metadata. Attackers can run parallel requests using stolen keys while staying under simplistic per-IP limits, effectively bypassing weak rate controls. Moreover, if logging inadvertently captures keys (for example, via request logging plugins or error traces), the keys become part of an attacker’s dictionary list for future stuffing attempts. This pattern is especially dangerous when the same key is shared across multiple services or environments, as a compromise in one area can cascade to others.

Because Hapi does not enforce authentication by default, developers must explicitly apply validation strategies. Relying on a single static Api Key without additional signals—such as mandatory headers, restricted scopes, or runtime attestation—turns credential stuffing into a practical threat. The OWASP API Security Top 10 category Broken Object Level Authorization (BOLA) and Security Misconfiguration map to this scenario when weak authentication schemes are combined with predictable or widely shared keys.

Remediation focuses on reducing the effectiveness of credential stuffing by hardening how Api Keys are validated, scoped, and monitored within Hapi. Avoid embedding keys in client-side artifacts, and instead use server-controlled key injection or short-lived tokens where feasible. Implement strict route-level validation, scope checks, and contextual rate limiting to ensure that a compromised key cannot be widely reused.

Below are concrete, working examples of secure Hapi configurations that reduce the risk of credential stuffing when using Api Keys.

Example 1: Key validation with scope enforcement and strict header usage

const Hapi = require('@hapi/hapi');

const validKeys = new Set(['s3cr3tK3y-0a1b2c3d4e5f']);
const keyToScope = {
  's3cr3tK3y-0a1b2c3d4e5f': ['read:data', 'write:data']
};

const validateKey = (key, scopes) => {
  if (!validKeys.has(key)) {
    return { isValid: false };
  }
  return { isValid: true, credentials: { scope: scopes } };
};

const init = async () => {
  const server = Hapi.server({ port: 4000, host: 'localhost' });

  server.auth.scheme('customApiKey', (server) => ({
    authenticate(request, h) {
      const key = request.headers['x-api-key'];
      if (!key) {
        return h.authenticated({ credentials: null, artifacts: null });
      }
      const validated = validateKey(key, keyToScope[key] || []);
      if (!validated.isValid) {
        return h.authenticated({ credentials: null, artifacts: null });
      }
      return h.authenticated({ credentials: { key, scope: validated.credentials.scope }, artifacts: null });
    }
  }));

  server.auth.strategy('api-key', 'customApiKey');

  server.route({
    method: 'GET',
    path: '/secure/data',
    options: {
      auth: {
        strategy: 'api-key',
        scope: ['read:data']
      },
      handler: (request, h) => {
        return { message: 'Access granted', scope: request.auth.credentials.scope };
      }
    }
  });

  await server.start();
  console.log('Server running on %s', server.info.uri);
};

init();

Example 2: Reject requests missing required headers and enforce tighter controls

const Hapi = require('@hapi/hapi');

const init = async () => {
  const server = Hapi.server({ port: 4000, host: 'localhost' });

  server.ext('onPreHandler', (request, h) => {
    const key = request.headers['x-api-key'];
    if (!key || key.length < 16) {
      return h.response({ error: 'Invalid API Key' }).code(401);
    }
    // Optionally check against a rotated key store or environment map
    const valid = process.env.API_KEY === key;
    if (!valid) {
      return h.response({ error: 'Forbidden' }).code(403);
    }
    request.pre.apiKey = key;
    return h.continue;
  });

  server.route({
    method: 'POST',
    path: '/admin/action',
    options: {
      auth: false,
      handler: (request, h) => {
        return { status: 'ok', keyPresent: !!request.pre.apiKey };
      }
    }
  });

  await server.start();
  console.log('Server running on %s', server.info.uri);
};

init();

These examples demonstrate how to enforce strict header requirements, validate key format and length, and bind permissions to scopes. For broader protection, combine these patterns with server-side rate limiting and request correlation (e.g., tracking key usage per route) to detect and mitigate credential stuffing behavior in real time.