@devcoffee/nuxt-core 1.0.2 → 1.1.1

package/dist/module.d.mts

@@ -1,161 +1,300 @@
-import * as _nuxt_schema from '@nuxt/schema';
-import { LogLevel, ConsolaOptions } from 'consola';
+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';
 
-type LoggingOptions = {
-    tag: string;
-    level: LogLevel;
-} & DeepPartial<Pick<ConsolaOptions, 'throttle' | 'throttleMin' | 'formatOptions'>>;
-type ModuleOptions = {
-    logging: {
-        server: LoggingOptions;
-        ssr: LoggingOptions;
-        client: LoggingOptions;
-    };
-};
+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[]
+}
 
-declare const configKey: "nuxtCore";
-declare module 'nuxt/schema' {
-    interface RuntimeConfig {
-        [configKey]: ModuleOptions;
-    }
-    interface PublicRuntimeConfig {
-        [configKey]: {
-            logging: ModuleOptions['logging']['client'];
-        };
-    }
+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
 }
-declare const _default: _nuxt_schema.NuxtModule<{
-    logging?: {
-        server?: {
-            tag?: string | undefined;
-            level?: 0 | 1 | 2 | 3 | 4 | 5 | {
-                toString?: {} | undefined;
-                toFixed?: {} | undefined;
-                toExponential?: {} | undefined;
-                toPrecision?: {} | undefined;
-                valueOf?: {} | undefined;
-                toLocaleString?: {} | undefined;
-            } | undefined;
-            throttle?: number | undefined;
-            throttleMin?: number | undefined;
-            formatOptions?: {
-                [x: string]: unknown;
-                columns?: number | undefined;
-                date?: boolean | undefined;
-                colors?: boolean | undefined;
-                compact?: boolean | number | undefined;
-                errorLevel?: number | undefined;
-            } | undefined;
-        } | undefined;
-        ssr?: {
-            tag?: string | undefined;
-            level?: 0 | 1 | 2 | 3 | 4 | 5 | {
-                toString?: {} | undefined;
-                toFixed?: {} | undefined;
-                toExponential?: {} | undefined;
-                toPrecision?: {} | undefined;
-                valueOf?: {} | undefined;
-                toLocaleString?: {} | undefined;
-            } | undefined;
-            throttle?: number | undefined;
-            throttleMin?: number | undefined;
-            formatOptions?: {
-                [x: string]: unknown;
-                columns?: number | undefined;
-                date?: boolean | undefined;
-                colors?: boolean | undefined;
-                compact?: boolean | number | undefined;
-                errorLevel?: number | undefined;
-            } | undefined;
-        } | undefined;
-        client?: {
-            tag?: string | undefined;
-            level?: 0 | 1 | 2 | 3 | 4 | 5 | {
-                toString?: {} | undefined;
-                toFixed?: {} | undefined;
-                toExponential?: {} | undefined;
-                toPrecision?: {} | undefined;
-                valueOf?: {} | undefined;
-                toLocaleString?: {} | undefined;
-            } | undefined;
-            throttle?: number | undefined;
-            throttleMin?: number | undefined;
-            formatOptions?: {
-                [x: string]: unknown;
-                columns?: number | undefined;
-                date?: boolean | undefined;
-                colors?: boolean | undefined;
-                compact?: boolean | number | undefined;
-                errorLevel?: number | undefined;
-            } | undefined;
-        } | undefined;
-    } | undefined;
-}, {
-    logging?: {
-        server?: {
-            tag?: string | undefined;
-            level?: 0 | 1 | 2 | 3 | 4 | 5 | {
-                toString?: {} | undefined;
-                toFixed?: {} | undefined;
-                toExponential?: {} | undefined;
-                toPrecision?: {} | undefined;
-                valueOf?: {} | undefined;
-                toLocaleString?: {} | undefined;
-            } | undefined;
-            throttle?: number | undefined;
-            throttleMin?: number | undefined;
-            formatOptions?: {
-                [x: string]: unknown;
-                columns?: number | undefined;
-                date?: boolean | undefined;
-                colors?: boolean | undefined;
-                compact?: boolean | number | undefined;
-                errorLevel?: number | undefined;
-            } | undefined;
-        } | undefined;
-        ssr?: {
-            tag?: string | undefined;
-            level?: 0 | 1 | 2 | 3 | 4 | 5 | {
-                toString?: {} | undefined;
-                toFixed?: {} | undefined;
-                toExponential?: {} | undefined;
-                toPrecision?: {} | undefined;
-                valueOf?: {} | undefined;
-                toLocaleString?: {} | undefined;
-            } | undefined;
-            throttle?: number | undefined;
-            throttleMin?: number | undefined;
-            formatOptions?: {
-                [x: string]: unknown;
-                columns?: number | undefined;
-                date?: boolean | undefined;
-                colors?: boolean | undefined;
-                compact?: boolean | number | undefined;
-                errorLevel?: number | undefined;
-            } | undefined;
-        } | undefined;
-        client?: {
-            tag?: string | undefined;
-            level?: 0 | 1 | 2 | 3 | 4 | 5 | {
-                toString?: {} | undefined;
-                toFixed?: {} | undefined;
-                toExponential?: {} | undefined;
-                toPrecision?: {} | undefined;
-                valueOf?: {} | undefined;
-                toLocaleString?: {} | undefined;
-            } | undefined;
-            throttle?: number | undefined;
-            throttleMin?: number | undefined;
-            formatOptions?: {
-                [x: string]: unknown;
-                columns?: number | undefined;
-                date?: boolean | undefined;
-                colors?: boolean | undefined;
-                compact?: boolean | number | undefined;
-                errorLevel?: number | undefined;
-            } | undefined;
-        } | undefined;
-    } | undefined;
-}, false>;
+
+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 };