@insureco/bio 0.3.0

Released: 2026-01-10

JWT auth migrated from HS256+shared-secret to RS256+JWKS. JWT_SECRET no longer used.

Breaking Changes

🔴 BLOCK — bio-verify-token-hs256

verifyToken(token, secret) is deprecated for RS256 tokens. Bio-ID 0.3.0+ issues RS256 tokens. Calling verifyToken() on an RS256 token throws immediately: "Token uses RS256 — use verifyTokenJWKS() instead".

@insureco/bio 0.3.0: verifyToken() does not work with RS256 tokens.

REMOVE:
  import { verifyToken } from '@insureco/bio'
  const payload = verifyToken(token, process.env.JWT_SECRET)

REPLACE WITH:
  import { verifyTokenJWKS } from '@insureco/bio'
  const payload = await verifyTokenJWKS(token)

No secret needed. verifyTokenJWKS() fetches Bio-ID's public key from JWKS
and verifies locally. BIO_ID_URL is auto-injected by the builder.

Most services don't need this at all — if your routes are registered in
catalog-info.yaml with auth: required, Janus handles verification for you.

🟠 ERROR — bio-jwt-secret-env

JWT_SECRET is no longer used or needed in consuming services. Bio-ID 0.3.0 issues RS256 tokens signed with its private key. Consuming services verify using the public JWKS endpoint — no shared secret. Services that still set JWT_SECRET are either using legacy HS256 tokens or have unnecessary dead config.

@insureco/bio 0.3.0: JWT_SECRET is not used with RS256 auth.

REMOVE: JWT_SECRET from all env files, tawa config, and code references.

If you are verifying tokens: use verifyTokenJWKS(token) — no secret needed.
If you are generating tokens: use BioAuth.fromEnv() — reads BIO_CLIENT_ID + BIO_CLIENT_SECRET.

To clean up: tawa config unset JWT_SECRET

🟠 ERROR — bio-base-url-renamed

BIO_ID_BASE_URL env var renamed to BIO_ID_URL. BioAuth.fromEnv() reads process.env.BIO_ID_URL (confirmed in auth.ts line 72). Any code or config referencing BIO_ID_BASE_URL will silently fail to connect to the correct Bio-ID instance.

@insureco/bio 0.3.0: Environment variable renamed.

REMOVE:  BIO_ID_BASE_URL
ADD:     BIO_ID_URL

BIO_ID_URL is auto-injected by the builder when bio-id is declared as an
internalDependency. You rarely need to set this manually.

Deprecations

🟡 bio-verify-token-legacy

verifyToken(token, secret) still exists for HS256 tokens but is marked @deprecated in source. Will be removed in @insureco/bio 1.0.0.

EOL: 2027-01-01

@insureco/bio: verifyToken() with a secret is deprecated.
Upgrade to verifyTokenJWKS() for RS256 token verification.
Will be removed in @insureco/bio 1.0.0.

Migration

Migrating from: 0.2.x

Guide: https://tawa.insureco.io/docs/migration/bio-0.3

Notes

SECURITY NOTE: The HS256+shared-secret model meant JWT_SECRET had to be deployed to every service that verified tokens. A single compromise exposed all services. RS256 eliminates this — the private key lives only in Bio-ID, consuming services use the public JWKS endpoint.

Most services do NOT need to call verifyTokenJWKS() directly. If your routes are registered with auth: required in catalog-info.yaml, Janus verifies tokens before proxying the request. Only services with custom auth middleware need the SDK directly.