Home

cognito-toolkit

AWS Cognito authentication & authorization for web apps: a middleware family for Koa (cognito-toolkit/koa) and Express (cognito-toolkit/express) 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.

• 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);
router.post('/scoped', auth.hasScope('write'), handler);

Documentation

• README — install, usage, full API, security notes, migration from the v1 middlewares and from cognito-toolkit 1.x.
• llms.txt / llms-full.txt — machine-readable API reference shipped in the package.
• ARCHITECTURE — internal layout and the delegation rationale.