Release notes

Release notes

Detailed per-version history. The README carries the one-line summaries.

3.1.0 (2026-07-17)

The port family is complete — and the browser side is documented:

• Fetch and Lambda middleware ports. cognito-toolkit/fetch wraps (request: Request) => Response handlers (Bun.serve, Deno.serve / Deploy, Cloudflare Workers, Hono); cognito-toolkit/lambda wraps (event, context) handlers with API Gateway v1 / v2 / Function URL / ALB event shapes auto-detected (case-insensitive headers, v2 cookies array, ALB multi-value header mode mirrored on responses). Both use the handler-wrapper model: getUser is a per-request-memoized lookup, guards wrap handlers, denials are a Response / result envelope. The family now mirrors dynamodb-toolkit's adapter ports (./koa, ./express, ./fetch, ./lambda), so the two toolkits compose without glue; sources moved under src/http/ to match.
• Renewal hardening in createRenewableAccessToken. A failed scheduled renewal no longer stops the cycle silently: it keeps the previous token and retries every retryInterval ms (new option, default one minute) until success or cancellation, reporting each failure to the new onError hook (or the debug channel) — never an unhandled rejection. cancelRenewal() is now final even mid-flight: a renewal already awaiting the token endpoint neither stores its late result nor reschedules.
• AlbJwtVerifier re-exported from the root alongside CognitoJwtVerifier / JwtVerifier — the lambda port's ALB story is one-stop now.
• Documentation build-out. The wiki gained a formal reference tier (Middleware ports, Core-API, per-port pages, the token-utility pages) and Browser usage — the production-proven client-side pattern: 401-driven login redirects with return URLs, active-user renewal timers, history hygiene (location.replace + history.go(-N)), and the double-meh pairing. The README added TypeScript and CommonJS notes.
• Internal: subpath entry points restructured as folder barrels (importmap-friendly exports, public paths unchanged); @ts-self-types directives added across src/; retired llms/llmsFull package fields and the policy-only engines.node dropped; @types/aws-lambda joined the dev dependencies.

3.0.0 (2026-07-17)

Breaking reshape — the package became the web-app glue over AWS's official verifier:

• Verification delegated to aws-jwt-verify (^5.2.1), the single runtime dependency (itself dependency-free). The 1.x homegrown verification stack (jsonwebtoken-era code and its 2.x zero-dependency rewrite) is gone. CognitoJwtVerifier / JwtVerifier are re-exported from the package root.
• makeGetUser(verifier, options?) replaces makeGetUser(pools, options?): build the verifier yourself (CognitoJwtVerifier.create({userPoolId, clientId, tokenUse})) and hand it over. An absent token resolves null and never throws; verification failures resolve null or, under throwOnError, throw aws-jwt-verify error classes. prime() maps to the verifier's hydrate().
• Middlewares absorbed as subpaths — the sister packages koa-cognito-middleware and cognito-express-middleware moved in as cognito-toolkit/koa and cognito-toolkit/express; the standalone packages are frozen re-export thunks (their 2.0.0). makeAuth(options) returns a per-instance bundle — getUser, isAuthenticated, hasGroup, hasScope, isAllowed, setAuthCookie, stateUserProperty — replacing the former module-level statics.
• Auth-cookie fix: the cookie domain defaults to the request hostname — the old host default broke on Express 5, which keeps the port on req.host (the cookie serializer rejects it).
• Guards read Cognito's cognito:groups and OAuth2 scope claims; 401 for anonymous, 403 for authenticated-but-unauthorized. Tokens are used bare (no Bearer stripping — use a custom source to strip).
• Token utilities (utils/lazy-access-token, utils/renewable-access-token) are unchanged from 2.x.
• Migration guides: from the v1 middlewares and from cognito-toolkit 1.x.

2.0.0 (unpublished)

Zero-dependency, ESM-only rewrite of the 1.x verifier on Node built-ins (crypto + fetch): configurable algorithm policy, audience / tokenUse / validate checks, typed CognitoAuthError, per-issuer JWKS with rotation refresh. Never published — the survey found AWS's aws-jwt-verify at parity-plus, which led directly to the 3.0.0 delegation.

1.x

• 1.0.6 — updated dependencies.
• 1.0.5 — updated dependencies.
• 1.0.4 — updated dependencies.
• 1.0.3 — updated dependencies.
• 1.0.2 — updated dependencies.
• 1.0.1 — added support for multiple pools.
• 1.0.0 — the initial public release (CommonJS, jsonwebtoken + jwk-to-pem).