@zephkelly/nuxt-authkit 0.0.1

package/dist/runtime/server/api/_auth/refresh-handler.js

@@ -0,0 +1,44 @@
+import { createError, getHeader } from "h3";
+import { consola } from "consola";
+import { getAuthkit } from "../../../service/utils/getJwtAsyncService.js";
+function assertNotCrossSite(event) {
+  const secFetchSite = getHeader(event, "sec-fetch-site");
+  if (secFetchSite === "cross-site") {
+    throw createError({
+      statusCode: 403,
+      statusMessage: "Forbidden"
+    });
+  }
+}
+export async function handleRefreshRequest(event) {
+  assertNotCrossSite(event);
+  let refreshResult;
+  try {
+    const auth = getAuthkit();
+    refreshResult = await auth.refresh();
+  } catch (error) {
+    consola.error("[nuxt-authkit] Unexpected error while refreshing token:", error);
+    throw createError({
+      statusCode: 500,
+      statusMessage: "Internal Server Error"
+    });
+  }
+  if (!refreshResult.success) {
+    consola.debug("[nuxt-authkit] Refresh rejected:", refreshResult.error);
+    throw createError({
+      statusCode: 401,
+      statusMessage: "Unauthorized",
+      data: {
+        error: {
+          code: refreshResult.error?.code ?? "REFRESH_TOKEN_INVALID",
+          recoverable: refreshResult.error?.recoverable ?? false
+        }
+      }
+    });
+  }
+  return {
+    status: "ok",
+    message: "Token refreshed",
+    data: refreshResult
+  };
+}

package/dist/runtime/server/api/_auth/refresh.post.d.ts

@@ -0,0 +1,6 @@
+declare const _default: import("h3").EventHandler<import("h3").EventHandlerRequest, Promise<{
+    status: string;
+    message: string;
+    data: import("../../../index.js").AuthResult;
+}>>;
+export default _default;

package/dist/runtime/server/api/_auth/refresh.post.js

@@ -0,0 +1,5 @@
+import { eventHandler } from "h3";
+import { handleRefreshRequest } from "./refresh-handler.js";
+export default eventHandler(async (event) => {
+  return await handleRefreshRequest(event);
+});

package/dist/runtime/server/tsconfig.json

@@ -0,0 +1,3 @@
+{
+  "extends": "../../../.nuxt/tsconfig.server.json",
+}

package/dist/runtime/service/index.d.ts

@@ -0,0 +1,119 @@
+import type { H3Event } from 'h3';
+import type { AuthResult, VerifyAuthResult } from '../types/index.js';
+import type { IAuthStrategy } from '../strategy/types.js';
+import type { AuthkitCredentials } from '#nuxt-authkit';
+import type { IAuthServiceAsync } from './types/async-service.js';
+import type { Expand } from '../types/expand.js';
+/**
+ * Singleton Authentication Service
+ *
+ * Manages authentication using a pluggable strategy pattern.
+ * Types are automatically inferred from module augmentation.
+ *
+ * @example
+ * ```ts
+ * // 1. Define types once:
+ * declare module 'nuxt-auth-toolkit' {
+ *   interface AuthKitTypes {
+ *     User: MyUser
+ *     Credentials: MyCredentials
+ *   }
+ * }
+ *
+ * // 2. Use everywhere without type parameters:
+ * const auth = getNuxtAuthkit() // Automatically typed!
+ * ```
+ */
+export declare class AuthenticationService implements IAuthServiceAsync {
+    private static instance;
+    private static isInitialized;
+    private readonly strategy;
+    private constructor();
+    /**
+     * Initialize the singleton instance
+     * Must be called once during app startup
+     */
+    static init(strategy: IAuthStrategy): AuthenticationService;
+    /**
+     * Get the singleton instance
+     * Types are automatically inferred from module augmentation
+     */
+    static getInstance(): AuthenticationService;
+    /**
+     * Check if service is initialized
+     */
+    static isReady(): boolean;
+    /**
+     * Reset the singleton (useful for testing)
+     */
+    static reset(): void;
+    /**
+     * Get the strategy name
+     */
+    get strategyName(): string;
+    /**
+     * Authenticate user with credentials
+     */
+    authenticate(credentials: AuthkitCredentials, options?: {
+        accessExpiresIn?: number;
+        refreshExpiresIn?: number;
+    }, event?: H3Event): Promise<AuthResult>;
+    /**
+     * Verify a token
+     */
+    verify(event?: H3Event, options?: any): Promise<VerifyAuthResult>;
+    /**
+     * Verify a bare access token, with no request context.
+     *
+     * Synchronous by design: this is signature + claim validation only, and its
+     * callers (WebSocket upgrade handlers, workers) are often outside a request.
+     */
+    verifyToken(token: string): VerifyAuthResult;
+    /**
+     * Issue tokens for an already-identified user, bypassing credentials.
+     */
+    issueTokens(userId: string, options?: {
+        roles?: string[];
+        claims?: Record<string, unknown>;
+        accessExpiresIn?: number;
+        refreshExpiresIn?: number;
+    }, event?: H3Event): Promise<AuthResult>;
+    /**
+     * Refresh tokens
+     */
+    refresh(event?: H3Event, options?: any): Promise<AuthResult>;
+    /**
+     * Revoke/invalidate tokens
+     */
+    revoke(event?: H3Event): Promise<void>;
+    /**
+     * Revoke/invalidate tokens during logout (server initiated) - e.g. Nitro scheduled task
+     *
+     * Throws if the active strategy cannot perform server-side revocation, rather
+     * than resolving successfully having done nothing — an operator running an
+     * incident force-logout has to be able to trust the answer.
+     */
+    revokeServer(options: any, event?: H3Event): Promise<void>;
+}
+/**
+ * Factory function to create and initialize the singleton
+ * Types are automatically inferred from module augmentation
+ *
+ * @example
+ * ```ts
+ * // 1. Define your types once (in types/auth.ts):
+ * declare module 'nuxt-auth-toolkit' {
+ *   interface AuthKitTypes {
+ *     User: { id: number; email: string; name: string }
+ *     Credentials: { username: string; password: string }
+ *   }
+ * }
+ *
+ * // 2. Initialize (in server/plugins/auth.ts):
+ * export default defineNitroPlugin((nitroApp) => {
+ *   const strategy = new JwtStrategy({ ... }, callbacks)
+ *   createAuthenticationService(nitroApp, strategy) // Types inferred!
+ * })
+ * ```
+ */
+export declare function createNuxtAuthkit<TCredentials = AuthkitCredentials>(strategy: IAuthStrategy): Expand<IAuthServiceAsync<TCredentials>>;

package/dist/runtime/service/index.js

@@ -0,0 +1,170 @@
+import { useEvent } from "nitropack/runtime/internal/context";
+import { consola } from "consola";
+export class AuthenticationService {
+  static instance = null;
+  static isInitialized = false;
+  strategy;
+  constructor(strategy) {
+    this.strategy = strategy;
+  }
+  /**
+   * Initialize the singleton instance
+   * Must be called once during app startup
+   */
+  static init(strategy) {
+    if (this.isInitialized && this.instance) {
+      return this.instance;
+    }
+    this.instance = new AuthenticationService(
+      strategy
+    );
+    this.isInitialized = true;
+    consola.log({
+      message: `Using strategy: \x1B[32m${strategy.name} \x1B`,
+      tag: "\x1B[32m nuxt-authkit \x1B"
+    });
+    return this.instance;
+  }
+  /**
+   * Get the singleton instance
+   * Types are automatically inferred from module augmentation
+   */
+  static getInstance() {
+    if (!this.instance || !this.isInitialized) {
+      throw new Error(
+        "[nuxt-authkit] not initialized. Call createNuxtAuthkit() first in your Nitro plugin."
+      );
+    }
+    return this.instance;
+  }
+  /**
+   * Check if service is initialized
+   */
+  static isReady() {
+    return this.isInitialized && this.instance !== null;
+  }
+  /**
+   * Reset the singleton (useful for testing)
+   */
+  static reset() {
+    this.instance = null;
+    this.isInitialized = false;
+  }
+  /**
+   * Get the strategy name
+   */
+  get strategyName() {
+    return this.strategy.name;
+  }
+  // ========== Authentication Methods ==========
+  /**
+   * Authenticate user with credentials
+   */
+  async authenticate(credentials, options, event) {
+    const currentEvent = event ? event : typeof useEvent === "function" ? useEvent() : void 0;
+    try {
+      return await this.strategy.authenticate(credentials, currentEvent, options);
+    } catch (error) {
+      console.error("[nuxt-authkit] Authentication error:", error);
+      throw error;
+    }
+  }
+  /**
+   * Verify a token
+   */
+  async verify(event, options) {
+    const currentEvent = event ? event : typeof useEvent === "function" ? useEvent() : void 0;
+    try {
+      return await this.strategy.verify(currentEvent, options);
+    } catch (error) {
+      console.error("[nuxt-authkit] Token verification error:", error);
+      throw error;
+    }
+  }
+  /**
+   * Verify a bare access token, with no request context.
+   *
+   * Synchronous by design: this is signature + claim validation only, and its
+   * callers (WebSocket upgrade handlers, workers) are often outside a request.
+   */
+  verifyToken(token) {
+    if (typeof this.strategy.verifyToken !== "function") {
+      throw new TypeError(
+        `[nuxt-authkit] The "${this.strategy.name}" strategy does not support context-free token verification.`
+      );
+    }
+    return this.strategy.verifyToken(token);
+  }
+  /**
+   * Issue tokens for an already-identified user, bypassing credentials.
+   */
+  async issueTokens(userId, options, event) {
+    if (typeof this.strategy.issueTokens !== "function") {
+      throw new TypeError(
+        `[nuxt-authkit] The "${this.strategy.name}" strategy does not support issuing tokens without credentials.`
+      );
+    }
+    const currentEvent = event ? event : typeof useEvent === "function" ? useEvent() : void 0;
+    try {
+      return await this.strategy.issueTokens(userId, currentEvent, options);
+    } catch (error) {
+      console.error("[nuxt-authkit] Token issuance error:", error);
+      throw error;
+    }
+  }
+  /**
+   * Refresh tokens
+   */
+  async refresh(event, options) {
+    const currentEvent = event ? event : typeof useEvent === "function" ? useEvent() : void 0;
+    try {
+      return await this.strategy.refresh(currentEvent, options);
+    } catch (error) {
+      console.error("[nuxt-authkit] Token refresh error:", error);
+      throw error;
+    }
+  }
+  /**
+   * Revoke/invalidate tokens
+   */
+  async revoke(event) {
+    const currentEvent = event ? event : typeof useEvent === "function" ? useEvent() : void 0;
+    try {
+      await this.strategy.revoke(currentEvent);
+    } catch (error) {
+      console.error("[nuxt-authkit] Token revocation error:", error);
+      throw error;
+    }
+  }
+  /**
+   * Revoke/invalidate tokens during logout (server initiated) - e.g. Nitro scheduled task
+   *
+   * Throws if the active strategy cannot perform server-side revocation, rather
+   * than resolving successfully having done nothing — an operator running an
+   * incident force-logout has to be able to trust the answer.
+   */
+  async revokeServer(options, event) {
+    if (typeof this.strategy.revokeServer !== "function") {
+      throw new TypeError(
+        `[nuxt-authkit] The "${this.strategy.name}" strategy does not support server-initiated revocation.`
+      );
+    }
+    let currentEvent = event;
+    if (!currentEvent && typeof useEvent === "function") {
+      try {
+        currentEvent = useEvent();
+      } catch {
+        currentEvent = void 0;
+      }
+    }
+    try {
+      await this.strategy.revokeServer(options, currentEvent);
+    } catch (error) {
+      console.error("[nuxt-authkit] Server token revocation error:", error);
+      throw error;
+    }
+  }
+}
+export function createNuxtAuthkit(strategy) {
+  return AuthenticationService.init(strategy);
+}

package/dist/runtime/service/new-index.d.ts

@@ -0,0 +1,24 @@
+import type { H3Event } from "h3";
+import type { AuthResult, VerifyAuthResult } from "../types/index.js";
+import type { Expand } from "../types/expand.js";
+import type { AuthkitCredentials } from './../types/authkit-types.js';
+/**
+ * Base interface that all authentication strategies must implement
+ */
+export interface IAuthService<TCredentials = AuthkitCredentials> {
+    /**
+     * Authenticate user with credentials
+     * Returns tokens and user data on success
+     */
+    authenticate(credentials: TCredentials, event?: H3Event): Promise<Expand<AuthResult>>;
+    /**
+     * Verify a that the current authentication method is valid
+     */
+    verify(event?: H3Event): Promise<VerifyAuthResult>;
+    refresh(event?: H3Event): Promise<AuthResult>;
+    /**
+     * Revoke/invalidate tokens
+     * Used during logout
+     */
+    revoke(event?: H3Event): Promise<void>;
+}

package/dist/runtime/service/types/async-service.d.ts

@@ -0,0 +1,59 @@
+import type { AuthResult, VerifyAuthResult } from "../../types/index.js";
+import type { Expand } from "../../types/expand.js";
+import type { AuthkitCredentials } from './../../types/authkit-types.js';
+/**
+ * Base interface that auth service must implement when experimental 'asyncContext' is used,
+ * meaning event is captured via 'useEvent' internally at each method call. Use in nuxt/nitro
+ * context only.
+ */
+export interface IAuthServiceAsync<TCredentials = AuthkitCredentials, TServerRevokeOptions = {}, TVerifyOptions = {}, TRefreshOptions = {}> {
+    /**
+     * Authenticate user with credentials
+     * Returns tokens and user data on success
+     */
+    authenticate(credentials: TCredentials, options?: {
+        accessExpiresIn?: number;
+        refreshExpiresIn?: number;
+    }): Promise<Expand<AuthResult>>;
+    /**
+     * Verify a that the current authentication method is valid
+     */
+    verify(options?: Expand<TVerifyOptions>): Promise<VerifyAuthResult>;
+    /**
+     * Verify a bare access token with no request context — for callers that hold
+     * a token but no H3 event (WebSocket peers, background workers, signed asset
+     * URLs). Synchronous: no store lookup is involved, only signature and claims.
+     *
+     * Throws if the active strategy has no context-free token to verify.
+     */
+    verifyToken(token: string): VerifyAuthResult;
+    /**
+     * Issue a token pair for `userId` without presenting credentials, for flows
+     * where identity is already established (OAuth callback, accepted invite,
+     * impersonation, device linking).
+     *
+     * This authenticates nobody — the caller asserts the subject. Never reach it
+     * from a route that has not already proven who the user is.
+     */
+    issueTokens(userId: string, options?: {
+        roles?: string[];
+        claims?: Record<string, unknown>;
+        accessExpiresIn?: number;
+        refreshExpiresIn?: number;
+    }): Promise<Expand<AuthResult>>;
+    /**
+     * Exchange the refresh token for a new access token.
+     * The refresh token is rotated unless rotation is disabled.
+     */
+    refresh(options?: Expand<TRefreshOptions>): Promise<AuthResult>;
+    /**
+     * Revoke/invalidate tokens
+     * Used during logout
+     */
+    revoke(): Promise<void>;
+    /**
+     * Server-initiated revocation. Throws if the strategy has no
+     * `onRevokeServer` callback configured — it will not silently no-op.
+     */
+    revokeServer(options: Expand<TServerRevokeOptions>): Promise<void>;
+}

package/dist/runtime/service/types/sync-service.d.ts

@@ -0,0 +1,28 @@
+import type { H3Event } from "h3";
+import type { AuthResult, VerifyAuthResult } from "../../types/index.js";
+import type { Expand } from "../../types/expand.js";
+import type { AuthkitCredentials } from '../../types/authkit-types.js';
+export interface RevokeServerOptions {
+}
+/**
+ * Base interface that auth service must implement when experimental 'asyncContext' is used,
+ * meaning event is captured via 'useEvent' internally at each method call. Use in nuxt/nitro
+ * context only.
+ */
+export interface IAuthService<TCredentials = AuthkitCredentials> {
+    /**
+     * Authenticate user with credentials
+     * Returns tokens and user data on success
+     */
+    authenticate(credentials: TCredentials, event: H3Event): Promise<Expand<AuthResult>>;
+    /**
+     * Verify a that the current authentication method is valid
+     */
+    verify(event: H3Event): Promise<VerifyAuthResult>;
+    refresh(event: H3Event): Promise<AuthResult>;
+    /**
+     * Revoke/invalidate tokens during logout (client initiated)
+     */
+    revoke(event: H3Event): Promise<void>;
+    revokeServer(options: Expand<RevokeServerOptions>): Promise<void>;
+}

package/dist/runtime/service/utils/getJwtAsyncService.d.ts

@@ -0,0 +1,11 @@
+import type { IAuthServiceAsync } from '../types/async-service.js';
+import type { AuthkitCredentials } from '../../types/authkit-types.js';
+import type { Expand } from '../../types/expand.js';
+import type { JWTServerRevokeOptions, JWTVerifyOptions, JWTRefreshOptions } from '../../strategy/jwt/types.js';
+/**
+ * Alias for useAuthenticationService
+ * Provides a more Nuxt-friendly name
+ * Types are automatically inferred from module augmentation
+ * ```
+ */
+export declare function getAuthkit<TCredentials = AuthkitCredentials>(): Expand<IAuthServiceAsync<TCredentials, JWTServerRevokeOptions, JWTVerifyOptions, JWTRefreshOptions>>;

package/dist/runtime/service/utils/getJwtAsyncService.js

@@ -0,0 +1,16 @@
+import { AuthenticationService } from "../index.js";
+export function getAuthkit() {
+  const authService = AuthenticationService.getInstance();
+  return {
+    authenticate: (credentials, options) => authService.authenticate(credentials, options),
+    // `undefined` is passed explicitly for the event slot: the service resolves
+    // the ambient event itself, and passing options positionally here used to
+    // land them in that slot and break every verify({ accessToken }) call.
+    verify: (options) => authService.verify(void 0, options),
+    verifyToken: (token) => authService.verifyToken(token),
+    issueTokens: (userId, options) => authService.issueTokens(userId, options),
+    refresh: (options) => authService.refresh(void 0, options),
+    revoke: () => authService.revoke(),
+    revokeServer: (options) => authService.revokeServer(options)
+  };
+}

package/dist/runtime/storage/nitro.d.ts

@@ -0,0 +1,61 @@
+import type { AuthStorage, StorageOptions, StorageAdapter } from './types.js';
+/**
+ * Configuration for Nitro storage
+ */
+export interface NitroStorageConfig {
+    /**
+     * Prefix for all storage keys
+     * Useful for namespacing auth data
+     * @default 'auth'
+     */
+    prefix?: string;
+    /**
+     * Default TTL for items (in seconds)
+     * If not provided, items don't expire
+     */
+    ttl?: number;
+}
+/**
+ * AuthStorage implementation using Nitro's storage via dependency injection
+ *
+ * NOTE: not currently used by `JWTStrategy` — refresh-token persistence is
+ * delegated entirely to the `onStoreRefreshToken` / `onGetRefreshToken` /
+ * `onRemoveRefreshToken` callbacks. Kept as a general-purpose adapter.
+ *
+ * @example
+ * ```ts
+ * const storage = useStorage('redis')
+ * const authStorage = new NitroStorage(storage, {
+ *   prefix: 'auth',
+ *   ttl: 3600
+ * })
+ *
+ * // Keys are escaped, so a ':' inside an untrusted id cannot forge a namespace.
+ * await authStorage.set(userId, token)
+ * const token = await authStorage.get(userId)
+ * ```
+ */
+export declare class NitroStorage implements AuthStorage {
+    private readonly config;
+    private readonly storage;
+    constructor(storage: StorageAdapter, config?: NitroStorageConfig);
+    /**
+     * `:` is the namespace separator, so a key containing one could otherwise
+     * collide with — or overwrite — another namespace's entry when the key is
+     * derived from an untrusted identifier. Escape it (and the escape character)
+     * before joining.
+     */
+    private buildKey;
+    get(key: string): Promise<string | null>;
+    set(key: string, value: string, options?: StorageOptions): Promise<void>;
+    remove(key: string): Promise<void>;
+    /**
+     * Clear all items with this prefix
+     * Note: This only works efficiently with some drivers (filesystem, memory)
+     */
+    clear(): Promise<void>;
+    has(key: string): Promise<boolean>;
+    getMany(keys: string[]): Promise<Map<string, string | null>>;
+    setMany(entries: Array<[string, string]>, options?: StorageOptions): Promise<void>;
+    keys(): Promise<string[]>;
+}

package/dist/runtime/storage/nitro.js

@@ -0,0 +1,124 @@
+export class NitroStorage {
+  config;
+  storage;
+  constructor(storage, config = {}) {
+    this.storage = storage;
+    this.config = {
+      prefix: config.prefix ?? "auth",
+      ttl: config.ttl ?? 0
+    };
+  }
+  /**
+   * `:` is the namespace separator, so a key containing one could otherwise
+   * collide with — or overwrite — another namespace's entry when the key is
+   * derived from an untrusted identifier. Escape it (and the escape character)
+   * before joining.
+   */
+  buildKey(key) {
+    const escaped = key.replace(/\\/g, "\\\\").replace(/:/g, "\\:");
+    return this.config.prefix ? `${this.config.prefix}:${escaped}` : escaped;
+  }
+  async get(key) {
+    const fullKey = this.buildKey(key);
+    try {
+      const value = await this.storage.getItem(fullKey);
+      if (!value) {
+        return null;
+      }
+      if (typeof value === "object" && "data" in value && "expiresAt" in value) {
+        const wrapped = value;
+        if (Date.now() > wrapped.expiresAt) {
+          await this.storage.removeItem(fullKey);
+          return null;
+        }
+        return wrapped.data;
+      }
+      return typeof value === "string" ? value : JSON.stringify(value);
+    } catch (error) {
+      console.error(
+        `[NitroStorage] Error getting key "${fullKey}":`,
+        error
+      );
+      return null;
+    }
+  }
+  async set(key, value, options) {
+    const fullKey = this.buildKey(key);
+    try {
+      const ttl = options?.maxAge ?? this.config.ttl;
+      if (ttl > 0) {
+        const expiresAt = Date.now() + ttl * 1e3;
+        const data = {
+          data: value,
+          expiresAt
+        };
+        await this.storage.setItem(fullKey, data);
+      } else {
+        await this.storage.setItem(fullKey, value);
+      }
+    } catch (error) {
+      console.error(
+        `[NitroStorage] Error setting key "${fullKey}":`,
+        error
+      );
+      throw error;
+    }
+  }
+  async remove(key) {
+    const fullKey = this.buildKey(key);
+    try {
+      await this.storage.removeItem(fullKey);
+    } catch (error) {
+      console.error(
+        `[NitroStorage] Error removing key "${fullKey}":`,
+        error
+      );
+      throw error;
+    }
+  }
+  /**
+   * Clear all items with this prefix
+   * Note: This only works efficiently with some drivers (filesystem, memory)
+   */
+  async clear() {
+    try {
+      const keys = await this.storage.getKeys(`${this.config.prefix}:`);
+      await Promise.all(keys.map((key) => this.storage.removeItem(key)));
+    } catch (error) {
+      console.error("[NitroStorage] Error clearing storage:", error);
+      throw error;
+    }
+  }
+  async has(key) {
+    const value = await this.get(key);
+    return value !== null;
+  }
+  async getMany(keys) {
+    const results = /* @__PURE__ */ new Map();
+    await Promise.all(
+      keys.map(async (key) => {
+        const value = await this.get(key);
+        results.set(key, value);
+      })
+    );
+    return results;
+  }
+  async setMany(entries, options) {
+    await Promise.all(
+      entries.map(([key, value]) => this.set(key, value, options))
+    );
+  }
+  async keys() {
+    try {
+      const allKeys = await this.storage.getKeys(
+        `${this.config.prefix}:`
+      );
+      return allKeys.map(
+        (key) => key.startsWith(this.config.prefix + ":") ? key.slice(this.config.prefix.length + 1) : key
+      );
+    } catch (error) {
+      console.error("[NitroStorage] Error getting keys:", error);
+      return [];
+    }
+  }
+}