@zephkelly/nuxt-authkit 0.0.1

package/README.md

@@ -0,0 +1,170 @@
+# @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](./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
+
+```ts
+// 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:
+
+```bash
+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.
+
+```ts
+// 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
+
+```ts
+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.
+
+On the client, the shipped plugin attaches the access token to same-origin requests
+and transparently refreshes + retries once on a 401:
+
+```ts
+const { accessToken, setAccessToken, clearAccessToken } = useAuthkitToken();
+```
+
+## Passwords
+
+```ts
+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](./SECURITY-AUDIT-JWT.md) for the audit this library's
+current design responds to, and [MIGRATION.md](./MIGRATION.md) for the resulting
+changes.

package/dist/module.d.mts

@@ -0,0 +1,6 @@
+import * as _nuxt_schema from '@nuxt/schema';
+import { ModuleOptions } from '../dist/runtime/types/module-options.js';
+
+declare const _default: _nuxt_schema.NuxtModule<ModuleOptions, ModuleOptions, false>;
+
+export { _default as default };

package/dist/module.json

@@ -0,0 +1,9 @@
+{
+  "name": "nuxt-authkit",
+  "configKey": "nuxtAuthkit",
+  "version": "0.0.1",
+  "builder": {
+    "@nuxt/module-builder": "1.0.2",
+    "unbuild": "3.6.1"
+  }
+}

package/dist/module.mjs

@@ -0,0 +1,80 @@
+import { defineNuxtModule, createResolver, updateRuntimeConfig, addServerImports, addServerHandler, addPlugin } from '@nuxt/kit';
+import { mergeRuntimeConfig } from '../dist/runtime/utils/get-module-options.js';
+
+const module = defineNuxtModule({
+  meta: {
+    name: "nuxt-authkit",
+    configKey: "nuxtAuthkit"
+  },
+  defaults: {
+    strategies: ["jwt"],
+    scrypt: {},
+    clientPlugin: true
+  },
+  setup(_options, _nuxt) {
+    const resolver = createResolver(import.meta.url);
+    _nuxt.options.alias = _nuxt.options.alias || {};
+    _nuxt.options.alias["#nuxt-authkit"] = resolver.resolve("./runtime/index");
+    _nuxt.hook("nitro:config", async (nitroConfig) => {
+      nitroConfig.experimental = nitroConfig.experimental || {};
+      nitroConfig.experimental.asyncContext = true;
+    });
+    const mergedRuntimeConfig = mergeRuntimeConfig(_options);
+    updateRuntimeConfig(mergedRuntimeConfig);
+    let getAuthkitUtil = null;
+    if (mergedRuntimeConfig?.nuxtAuthkit.strategies.includes("jwt")) {
+      getAuthkitUtil = {
+        name: "getAuthkit",
+        from: resolver.resolve("./runtime/service/utils/getJwtAsyncService")
+      };
+    }
+    addServerImports([
+      {
+        name: "createNuxtAuthkit",
+        from: resolver.resolve("./runtime/index")
+      },
+      {
+        name: "createJWTStrategy",
+        from: resolver.resolve("./runtime/strategy/jwt")
+      },
+      ...getAuthkitUtil ? [getAuthkitUtil] : []
+    ]);
+    addServerImports([
+      {
+        name: "hasAuthkitRole",
+        from: resolver.resolve("./runtime/helpers/request-middleware")
+      },
+      {
+        name: "hasAuthkitSession",
+        from: resolver.resolve("./runtime/helpers/request-middleware")
+      },
+      {
+        name: "rejectAuthkitRole",
+        from: resolver.resolve("./runtime/helpers/request-middleware")
+      }
+    ]);
+    addServerImports([
+      {
+        name: "hashPassword",
+        from: resolver.resolve("./runtime/utils/password")
+      },
+      {
+        name: "verifyPassword",
+        from: resolver.resolve("./runtime/utils/password")
+      }
+    ]);
+    addServerHandler({
+      route: "/api/_authkit/refresh",
+      method: "post",
+      handler: resolver.resolve("./runtime/server/api/_auth/refresh.post")
+    });
+    if (_options.clientPlugin !== false) {
+      addPlugin({
+        src: resolver.resolve("./runtime/plugins/auth-fetch.client"),
+        mode: "client"
+      });
+    }
+  }
+});
+
+export { module as default };

package/dist/runtime/composables/useAuthkitToken.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Access to the current access token.
+ *
+ * The refresh token deliberately has no presence here. It lives in an HttpOnly
+ * cookie, unreadable from JavaScript, and the server reads it from there and
+ * nowhere else. Mirroring it into `useState` would put a multi-day credential
+ * within reach of any XSS on the page (and serialise it into `window.__NUXT__`
+ * during SSR) in exchange for nothing.
+ */
+export declare function useAuthkitToken(): {
+    accessToken: Readonly<import("vue").Ref<string | null, string | null>>;
+    setAccessToken: (token: string | null) => void;
+    clearAccessToken: () => void;
+    getAuthHeader: () => {
+        Authorization: string;
+    } | {
+        Authorization?: undefined;
+    };
+    /**
+     * @deprecated The refresh token is HttpOnly and is never held in client
+     * state. Clearing the access token is what "log out locally" means here.
+     * This alias exists so 0.0.x callers keep compiling; it will be removed.
+     */
+    clearRefreshToken: () => void;
+};

package/dist/runtime/composables/useAuthkitToken.js

@@ -0,0 +1,31 @@
+import { useState } from "#app";
+import { readonly } from "vue";
+export function useAuthkitToken() {
+  const accessToken = useState("authkit-access-token", () => null);
+  function setAccessToken(token) {
+    accessToken.value = token;
+  }
+  function clearAccessToken() {
+    accessToken.value = null;
+  }
+  function getAuthHeader() {
+    if (accessToken.value) {
+      return {
+        Authorization: `Bearer ${accessToken.value}`
+      };
+    }
+    return {};
+  }
+  return {
+    accessToken: readonly(accessToken),
+    setAccessToken,
+    clearAccessToken,
+    getAuthHeader,
+    /**
+     * @deprecated The refresh token is HttpOnly and is never held in client
+     * state. Clearing the access token is what "log out locally" means here.
+     * This alias exists so 0.0.x callers keep compiling; it will be removed.
+     */
+    clearRefreshToken: clearAccessToken
+  };
+}

package/dist/runtime/helpers/request-middleware.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Require a valid session. Throws 401 otherwise.
+ */
+export declare function hasAuthkitSession(): Promise<void>;
+/**
+ * Require the caller to hold at least one of `roles` (or all of them when
+ * `requireAll`). Throws 401 without a valid session, 403 without the role.
+ */
+export declare function hasAuthkitRole(roles: string | string[], requireAll?: boolean): Promise<void>;
+/**
+ * Deny-filter: reject callers who hold any of `roles` (or all of them when
+ * `requireAll`).
+ *
+ * This is NOT an authentication gate — it is the inverse of one, and it requires
+ * a valid session to mean anything. Without the session check below, an
+ * unauthenticated request has no roles, "has no roles" reads as "does not hold
+ * the rejected role", and the guard waves it straight through: a banned user
+ * evades `rejectAuthkitRole('banned')` by simply dropping their Authorization
+ * header. Proving a caller does *not* hold a role first requires knowing who
+ * they are.
+ */
+export declare function rejectAuthkitRole(roles: string | string[], requireAll?: boolean): Promise<void>;

package/dist/runtime/helpers/request-middleware.js

@@ -0,0 +1,82 @@
+import { createError } from "h3";
+import { getAuthkit } from "../service/utils/getJwtAsyncService.js";
+import { hasRole } from "../roles/has-role.js";
+function isHttpError(error) {
+  return !!error && typeof error === "object" && "statusCode" in error;
+}
+export async function hasAuthkitSession() {
+  try {
+    const authkit = getAuthkit();
+    const tokenSet = await authkit.verify();
+    if (!tokenSet.valid) {
+      throw createError({
+        statusCode: 401,
+        message: "Unauthorized"
+      });
+    }
+  } catch (error) {
+    if (isHttpError(error)) {
+      throw error;
+    }
+    throw createError({
+      statusCode: 401,
+      message: "Unauthorized"
+    });
+  }
+}
+export async function hasAuthkitRole(roles, requireAll = false) {
+  try {
+    const authkit = getAuthkit();
+    const verificationResult = await authkit.verify();
+    if (!verificationResult.valid) {
+      throw createError({
+        statusCode: 401,
+        message: "Unauthorized"
+      });
+    }
+    const payloadRoles = verificationResult.payload?.roles || [];
+    const allowedRoles = Array.isArray(roles) ? roles : [roles];
+    if (!hasRole(payloadRoles, allowedRoles, requireAll)) {
+      throw createError({
+        statusCode: 403,
+        message: "Forbidden"
+      });
+    }
+  } catch (error) {
+    if (isHttpError(error)) {
+      throw error;
+    }
+    throw createError({
+      statusCode: 403,
+      message: "Forbidden"
+    });
+  }
+}
+export async function rejectAuthkitRole(roles, requireAll = false) {
+  try {
+    const authkit = getAuthkit();
+    const verificationResult = await authkit.verify();
+    if (!verificationResult.valid) {
+      throw createError({
+        statusCode: 401,
+        message: "Unauthorized"
+      });
+    }
+    const payloadRoles = verificationResult.payload?.roles || [];
+    const rejectedRoles = Array.isArray(roles) ? roles : [roles];
+    if (hasRole(payloadRoles, rejectedRoles, requireAll)) {
+      throw createError({
+        statusCode: 403,
+        message: "Forbidden"
+      });
+    }
+  } catch (error) {
+    if (isHttpError(error)) {
+      throw error;
+    }
+    throw createError({
+      statusCode: 403,
+      message: "Forbidden"
+    });
+  }
+}

package/dist/runtime/index.d.ts

@@ -0,0 +1,8 @@
+export { createNuxtAuthkit } from './service/index.js';
+export { createJWTStrategy } from './strategy/jwt/index.js';
+export type { AuthCallbacks, RefreshTokenLookup, RefreshTokenLookupResult } from './types/callbacks.js';
+export type { AuthkitCredentials, AuthkitUser } from './types/authkit-types.js';
+export type { TokenPayload, TokenSet, TokenMetadata, TokenUse } from './types/token.js';
+export type { AuthResult, VerifyAuthResult, AuthError, AuthErrorCode } from './types/index.js';
+export type { JWTAuthCallbacks } from './strategy/jwt/callback.js';
+export type { JwtStrategyConfig, JWTVerifyOptions, JWTRefreshOptions, JWTServerRevokeOptions } from './strategy/jwt/types.js';

package/dist/runtime/index.js

@@ -0,0 +1,2 @@
+export { createNuxtAuthkit } from "./service/index.js";
+export { createJWTStrategy } from "./strategy/jwt/index.js";

package/dist/runtime/plugins/auth-fetch.client.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Client-only. This plugin assigns `globalThis.$fetch`, and on the server that is
+ * a single process-wide object shared by every concurrent SSR request — one
+ * request's setup would overwrite another's, handing request A the token store
+ * closed over by request B. In the browser `globalThis` is the tab, so exactly
+ * one user's session is ever in scope.
+ *
+ * The `.client` suffix is what enforces that. Nuxt matches plugin mode on
+ * `/\.(server|client)(\.\w+)*$/` — a *dot*, not a hyphen. A file named
+ * `auth-fetch-client.ts` does not match, registers as mode 'all', and runs on SSR.
+ */
+declare const _default: import("nuxt/app").Plugin<Record<string, unknown>> & import("nuxt/app").ObjectPlugin<Record<string, unknown>>;
+export default _default;

package/dist/runtime/plugins/auth-fetch.client.js

@@ -0,0 +1,91 @@
+import { defineNuxtPlugin } from "#app";
+import { useAuthkitToken } from "../composables/useAuthkitToken.js";
+import { REFRESH_ENDPOINT, isSameOrigin, isRefreshRequest } from "./internal/request-target.js";
+export default defineNuxtPlugin(() => {
+  const tokenStore = useAuthkitToken();
+  let refreshPromise = null;
+  const origin = () => window.location.origin;
+  const performRefresh = async () => {
+    try {
+      const response = await $fetch.raw(REFRESH_ENDPOINT, {
+        method: "POST"
+      });
+      const newToken = response?._data?.data?.tokens?.accessToken;
+      if (newToken) {
+        tokenStore.setAccessToken(newToken);
+        return newToken;
+      }
+      return null;
+    } catch (error) {
+      tokenStore.clearAccessToken();
+      throw error;
+    } finally {
+      refreshPromise = null;
+    }
+  };
+  globalThis.$fetch = $fetch.create({
+    async onRequest({ options, request }) {
+      if (isRefreshRequest(request, origin())) {
+        return;
+      }
+      if (refreshPromise) {
+        await refreshPromise.catch(() => {
+        });
+      }
+      if (!isSameOrigin(request, origin())) {
+        return;
+      }
+      const token = tokenStore.accessToken.value;
+      if (token) {
+        options.headers = {
+          ...options.headers,
+          ...tokenStore.getAuthHeader()
+        };
+      }
+    },
+    async onResponse({ response, request }) {
+      if (!isRefreshRequest(request, origin())) {
+        return;
+      }
+      const newToken = response._data?.data?.tokens?.accessToken;
+      if (newToken) {
+        tokenStore.setAccessToken(newToken);
+      }
+    },
+    async onResponseError({ response, options, request }) {
+      if (isRefreshRequest(request, origin())) {
+        return;
+      }
+      if (response.status !== 401) return;
+      if (options.headers?.["x-retried"]) {
+        tokenStore.clearAccessToken();
+        return;
+      }
+      if (response._data?.error?.code === "REFRESH_TOKEN_EXPIRED" || response._data?.error?.recoverable === false) {
+        tokenStore.clearAccessToken();
+        return;
+      }
+      if (!refreshPromise) {
+        refreshPromise = performRefresh();
+      }
+      try {
+        const newToken = await refreshPromise;
+        if (!newToken) {
+          tokenStore.clearAccessToken();
+          return;
+        }
+        return await $fetch(request, {
+          ...options,
+          headers: {
+            ...options.headers,
+            "Authorization": `Bearer ${newToken}`,
+            "x-retried": "true"
+          }
+        });
+      } catch {
+        tokenStore.clearAccessToken();
+        return;
+      }
+    }
+  });
+});

package/dist/runtime/plugins/internal/request-target.d.ts

@@ -0,0 +1,16 @@
+export declare const REFRESH_ENDPOINT = "/api/_authkit/refresh";
+/**
+ * Whether a request is going to our own origin.
+ *
+ * The interceptor patches the global `$fetch`, so it sees every request the app
+ * makes — including third-party ones (payments, maps, analytics) and any URL an
+ * attacker managed to influence. Attaching the session token to those hands the
+ * user's credential to whoever is on the other end, and a permissive CORS policy
+ * on their side is all it takes for the call to succeed.
+ */
+export declare function isSameOrigin(request: unknown, origin: string): boolean;
+/**
+ * Whether a request targets our own refresh endpoint — the only response allowed
+ * to hand us a new session token.
+ */
+export declare function isRefreshRequest(request: unknown, origin: string): boolean;

package/dist/runtime/plugins/internal/request-target.js

@@ -0,0 +1,17 @@
+export const REFRESH_ENDPOINT = "/api/_authkit/refresh";
+function toUrl(request, origin) {
+  const raw = typeof request === "string" ? request : typeof Request !== "undefined" && request instanceof Request ? request.url : String(request);
+  try {
+    return new URL(raw, origin);
+  } catch {
+    return null;
+  }
+}
+export function isSameOrigin(request, origin) {
+  return toUrl(request, origin)?.origin === origin;
+}
+export function isRefreshRequest(request, origin) {
+  const url = toUrl(request, origin);
+  if (!url) return false;
+  return url.origin === origin && url.pathname === REFRESH_ENDPOINT;
+}

package/dist/runtime/roles/has-role.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Core function to check if a user has the specified role(s)
+ * Works with both arrays of roles and role objects with primary_role/roles properties
+ *
+ * @param {string[] | { primary_role?: string, roles?: string[] } | null | undefined} userRoles - User roles to check
+ * @param {string[]} requiredRoles - Role or array of roles to check against
+ * @param {boolean} requireAll - If true, user must have ALL specified roles; if false, user only needs ONE of the roles
+ * @returns {boolean} - True if user has the required role(s), false otherwise
+ */
+export declare function checkRole(userRoles: (string)[] | {
+    primary_role?: string;
+    roles?: (string)[];
+} | null | undefined, requiredRoles: string | string[], requireAll?: boolean): boolean;
+/**
+ * Server-side role checking function
+ *
+ * @param string[] payloadRoles - Roles from the token payload
+ * @param string[] roles - Role or array of roles to check against
+ * @returns {boolean} - True if user has the role, false otherwise
+ */
+export declare function hasRole(payloadRoles: string[] | undefined, roles: string[], requireAll?: boolean): boolean;

package/dist/runtime/roles/has-role.js

@@ -0,0 +1,51 @@
+import { createError } from "h3";
+import { consola } from "consola";
+export function checkRole(userRoles, requiredRoles, requireAll = false) {
+  if (!userRoles) {
+    return false;
+  }
+  if (!requiredRoles) {
+    return false;
+  }
+  const rolesToCheck = Array.isArray(requiredRoles) ? requiredRoles : [requiredRoles];
+  if (rolesToCheck.length === 0) {
+    return false;
+  }
+  if (Array.isArray(userRoles)) {
+    if (requireAll) {
+      return rolesToCheck.every((role) => userRoles.includes(role));
+    } else {
+      return rolesToCheck.some((role) => userRoles.includes(role));
+    }
+  }
+  const allUserRoles = [];
+  if (userRoles.primary_role) {
+    allUserRoles.push(userRoles.primary_role);
+  }
+  if (userRoles.roles && Array.isArray(userRoles.roles)) {
+    allUserRoles.push(...userRoles.roles);
+  }
+  if (requireAll) {
+    return rolesToCheck.every((role) => allUserRoles.includes(role));
+  } else {
+    return rolesToCheck.some((role) => allUserRoles.includes(role));
+  }
+}
+export function hasRole(payloadRoles, roles, requireAll = false) {
+  if (!roles) {
+    if (import.meta.server) {
+      throw createError({
+        statusCode: 500,
+        message: "Validation rules not provided"
+      });
+    } else if (import.meta.client || import.meta.browser) {
+      consola.error("[\x1B[31m authkit \x1B[0m] hasRole called without roles to check against");
+      return false;
+    }
+    return false;
+  }
+  if (!payloadRoles) {
+    return false;
+  }
+  return checkRole(payloadRoles, roles, requireAll);
+}

package/dist/runtime/server/api/_auth/refresh-handler.d.ts

@@ -0,0 +1,6 @@
+import { type H3Event } from 'h3';
+export declare function handleRefreshRequest(event: H3Event): Promise<{
+    status: string;
+    message: string;
+    data: import("../../../index.js").AuthResult;
+}>;