@devcoffee/nuxt-core 1.0.2 → 1.1.0

package/dist/module.d.ts

@@ -0,0 +1,300 @@
+import { CookieSerializeOptions } from '#devcoffee-core/runtime/server/adapters/http';
+import { OidcUserInfo } from '#devcoffee-core/runtime/server/adapters/oidc';
+import { ConsolaInstance, LogLevel as LogLevel$1, ConsolaOptions } from 'consola';
+
+interface AuthorizedUser {
+  id: string
+  sub: string
+  email: string
+  firstName: string
+  lastName: string
+  locale: string
+  language: string
+  timezone: string
+}
+
+type AuthStatus = 'unauthenticated' | 'authenticated'
+
+type AuthData = {
+  status: AuthStatus
+  tokenSet?: {
+    accessToken: string
+    tokenType: string
+    expiresAt: number
+    idToken: string
+    refreshToken: string
+    scopes: string[]
+  }
+}
+
+type SessionContext<TData = Record<string, unknown>> = {
+  id: string
+  auth: AuthData
+  user: AuthorizedUser
+  data: TData
+  issuedAt: number
+  expiresAt: number
+}
+
+type NuxtAuthOptions = {
+  /**
+   * Default Devcoffee Nuxt AuthTS option callbacks for session and user mapping.
+   * These can be overridden by passing custom callbacks to `NuxtAuthtsHandler()`.
+   * @since 1.0.0
+   */
+  session: (
+    session: Omit<SessionContext, 'auth'>,
+    auth: SessionContext['auth']
+  ) => Awaitable<Omit<SessionContext, 'auth' | 'issuedAt' | 'expiresAt'> & { isAuthenticated: boolean }>
+
+  /**
+   * Maps the OpenID Connect user info response to your local user schema.
+   *
+   * @param user - The raw user info response from the OpenID provider.
+   * @param opts - The token response containing access and ID tokens.
+   * @returns A normalized user object.
+   * @since 1.0.0
+   */
+  userInfo: (
+    user: AuthorizedUser,
+    opts: {
+      openidUser?: OidcUserInfo
+      tokenSet: Exclude<SessionContext['auth']['tokenSet'], undefined>
+    }
+  ) => Awaitable<AuthorizedUser>
+}
+
+type NuxtSessionContext<TData = Record<string, unknown>> = {
+  readonly id: string
+  readonly isAuthenticated: boolean
+  readonly user: AuthorizedUser
+  readonly data: TData
+}
+
+type NuxtSessionUpdateContext<TData = Record<string, unknown>> = DeepPartial<{
+  user: AuthorizedUser
+  data: TData
+}>
+
+/**
+ * ⚙️ OpenID Connect configuration options.
+ *
+ * Defines parameters used for client registration, discovery,
+ * and token exchange with the OpenID Provider.
+ *
+ * @since 1.0.0
+ */
+type OpenIdOptions = {
+  /** Client ID registered with the OpenID Provider. */
+  clientId: string
+
+  /** Client secret for token exchange (if applicable). */
+  clientSecret: string
+
+  /** Whether to use Proof Key for Code Exchange (PKCE) flow. */
+  usePkce: boolean
+
+  /** Code challenge method, e.g. `S256`. */
+  codeChallengeMethod: string
+
+  /** Scopes requested from the OpenID Provider. */
+  scopes: string[]
+
+  /** Redirect URI used after authorization. */
+  redirectUri: string
+
+  /** The `.well-known/openid-configuration` discovery URL. */
+  wellKnownUrl: string
+
+  /** Whether to automatically fetch user info after login. */
+  autoFetchUser: boolean
+
+  /**
+   * TTL in seconds for caching autoFetchUser results per session.
+   * A GET_SESSION within the TTL window does not trigger an OIDC provider call.
+   * Only applies when autoFetchUser is true.
+   * @default 300
+   * @since 1.0.0
+   */
+  autoFetchUserTtl: number
+
+  /** Whether to fetch user info immediately after token grant. */
+  fetchUserOnLogin: boolean
+
+  /**
+   * Window in milliseconds before token expiry at which a refresh is triggered.
+   * Tokens with expiresAt more than this many milliseconds in the future are
+   * considered fresh and the refresh path is skipped entirely.
+   * @default 60000
+   * @since 1.0.0
+   */
+  tokenRefreshBufferMs: number
+
+  /**
+   * When `true`, the token refresh mutex uses an atomic Redis NX write
+   * (`SET key value NX EX ttl`) via the IORedis native client accessor for
+   * true distributed exclusion across multiple server instances. When `false`
+   * (default), the existing optimistic lock (`hasItem` + `setItem`) is used.
+   *
+   * @remarks Only effective when the Nitro `cache` storage mount is backed by
+   * a Redis driver. Setting `true` with a non-Redis backend falls through to
+   * the optimistic path silently.
+   *
+   * @default false
+   * @since 1.0.0
+   */
+  distributedLock?: boolean
+
+  /** Cache configuration for storing OpenID metadata. */
+  cache: {
+    /** Cache key prefix for the metadata store. */
+    prefix: string
+    /** Expiry time in seconds for cached metadata. */
+    expires: number
+  }
+}
+
+/**
+ * 🍪 Session management configuration.
+ *
+ * Defines session storage, expiration, and cookie behavior
+ * for authentication session tracking.
+ *
+ * @since 1.0.0
+ */
+type SessionsOptions = {
+  /** Cookie name mappings used by the session handler. */
+  names: {
+    /** PKCE verifier cookie name. */
+    pkce: string
+    /** State cookie name. */
+    state: string
+    /** Session ID cookie name. */
+    sessionId: string
+    /** Redirect URL cookie name. */
+    redirectUrl: string
+  }
+
+  storage: {
+    name: string
+
+    /** Key prefix for session data in the storage backend. */
+    prefix: string
+  }
+
+  /** Session lifetime in seconds. */
+  expiresIn: number
+
+  /** Options for how session cookies are serialized. */
+  cookieOpts: CookieSerializeOptions
+
+  /**
+   * Secret used to HMAC-sign session ID cookies and derive the AES-256-GCM key
+   * for tokenSet encryption. When empty, signing and encryption are skipped.
+   * @since 1.0.0
+   */
+  secret?: string
+}
+
+/**
+ * 🔐 Authentication behavior configuration.
+ *
+ * Defines default redirect paths and URIs used for login/logout flow.
+ *
+ * @since 1.0.0
+ */
+type AuthOptions = {
+  /** Path to the login page. */
+  loginUri: string
+
+  /** Default redirect URI after successful login. */
+  defaultLoginRedirectUri: string
+
+  /** Default redirect URI after logout. */
+  defaultLogoutRedirectUri: string
+
+  /** Default anonymous user object. */
+  anonymousUser: AuthorizedUser
+
+  ignoreRegexPatterns: RegExp[]
+
+  ignoreRegexPatternsDev: RegExp[]
+}
+
+/**
+ * 🧩 Main configuration interface for the Nuxt AuthTS module.
+ *
+ * Combines OpenID Connect, session, and general authentication options.
+ *
+ * @since 1.0.0
+ */
+type AuthtsModuleOptions = {
+  /** Enable or disable the module */
+  enabled: boolean
+  openid: OpenIdOptions
+  sessions: SessionsOptions
+  auth: AuthOptions
+}
+
+interface AuthtsMiddlewareMeta {
+  /** Require authentication to access */
+  required?: boolean
+
+  /** Only accessible if unauthenticated (login/register pages) */
+  unauthenticatedOnly?: boolean
+
+  /** Restrict access to these roles */
+  roles?: string[]
+}
+
+type CoreLogLevel = LogLevel$1
+type CoreLogInstance = ConsolaInstance
+
+type LoggingOptions = {
+  tag: string
+  level: CoreLogLevel
+} & DeepPartial<Pick<ConsolaOptions, 'throttle' | 'throttleMin' | 'formatOptions'>>
+
+type NuxtCoreLogging = {
+  getLogger: (opts?: { tag?: string; level?: LogLevel }) => CoreLogInstance
+}
+
+type LoggingModuleOptions = {
+  server: LoggingOptions
+  ssr: LoggingOptions
+  client: LoggingOptions
+}
+
+type ModuleOptions = {
+  defaultLocale: string
+  defaultLanguage: string
+  defaultTimeZone: string
+  logging: LoggingModuleOptions
+  authts: AuthtsModuleOptions
+  formatters: GenericType
+}
+
+type ModulePublicRuntimeConfig = Pick<ModuleOptions, 'defaultLocale' | 'defaultTimeZone' | 'defaultLanguage'> & {
+  logging: ModuleOptions['logging']['client']
+
+  authts: Pick<
+    AuthtsModuleOptions['auth'],
+    | 'loginUri'
+    | 'defaultLoginRedirectUri'
+    | 'defaultLogoutRedirectUri'
+    | 'ignoreRegexPatterns'
+    | 'ignoreRegexPatternsDev'
+  > &
+    Pick<AuthtsModuleOptions['openid'], 'redirectUri'> & {
+      enabled: boolean
+      redirectCookie: string
+      sessionCookie: string
+    }
+}
+
+type InputModuleOptions = DeepPartial<ModuleOptions>
+
+declare const _default: any;
+
+export { _default as default };
+export type { AuthData, AuthorizedUser, AuthtsMiddlewareMeta, AuthtsModuleOptions, CoreLogInstance, CoreLogLevel, InputModuleOptions, LoggingModuleOptions, LoggingOptions, ModuleOptions, ModulePublicRuntimeConfig, NuxtAuthOptions, NuxtCoreLogging, NuxtSessionContext, NuxtSessionUpdateContext, SessionContext };

package/dist/module.json

@@ -1,6 +1,6 @@
 {
   "name": "nuxt-core",
-  "version": "1.0.2",
+  "version": "1.1.0",
   "configKey": "nuxtCore",
   "compatibility": {
     "nuxt": "^4.0.0"

package/dist/module.mjs

@@ -1,31 +1,118 @@
-import { useLogger, defineNuxtModule, createResolver, addServerImportsDir, addServerPlugin, addImportsDir, addPlugin } from '@nuxt/kit';
-import { merge } from 'lodash-es';
+import { addCustomTab } from '@nuxt/devtools-kit';
+import { defineNuxtModule, useLogger, createResolver, addServerImports, addServerImportsDir, addServerPlugin, addImportsDir, addPlugin, addRouteMiddleware, addTemplate, addServerHandler } from '@nuxt/kit';
+import { deepMerge, pick } from '../dist/runtime/utils.js';
 
-const version = "1.0.2";
+const version = "1.1.0";
 
-const defaultModuleOptions = {
-  logging: {
-    server: {
-      tag: "server",
-      level: 2
+const defaultLocale = "vi-VN";
+const defaultLanguage = "vi";
+const defaultTimeZone = "Asia/Ho_Chi_Minh";
+const loggingDefaults = {
+  server: {
+    tag: "server",
+    level: 2
+  },
+  ssr: {
+    tag: "app-ssr",
+    level: 2
+  },
+  client: {
+    tag: "app-client",
+    level: 2
+  }
+};
+const authtsDefaults = {
+  enabled: true,
+  openid: {
+    cache: {
+      prefix: "oidc-server-meta",
+      expires: 60 * 60 * 24
     },
-    ssr: {
-      tag: "app-ssr",
-      level: 2
+    wellKnownUrl: "",
+    clientId: "",
+    clientSecret: "",
+    redirectUri: "/authorize",
+    scopes: [],
+    usePkce: true,
+    autoFetchUser: true,
+    autoFetchUserTtl: 300,
+    fetchUserOnLogin: true,
+    tokenRefreshBufferMs: 6e4,
+    distributedLock: false,
+    codeChallengeMethod: "S256"
+  },
+  sessions: {
+    names: {
+      sessionId: "auths.ssid",
+      redirectUrl: "auths.redirect",
+      state: "auths.state",
+      pkce: "auths.pkce"
     },
-    client: {
-      tag: "app-client",
-      level: 2
-    }
+    storage: { name: "sessions", prefix: "session" },
+    expiresIn: 60 * 60 * 24 * 6,
+    // 6 days
+    cookieOpts: {
+      path: "/",
+      sameSite: "lax",
+      httpOnly: true,
+      secure: process.env.NODE_ENV === "production"
+    },
+    secret: ""
+  },
+  auth: {
+    loginUri: "/login",
+    defaultLoginRedirectUri: "/",
+    defaultLogoutRedirectUri: "/login",
+    anonymousUser: {
+      id: "anonymous",
+      email: "",
+      sub: "anonymous",
+      firstName: "Anonymous",
+      lastName: "User",
+      locale: defaultLocale,
+      language: defaultLanguage,
+      timezone: defaultTimeZone
+    },
+    ignoreRegexPatterns: [],
+    ignoreRegexPatternsDev: []
   }
 };
 function normalizedModuleOptions(...inputOpts) {
-  return merge({}, defaultModuleOptions, ...inputOpts);
+  return deepMerge(
+    {
+      defaultLocale,
+      defaultLanguage,
+      defaultTimeZone,
+      logging: loggingDefaults,
+      authts: authtsDefaults
+    },
+    ...inputOpts
+  );
+}
+function normalizePublicRuntimeConfig(inputOpts) {
+  const { enabled } = inputOpts.authts;
+  const { loginUri, defaultLoginRedirectUri, defaultLogoutRedirectUri, ignoreRegexPatterns, ignoreRegexPatternsDev } = inputOpts.authts.auth;
+  const { redirectUri } = inputOpts.authts.openid;
+  const { redirectUrl: redirectCookie, sessionId: sessionCookie } = inputOpts.authts.sessions.names;
+  return {
+    logging: { ...inputOpts.logging.client },
+    authts: {
+      enabled,
+      loginUri,
+      redirectUri,
+      sessionCookie,
+      redirectCookie,
+      defaultLoginRedirectUri,
+      defaultLogoutRedirectUri,
+      ignoreRegexPatterns,
+      ignoreRegexPatternsDev
+    },
+    ...pick(inputOpts, ["defaultLocale", "defaultTimeZone", "defaultLanguage"])
+  };
 }
 
 const moduleName = "nuxt-core";
 const configKey = "nuxtCore";
-const logger = useLogger(moduleName);
 const module = defineNuxtModule({
   meta: {
     name: moduleName,
@@ -35,40 +122,108 @@ const module = defineNuxtModule({
       nuxt: "^4.0.0"
     }
   },
-  // Default configuration options of the Nuxt module
-  defaults: {},
+  defaults: (_nuxt) => {
+    return normalizedModuleOptions({}, (_nuxt.options.runtimeConfig || {})[configKey] || {});
+  },
   setup(_options, _nuxt) {
+    const logger = useLogger();
     const resolver = createResolver(import.meta.url);
-    let normalizedRuntimeConfig = _nuxt.options.runtimeConfig || {};
-    const normalizedOptions = normalizedModuleOptions(_options, normalizedRuntimeConfig[configKey] || {});
-    normalizedRuntimeConfig = merge(normalizedRuntimeConfig, {
-      [configKey]: normalizedOptions,
+    const resolvedOptions = normalizedModuleOptions(
+      {},
+      _options,
+      (_nuxt.options.runtimeConfig || {})[configKey] || {}
+    );
+    _nuxt.options.runtimeConfig = deepMerge(_nuxt.options.runtimeConfig || {}, {
+      [configKey]: resolvedOptions,
       public: {
-        [configKey]: merge({}, { logging: normalizedOptions.logging.client })
+        [configKey]: normalizePublicRuntimeConfig(resolvedOptions)
       }
     });
-    _nuxt.options.runtimeConfig = normalizedRuntimeConfig;
-    const sharedAlias = {};
-    _nuxt.options.alias = merge(_nuxt.options.alias, sharedAlias);
-    _nuxt.options.typescript = merge(_nuxt.options.typescript, {
-      tsConfig: { compilerOptions: { types: [] } }
-    });
+    _nuxt.options.alias["#devcoffee-core"] = resolver.resolve("./runtime");
+    addServerImports([
+      {
+        from: resolver.resolve("./runtime/server/core/nuxtAuthtsHandler"),
+        name: "default",
+        as: "NuxtAuthtsHandler"
+      },
+      {
+        from: resolver.resolve("./runtime/server/core/nuxtForwardHandler"),
+        name: "default",
+        as: "NuxtForwardRequestHandler"
+      }
+    ]);
     addServerImportsDir(resolver.resolve("./runtime/server/composables"));
     addServerPlugin(resolver.resolve("./runtime/server/plugins/logging"));
-    addImportsDir(resolver.resolve("./runtime/app/composables"));
+    addServerPlugin(resolver.resolve("./runtime/server/plugins/authts"));
+    addImportsDir([resolver.resolve("./runtime/app/composables"), resolver.resolve("./runtime/app/utils")]);
+    addPlugin({
+      mode: "all",
+      name: "authts",
+      src: resolver.resolve("./runtime/app/plugins/authts")
+    });
     addPlugin({
       mode: "all",
       name: "devcoffee-nuxt-core-logging",
       src: resolver.resolve("./runtime/app/plugins/logging")
     });
-    _nuxt.hook("nitro:prepare:types", (opts) => {
-      opts.references.push({ path: resolver.resolve("./runtime/types/global.env.d.ts") });
-      opts.references.push({ path: resolver.resolve("./runtime/types/nitro.d.ts") });
+    addPlugin(
+      {
+        mode: "all",
+        name: "core-locale",
+        src: resolver.resolve("./runtime/app/plugins/locale")
+      },
+      { append: true }
+    );
+    addPlugin(
+      {
+        mode: "all",
+        name: "core-formatters",
+        src: resolver.resolve("./runtime/app/plugins/formatters")
+      },
+      { append: true }
+    );
+    addRouteMiddleware([{ name: "authts", path: resolver.resolve("./runtime/app/middleware/authts"), global: true }], {
+      prepend: true
+    });
+    const globalTypes = addTemplate({
+      filename: "types/devcoffee-global.d.ts",
+      src: resolver.resolve("./runtime/types/global.env.d.ts")
+    });
+    _nuxt.options.nitro = deepMerge(_nuxt.options.nitro || {}, {
+      typescript: {
+        tsConfig: {
+          include: [globalTypes.dst]
+        }
+      }
+    });
+    const nuxtTypes = addTemplate({
+      filename: "types/devcoffee-nuxt-core.d.ts",
+      src: resolver.resolve("./runtime/types/nuxt.d.ts")
+    });
+    const nitroTypes = addTemplate({
+      filename: "types/devcoffee-nitro-core.d.ts",
+      src: resolver.resolve("./runtime/types/nitro.d.ts")
     });
     _nuxt.hook("prepare:types", (opts) => {
-      opts.references.push({ path: resolver.resolve("./runtime/types/global.env.d.ts") });
-      opts.references.push({ path: resolver.resolve("./runtime/types/nuxt.d.ts") });
+      opts.references.push({ path: globalTypes.dst });
+      opts.references.push({ path: nuxtTypes.dst });
+      opts.references.push({ path: nitroTypes.dst });
     });
+    if (_nuxt.options?.devtools) {
+      addCustomTab({
+        name: "devcoffee-core-session",
+        title: "Devcoffee Session",
+        icon: "carbon:apps",
+        view: {
+          type: "iframe",
+          src: "/__devcoffee_core_session_devtools__"
+        }
+      });
+      addServerHandler({
+        route: "/__devcoffee_core_session_devtools__",
+        handler: resolver.resolve("./runtime/server/dev/route/session")
+      });
+    }
     logger.success("`%s` setup finished", moduleName);
   }
 });

package/dist/runtime/app/composables/useAuthContext.d.ts

@@ -0,0 +1,26 @@
+/**
+ * 🧩 Provides reactive authentication state and actions for user login and authorization.
+ *
+ * This composable integrates with your Nuxt authentication system (`/api/_auth/*` endpoints)
+ * and session context to perform login, handle token exchanges, and update user session state.
+ *
+ * @example
+ * ```ts
+ * const { login, authorize, isAuthenticated, processing } = useAuthContext()
+ *
+ * async function handleLogin() {
+ *   await login('/dashboard')
+ * }
+ * ```
+ * @param {string} [initiator] - Optional initiator for logging purposes.
+ * @since 1.0.0
+ */
+export declare function useAuthContext(initiator?: string): {
+    user: any;
+    session: any;
+    processing: any;
+    isAuthenticated: any;
+    login: (redirectTo?: string) => Promise<void>;
+    authorize: (parameters: URLSearchParams) => Promise<void>;
+    logout: () => Promise<void>;
+};