Home

cognito-toolkit

AWS Cognito authentication & authorization for web apps: a middleware family for Koa (cognito-toolkit/koa), Express (cognito-toolkit/express), Fetch-style servers (cognito-toolkit/fetch — Bun, Deno, Cloudflare Workers, …), and AWS Lambda (cognito-toolkit/lambda — API Gateway v1/v2, Function URLs, ALB) with route guards and an auth-cookie convenience, built on AWS's official aws-jwt-verify verifier, plus utilities for obtaining machine-to-machine (client_credentials) access tokens. The port family mirrors dynamodb-toolkit's adapters, so the two toolkits compose without glue.

• ESM-only, Node 20+ (runs on the latest Bun and Deno too); CommonJS consumers use require(esm) and the named exports.
• One runtime dependency: aws-jwt-verify (itself dependency-free). Frameworks are duck-typed — koa / express are not dependencies.
• v3 absorbed the sister packages koa-cognito-middleware and cognito-express-middleware as subpath exports; the standalone packages are frozen re-export thunks.

Quick start

import {CognitoJwtVerifier} from 'cognito-toolkit';
import {makeAuth} from 'cognito-toolkit/koa'; // or 'cognito-toolkit/express'

const verifier = CognitoJwtVerifier.create({userPoolId: 'us-east-1_MY_POOL', clientId: 'my-app-client', tokenUse: 'access'});
const auth = makeAuth({verifier});

app.use(auth.getUser); // ctx.state.user / req.user = decoded payload or null
router.get('/protected', auth.isAuthenticated, handler);
router.post('/writers', auth.hasGroup('writers'), handler);

Search

🔍 Search this wiki — ranked, deep-linked search via wiki-search; install the bookmarklet to search in place. Fallback: GitHub wiki search.

Documentation

Start here

• README — install, usage, security notes, and migration guides (from the v1 middlewares and from cognito-toolkit 1.x)
• Middleware ports — the shared makeAuth surface: options, bundle members, the two execution models, the auth cookie
• Browser usage — the client-side pattern: 401-driven login redirects, return URLs, renewal timers, the double-meh pairing
• Release notes — detailed per-version history

Reference

• Core API — makeGetUser, TokenVerifier, the verifier re-exports
• koa · express · fetch · lambda — per-port signatures, examples, and quirks
• utils/lazy-access-token · utils/renewable-access-token — client_credentials token holders

Under the hood

• ARCHITECTURE — internal layout and the verification-delegation rationale
• llms.txt / llms-full.txt — machine-readable API reference shipped in the npm tarball