@overlens/idp-testing

Testing toolkit for integrations with the Overlens Identity Provider: mint valid RS256 tokens, serve a mock JWKS (object or ephemeral HTTP server), forge negative cases, run drop-in conformance suites, preflight your OIDC config with the idp-doctor CLI, and spin up the real containerized IDP — offline and deterministic; Docker is only needed for the container helper.

Built on @overlens/idp-token-core: a token minted here is byte-compatible with what the real IDP issues (same kid, same claims, RS256).

⚠️ Uses the repository's public test keypair — never valid in production. getTestKeyPair() throws under NODE_ENV=production.

Install

pnpm add -D @overlens/idp-testing
# or: npm i -D @overlens/idp-testing

ESM-only, Node >= 24.

Mint tokens and mock the JWKS

import { mintToken, mintM2MToken, getJwks, startJwksServer } from '@overlens/idp-testing';

const token = await mintToken({ sub: 'cm9abc...', email: '[email protected]' });
const m2m = await mintM2MToken({ clientId: 'my-service', scope: 'thing:read' });

const jwks = getJwks(); // JWKS literal for libs that accept an object
const server = await startJwksServer(); // ...or an ephemeral URL (e.g. jwks-rsa)
// server.jwksUri → http://127.0.0.1:<port>/.well-known/jwks.json
await server.close();

Negative-case factories (your validation MUST reject all of them): expiredToken, futureIatToken, wrongAudToken, wrongIssToken, unknownKidToken, invalidSignatureToken, hs256Token, algNoneToken.

Drop-in conformance kits

// rs-conformance.spec.ts (Jest or Vitest with globals)
import { runResourceServerConformance } from '@overlens/idp-testing/conformance';

runResourceServerConformance({
  verifyBearer: async (token) => {
    try {
      return { ok: true, principal: await verifyMyToken(token) };
    } catch {
      return { ok: false, status: 401 };
    }
  },
});

Registers the full case matrix (valid token, expired, wrong iss/aud, HS256/alg:none confusion, unknown kid, bad signature, M2M scopes…). For clients/BFFs that initiate login there is runClientConformance, driven against the in-process mock IDP (@overlens/idp-testing/mock-idp) — no browser, no network.

idp-doctor CLI

Preflight your OIDC configuration against a live IDP:

npx idp-doctor --issuer https://idp.overlens.com.br --json
# checks discovery + JWKS; add --token <jwt> to also check kid/iss/aud/clock

Real containerized IDP (Testcontainers)

Requires Docker and the optional peer dependency testcontainers (pnpm add -D testcontainers).

import { startIdpContainer } from '@overlens/idp-testing/container';

const idp = await startIdpContainer(); // embedded compose — works outside the monorepo
try {
  // idp.url, idp.jwksUri, headless login via POST /test/login ...
} finally {
  await idp.stop();
}

By default this uses the compose file embedded in the package (assets/docker-compose.external.yml), which runs the published image ghcr.io/overlens/idp-test (+ ephemeral Postgres/Redis, deterministic test keypair, seeded fixtures).

Note: the external mode requires that image to be published to GHCR (workflow publish-idp-test-image.yml in the IDP repo). First publication is pending — until then, external repos can use every other feature (mint/JWKS/mock/conformance/doctor), which needs no Docker.

Inside the monorepo, the original behavior is preserved: startIdpContainer({ composeDir: 'apps/idp' }) builds the image from the root Dockerfile.

Docs

Full guide: docs/integration/idp-testing-toolkit.md.

License

MIT © Overlens