Middleware ports

Middleware ports

One factory, four ports: makeAuth(options) builds a per-instance middleware bundle on the subpaths koa, express, fetch, and lambda. The family mirrors dynamodb-toolkit's adapter ports, so an authenticated dynamodb REST surface composes with zero special glue in every deployment shape.

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

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

There are no module-level singletons — create as many bundles as you need (e.g. one per pool, or one per token type).

Options (all ports)

Option	Default	Meaning
verifier	required	An aws-jwt-verify verifier (CognitoJwtVerifier / JwtVerifier), or anything with an async verify(token) that resolves to a payload and throws on an invalid token.
authHeader	'Authorization'	Header carrying the bare token (no Bearer stripping — strip it in a custom source). Falsy disables the header source.
authCookie	'auth'	Cookie carrying the token; also the cookie the auth-cookie helpers write. Falsy disables both.
source	header → cookie	Custom token source (ctx / req / request / event in, token or null out). Overrides the header / cookie lookups.
setAuthCookieOptions	null	When set to an object ({} is meaningful), authenticated traffic refreshes the auth cookie automatically.
stateUserProperty	'user'	koa / express only — where the user lands (ctx.state[prop] / req[prop]).
throwOnError	false	Verification failures throw (aws-jwt-verify error classes) instead of yielding an anonymous request. An absent token never throws.

The bundle

Member	Semantics
getUser	Authenticates a request: the decoded payload or null. Koa/Express: a middleware placing it on the state property. Fetch/Lambda: a memoized async lookup. An authenticated payload carries _token (the raw JWT).
isAuthenticated	401 unless a user is present.
hasGroup(group)	401 without a user; 403 unless the cognito:groups claim contains group.
hasScope(scope)	401 without a user; 403 unless the space-separated scope claim contains scope.
isAllowed(validator)	Custom rule (ctx | req | request | event, groups, scopes) => boolean | Promise<boolean>; falsy → 401 (anonymous) / 403 (authenticated).
setAuthCookie(…)	Persist the current token into the auth cookie, skipped when the cookie already holds it. Signatures differ per port — see the port pages.
stateUserProperty	koa / express only — the resolved property name, for generic code.

Two execution models

• Chain middleware — koa and express. Guards are middleware in the chain after getUser; the user lives on ctx.state / req.
• Handler wrappers — fetch and lambda. Requests/events are not decorated (Fetch Requests are immutable, Lambda events stay pristine): getUser(request | event) is a per-request-memoized lookup (guards and handlers share one verification), guards wrap handlers, and denials are a Response / result envelope.

The auth cookie

Enables a "login once" flow: authenticate via a header once (e.g. after an OAuth2 redirect), persist the token as a cookie, and let subsequent requests authenticate from the cookie automatically. The cookie expires with the token (exp claim); Domain defaults to the request hostname. Koa/Express delegate cookie writing to the framework; Fetch/Lambda serialize in-house with Path=/ and HttpOnly by default.

See also

• Core-API — the framework-free makeGetUser and the verifier re-exports.
• Release notes.