@zephkelly/nuxt-authkit

@zephkelly/nuxt-authkit

An authentication toolkit for Nuxt applications. JWT access/refresh tokens with rotating refresh tokens, HttpOnly cookie storage, role guards, and scrypt password hashing.

Upgrading from 0.0.x? Read MIGRATION.md first. This release logs every user out once — tokens minted by 0.0.x carry no typ claim and are now rejected — and three changes need action in consuming apps.

Setup

// nuxt.config.ts
export default defineNuxtConfig({
    modules: ['@zephkelly/nuxt-authkit'],

    nuxtAuthkit: {
        strategies: ['jwt'],
        strategy: {
            name: 'jwt',
            tokens: {
                access: { expiresIn: 900 },        // 15 minutes
                refresh: {
                    expiresIn: 604800,             // 7 days
                    rotate: true,                  // rotate on every refresh (default)
                    cookie: {
                        name: 'refreshToken',
                        secure: true,
                        httpOnly: true,            // forced on regardless
                        sameSite: 'strict'
                    }
                }
            },
            jwt: {
                algorithm: 'RS256',
                privateKey: process.env.JWT_PRIVATE_KEY!,
                publicKey: process.env.JWT_PUBLIC_KEY!
            }
        }
    }
});

Generate an RSA key pair:

openssl genpkey -algorithm RSA -pkeyopt rsa_keygen_bits:3072 -out private.pem
openssl rsa -pubout -in private.pem -out public.pem

Keep the private key in JWT_PRIVATE_KEY (or NUXT_NUXTAUTHKIT_STRATEGY_JWT_PRIVATE_KEY) — it belongs in the environment, never in a committed config or a published build output.

Wiring it up

Register the strategy in a Nitro plugin. The callbacks are where your app plugs in its own storage and user directory.

// server/plugins/auth.ts
export default defineNitroPlugin(() => {
    createNuxtAuthkit(
        createJWTStrategy({
            // Required: verify credentials.
            async onAuthenticate({ email, password }) {
                const user = await db.users.findByEmail(email);
                if (!user || !await verifyPassword(user.passwordHash, password)) {
                    return null;
                }
                return { id: user.id, roles: user.roles };
            },

            // Required: persist a refresh token. Store a HASH, not the token —
            // then a leaked database snapshot is not a set of live sessions.
            async onStoreRefreshToken(token, userId) {
                await db.refreshTokens.insert({ userId, hash: sha256(token) });
            },

            // Required: look one up.
            async onGetRefreshToken(token, userId) {
                const record = await db.refreshTokens.find(sha256(token));
                if (!record) return { valid: false };

                // Rotated away already but presented again → the token was stolen.
                // authkit responds by revoking the whole family via onRevokeTokenFamily.
                // Allow a short grace period, or concurrent refreshes log users out.
                if (record.consumedAt) {
                    const age = Date.now() - record.consumedAt;
                    return age < 10_000 ? { valid: true } : { valid: false, reused: true };
                }

                // Roles read fresh from the DB, so a ban applies on the next refresh
                // rather than whenever the user next logs in.
                return { valid: true, roles: await db.users.rolesOf(userId) };
            },

            // Strongly recommended: without this, logout cannot terminate a session
            // server-side and rotation never invalidates the old token.
            async onRemoveRefreshToken(token) {
                await db.refreshTokens.markConsumed(sha256(token));
            },

            // Recommended: theft response.
            async onRevokeTokenFamily(family) {
                await db.refreshTokens.revokeFamily(family);
            },

            // Recommended: admin force-logout. revokeServer() throws without it.
            async onRevokeServer({ userId }) {
                await db.refreshTokens.deleteAllForUser(userId);
            }
        })
    );
});

The library warns at startup about any recommended callback you have not implemented, and what the consequence is.

Protecting routes

export default defineEventHandler({
    onRequest: [
        () => hasAuthkitSession(),          // 401 without a valid session
        () => hasAuthkitRole('admin'),      // 401 unauthenticated, 403 without the role
        () => rejectAuthkitRole('banned')   // deny-filter; also 401 unauthenticated
    ],
    handler: async () => { /* ... */ }
});

rejectAuthkitRole is a deny-filter, not an authentication gate. It requires a valid session: proving a caller does not hold a role first requires knowing who they are.

Tokens

authenticate() sets the refresh token as an HttpOnly cookie and returns the access token. Never put the refresh token in a response body — from there it reaches JavaScript, and it is a multi-day credential.

Access and refresh tokens carry a signed typ claim, so a refresh token cannot be replayed as a Bearer access token.

The access token also carries sid: the refresh token's rotation family, minted once per authenticate() / issueTokens() and constant across every rotation. It is the one stable per-sign-in identifier a server can read off a Bearer request (access tokens have no jti), meant for correlating logs and sessions, never for access decisions. sid is reserved, like family.

On the client, the shipped plugin attaches the access token to same-origin requests and transparently refreshes + retries once on a 401:

const { accessToken, setAccessToken, clearAccessToken } = useAuthkitToken();

Passwords

const hash = await hashPassword(plain);
const ok = await verifyPassword(hash, plain);

scrypt via @adonisjs/hash. Cost parameters are configurable under nuxtAuthkit.scrypt; parameters are embedded in each stored hash, so raising them later does not invalidate existing passwords.

Security

See SECURITY-AUDIT-JWT.md for the audit this library's current design responds to, and MIGRATION.md for the resulting changes.