Testing H33 Authentication:
Unit and Integration Tests

Authentication systems are only as reliable as the tests that guard them. When your stack operates at 1.595 million authentications per second with a full post-quantum pipeline—BFV fully homomorphic encryption, zero-knowledge proof lookups, and Dilithium signature attestation—a single untested edge case can cascade into a production incident that affects millions of users. This guide walks through a layered testing strategy for H33 integrations, from isolated unit tests through full end-to-end verification, so you can ship with confidence.

Why Authentication Testing Demands a Different Mindset

Standard application tests verify that correct inputs produce correct outputs. Authentication testing must go further: you need to prove that incorrect inputs are rejected, that timing characteristics do not leak secrets, and that cryptographic operations remain consistent across environments. H33 compounds this challenge because each API call executes three distinct cryptographic stages—FHE biometric matching, ZKP cache verification, and post-quantum attestation—all within roughly 42 microseconds per authentication. Your tests must validate each stage independently and then confirm they compose correctly.

Unit Tests: Isolating the Client Layer

Unit tests should cover your client-side integration code without making real API calls. The goal is to verify that your application correctly constructs requests, handles responses, and manages error conditions.

Mocking the H33 SDK

Create deterministic mock responses for each endpoint. The critical responses to mock are the enrollment confirmation, the verification result (match or no-match), and the attestation certificate. Here is a minimal example using a mock server:

// test/mocks/h33-mock.ts
import { setupServer } from "msw/node";
import { rest } from "msw";

const server = setupServer(
  rest.post("https://api.h33.ai/v1/verify", (req, res, ctx) => {
    const { template } = req.body;
    if (!template || template.length !== 128) {
      return res(ctx.status(400), ctx.json({
        error: "INVALID_TEMPLATE",
        message: "Template must be 128 dimensions"
      }));
    }
    return res(ctx.json({
      match: true,
      confidence: 0.97,
      attestation: "dilithium-sig-base64...",
      latency_us: 42,
      pipeline: { fhe_us: 34, zkp_us: 0.085, attest_us: 7.6 }
    }));
  })
);

beforeAll(() => server.listen());
afterEach(() => server.resetHandlers());
afterAll(() => server.close());

Notice the pipeline field in the mock response. In production, H33 returns per-stage latency breakdowns. Your unit tests should verify that your code correctly parses these fields, even if the exact values differ between environments. The ZKP lookup stage resolves in approximately 0.085 microseconds via an in-process DashMap cache, while the FHE batch operation for 32 users takes around 1,109 microseconds.

What to Assert in Unit Tests

• Request shape — API key header present, template encoded as expected, correct Content-Type
• Success path — Match result propagated to caller, confidence score parsed as a float, attestation stored
• Error mapping — HTTP 401 maps to an authentication error, HTTP 429 triggers retry with backoff, HTTP 500 triggers circuit breaker
• Timeout handling — Request aborts after your configured threshold (recommended: 5 seconds for network, though the server-side pipeline completes in microseconds)
• Attestation validation — Dilithium signature is forwarded to your verification layer, not silently discarded

Integration Tests: Sandbox Environment

H33 provides a sandbox environment at sandbox.h33.ai that mirrors the production pipeline but operates on synthetic biometric templates. Integration tests should exercise the real network path, TLS handshake, and response parsing against this sandbox.

Verifying the Attestation Certificate

Every H33 response includes a Dilithium signature that attests to the integrity of the result. This is not decorative—it is the mechanism that prevents a man-in-the-middle from flipping a match: false to match: true. Your integration tests must verify this signature against H33's published public key:

import { verifyDilithium } from "@h33/sdk";
import { H33_PUBLIC_KEY } from "./keys";

test("attestation signature is valid", async () => {
  const result = await h33.verify(enrolledUser, freshTemplate);
  const payload = JSON.stringify({
    match: result.match,
    confidence: result.confidence,
    timestamp: result.timestamp,
  });
  const valid = verifyDilithium(H33_PUBLIC_KEY, payload, result.attestation);
  expect(valid).toBe(true);
});

If you skip attestation verification in production, you lose the post-quantum guarantee entirely. The FHE and ZKP stages protect data confidentiality and proof integrity, but it is the Dilithium signature that binds the result to H33's identity. All three stages must be validated end-to-end.

End-to-End and Load Testing

End-to-end tests run through your full application stack: UI interaction, backend proxy, H33 API call, response handling, and session creation. These tests catch integration failures that neither unit nor integration tests reveal—missing CORS headers, cookie misconfiguration, or race conditions in concurrent authentication flows.

Load Testing Against Production Characteristics

H33's production infrastructure sustains 1.595 million authentications per second on a single Graviton4 node. Your bottleneck will almost certainly be on your side, not on H33's. Load tests should focus on three areas:

• Connection pooling — Ensure your HTTP client reuses connections. Opening a new TLS 1.3 handshake per request adds 20–50ms of overhead that dwarfs the ~42-microsecond server-side processing time.
• Concurrent request handling — Simulate your expected peak concurrency. Verify that your backend does not serialize authentication requests behind a single mutex or database lock.
• Graceful degradation — Test with H33 returning HTTP 503 for 10% of requests. Your circuit breaker should open after a configurable threshold and return a cached decision or a fallback flow.

Security-Focused Test Cases

Beyond functional correctness, dedicate a test suite to adversarial scenarios. These tests validate that your integration does not inadvertently weaken the security properties that H33 provides:

• Replay resistance — Record a valid verification response and replay it 60 seconds later. Your backend should reject it based on the timestamp in the attestation.
• Template confidentiality — Assert that biometric templates are never written to application logs, error tracking services, or browser local storage. Templates are encrypted under BFV FHE before leaving the client; logging the ciphertext is safe, but logging the plaintext template is a compliance violation.
• Key rotation — Simulate H33 rotating its Dilithium public key. Your verification layer should accept signatures from both the current and previous key during the overlap window.
• Downgrade prevention — Ensure your client rejects responses that lack the attestation field entirely. A missing signature should be treated as a verification failure, not a match.

Continuous Integration Pipeline

Structure your CI pipeline in three stages, each gating the next. Unit tests run on every commit, typically completing in under 10 seconds. Integration tests run against the sandbox on every pull request, adding 30–60 seconds. Load tests and security scans run nightly or before release cuts.

# .github/workflows/auth-tests.yml
jobs:
  unit:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: npm ci
      - run: npm test -- --grep "unit"

  integration:
    needs: unit
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: npm ci
      - run: npm test -- --grep "integration"
    env:
      H33_API_KEY: ${{ secrets.H33_SANDBOX_KEY }}
      H33_BASE_URL: https://sandbox.h33.ai

  load:
    needs: integration
    if: github.event_name == 'schedule'
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: npx k6 run tests/load/h33-auth.js

A well-structured test suite for H33 integration is not overhead—it is the mechanism by which you inherit the security guarantees of a post-quantum authentication pipeline. The FHE encryption, ZKP proof validation, and Dilithium attestation — all computed on encrypted data — are only as strong as the code that invokes and verifies them. Test thoroughly, test adversarially, and test continuously.