@overlens/idp-token-core

Shared core of the Overlens Identity Provider. Single source of truth for:

1. Token claims contract — UserJwtPayload, M2MJwtPayload, IdTokenPayload + issuer/audience defaults.
2. Deterministic RSA-2048 test keypair with a fixed kid — public by design, for tests only.
3. Framework-agnostic RS256 signer/verifier built on jose — no NestJS, no Prisma.

A token minted here with the test keypair is byte-compatible with what the real IDP issues and validates (same kid, same claims, RS256).

⚠️ The test keypair never goes to production. TEST_RSA_PRIVATE_KEY_PEM is committed to the repository on purpose — it exists only for deterministic tests. getTestKeyPair() throws under NODE_ENV=production.

Install

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

ESM-only, Node >= 24.

Usage

import {
  signAccessToken,
  signM2MToken,
  verify,
  getTestKeyPair,
  TEST_RSA_KID,
} from '@overlens/idp-token-core';

// Mint a user access token (defaults: test keypair, IDP issuer/audience)
const token = await signAccessToken({
  sub: 'cm9abc...',
  email: '[email protected]',
  name: 'Ana',
  role: 'BASIC',
  email_verified: true,
});

// Verify (RS256 pinned; issuer/audience optional)
const payload = await verify(token, { issuer: 'https://idp.overlens.com.br' });

Subpath exports: @overlens/idp-token-core/claims, /test-keys, /sign.

Claims contract (summary)

| Token | aud | exp - iat | Key claims | |---|---|---|---| | User access | string[] | 900 | sub, email, name, role, email_verified, new_user? | | M2M | string[] | 300 | sub(=client_id), client_id, scope | | ID token (OIDC) | string (client_id) | 3600 | sub, email, name, email_verified, at_hash |

role is @deprecated as an authorization source (ADR-0008) — kept for backwards compatibility.

Docs

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

License

MIT © Overlens