@devcoffee/nuxt-core 1.0.2 → 1.1.1

package/dist/runtime/app/plugins/locale.js

@@ -0,0 +1,39 @@
+import { defineNuxtPlugin, useRuntimeConfig, useState } from "#app";
+import { useAuthContext, useLogger, watch } from "#imports";
+export default defineNuxtPlugin(async (_nuxtApp) => {
+  const logger = useLogger({ tag: "plugin.locale", level: 3 });
+  const { defaultLocale, defaultLanguage, defaultTimeZone } = useRuntimeConfig().public.nuxtCore;
+  const localeState = useState("devecoffee.locale", () => ({
+    locale: defaultLocale,
+    language: defaultLanguage,
+    timeZone: defaultTimeZone
+  }));
+  watch(
+    localeState,
+    async (value) => {
+      await _nuxtApp.callHook("dfLocale:changed", value);
+    },
+    { deep: true }
+  );
+  _nuxtApp.hooks.addHooks({
+    "app:created": () => {
+      const { user } = useAuthContext();
+      [localeState.value.locale, localeState.value.language, localeState.value.timeZone] = [
+        user.value.locale,
+        user.value.language,
+        user.value.timezone
+      ];
+      logger.debug(`App created, updating locale = '${JSON.stringify(localeState.value)}'.`);
+    },
+    "session:changed": (session) => {
+      const { locale, language, timezone } = session.user;
+      [localeState.value.locale, localeState.value.language, localeState.value.timeZone] = [locale, language, timezone];
+      logger.debug(`Session changed, updating locale = '${JSON.stringify(localeState.value)}'.`);
+    }
+  });
+  _nuxtApp.provide("dfLocale", {
+    locale: localeState.value.locale,
+    language: localeState.value.language,
+    timeZone: localeState.value.timeZone
+  });
+});

package/dist/runtime/app/plugins/logging.d.ts

@@ -1,17 +1,25 @@
-import { type ConsolaInstance, type LogLevel } from 'consola';
-declare const _default: import("#app").Plugin<{
-    logging: {
-        getLogger: (opts?: {
-            tag?: string;
-            level?: LogLevel;
-        }) => ConsolaInstance;
-    };
-}> & import("#app").ObjectPlugin<{
-    logging: {
-        getLogger: (opts?: {
-            tag?: string;
-            level?: LogLevel;
-        }) => ConsolaInstance;
-    };
-}>;
+import type { NuxtCoreLogging } from '@devcoffee/nuxt-core';
+declare module 'vue' {
+    /**
+     * Provides access to logging utilities.
+     * @since 1.0.0
+     */
+    interface ComponentCustomProperties {
+        $logging: NuxtCoreLogging;
+    }
+}
+declare module '#app' {
+    interface NuxtApp {
+        /**
+         * Provides access to logging utilities.
+         * @since 1.0.0
+         */
+        $logging: NuxtCoreLogging;
+    }
+}
+/**
+ * 🧩 Nuxt plugin for logging utilities.
+ * @since 1.0.0
+ */
+declare const _default: any;
 export default _default;

package/dist/runtime/app/plugins/logging.js

@@ -7,7 +7,6 @@ function initLogger() {
     config = useRuntimeConfig(useRequestEvent()).nuxtCore.logging.ssr;
   } else {
     config = useRuntimeConfig().public.nuxtCore.logging;
-    console.log("Initializing logger with tag:", config);
   }
   const { tag = "app", ...opts } = config;
   return consola.create(opts).withTag(tag);

package/dist/runtime/app/utils/hashing.d.ts

@@ -0,0 +1 @@
+export declare function randomShortHash(length?: number): string;

package/dist/runtime/app/utils/hashing.js

@@ -0,0 +1,3 @@
+export function randomShortHash(length = 8) {
+  return crypto.randomUUID().replace(/-/g, "").substring(0, length);
+}

package/dist/runtime/server/adapters/http.d.ts

@@ -0,0 +1,5 @@
+export { createError, deleteCookie, eventHandler, getCookie, getQuery, getRequestHeaders, getRequestURL, proxyRequest, readBody, readFormData, sendNoContent, setCookie, } from 'h3';
+export type { EventHandlerRequest, H3Error, H3Event, ProxyOptions, RequestHeaders } from 'h3';
+export { defineNitroPlugin, useRuntimeConfig } from 'nitropack/runtime';
+export type { CoreLogLevel, NuxtAuthOptions } from '@devcoffee/nuxt-core';
+export type { CookieSerializeOptions } from 'cookie-es';

package/dist/runtime/server/adapters/http.js

@@ -0,0 +1,15 @@
+export {
+  createError,
+  deleteCookie,
+  eventHandler,
+  getCookie,
+  getQuery,
+  getRequestHeaders,
+  getRequestURL,
+  proxyRequest,
+  readBody,
+  readFormData,
+  sendNoContent,
+  setCookie
+} from "h3";
+export { defineNitroPlugin, useRuntimeConfig } from "nitropack/runtime";

package/dist/runtime/server/adapters/oidc.d.ts

@@ -0,0 +1,58 @@
+import * as client from 'openid-client';
+export type { TokenEndpointResponse, AuthorizationCodeGrantChecks } from 'openid-client';
+export type { ServerMetadata, ClientMetadata } from 'openid-client';
+export { Configuration } from 'openid-client';
+/**
+ * Module-owned type for OIDC userinfo response fields used by this module.
+ * Fields match exactly what helpers.fetchUserInfo() returns after mapping.
+ * No index signature — named fields only (avoids TypeScript index signature conflicts).
+ *
+ * @since 1.0.0
+ */
+export interface OidcUserInfo {
+    sub: string;
+    email: string;
+    id: string;
+    firstName: string;
+    lastName: string;
+}
+/** @since 1.0.0 */
+export declare const discovery: typeof client.discovery;
+/**
+ * Allows `openid-client` to use HTTP (non-TLS) discovery and token endpoints.
+ * Pass as `execute: [allowInsecureRequests]` in discovery options.
+ * Required for test fixtures that run a mock OIDC server on http://.
+ * Never pass this in production — production always uses HTTPS endpoints.
+ * @since 1.0.0
+ */
+export declare const allowInsecureRequests: typeof client.allowInsecureRequests;
+/** @since 1.0.0 */
+export declare const randomState: typeof client.randomState;
+/** @since 1.0.0 */
+export declare const randomPKCECodeVerifier: typeof client.randomPKCECodeVerifier;
+/** @since 1.0.0 */
+export declare const calculatePKCECodeChallenge: typeof client.calculatePKCECodeChallenge;
+/** @since 1.0.0 */
+export declare const buildAuthorizationUrl: typeof client.buildAuthorizationUrl;
+/** @since 1.0.0 */
+export declare const authorizationCodeGrant: typeof client.authorizationCodeGrant;
+/** @since 1.0.0 */
+export declare const refreshTokenGrant: typeof client.refreshTokenGrant;
+/**
+ * Revokes an OAuth token via the token revocation endpoint.
+ * Wraps client.tokenRevocation with the module-owned function name.
+ *
+ * @since 1.0.0
+ */
+export declare const revokeToken: typeof client.tokenRevocation;
+/**
+ * Fetches user info from the OIDC provider and maps to module-owned OidcUserInfo type.
+ * Internalizes all casts from UserInfoResponse non-standard fields (id, firstName, lastName).
+ *
+ * @param config - The openid-client Configuration instance.
+ * @param accessToken - The access token to use for the userinfo request.
+ * @param sub - The subject identifier of the authenticated user.
+ * @returns Mapped OidcUserInfo with empty strings for any missing optional fields.
+ * @since 1.0.0
+ */
+export declare function fetchUserInfo(config: client.Configuration, accessToken: string, sub: string): Promise<OidcUserInfo>;

package/dist/runtime/server/adapters/oidc.js

@@ -0,0 +1,21 @@
+import * as client from "openid-client";
+export { Configuration } from "openid-client";
+export const discovery = client.discovery;
+export const allowInsecureRequests = client.allowInsecureRequests;
+export const randomState = client.randomState;
+export const randomPKCECodeVerifier = client.randomPKCECodeVerifier;
+export const calculatePKCECodeChallenge = client.calculatePKCECodeChallenge;
+export const buildAuthorizationUrl = client.buildAuthorizationUrl;
+export const authorizationCodeGrant = client.authorizationCodeGrant;
+export const refreshTokenGrant = client.refreshTokenGrant;
+export const revokeToken = client.tokenRevocation;
+export async function fetchUserInfo(config, accessToken, sub) {
+  const oidUser = await client.fetchUserInfo(config, accessToken, sub);
+  return {
+    id: oidUser["id"] || "",
+    sub: oidUser.sub,
+    email: oidUser.email || "",
+    firstName: oidUser["firstName"] || "",
+    lastName: oidUser["lastName"] || ""
+  };
+}

package/dist/runtime/server/adapters/storage.d.ts

@@ -0,0 +1,39 @@
+import type { SessionContext } from '@devcoffee/nuxt-core';
+/**
+ * Retrieves session data from Nitro storage.
+ *
+ * @param storageName - The Nitro storage name (e.g. 'session').
+ * @param key - The storage key including prefix (e.g. 'prefix:sessionId').
+ * @returns The stored {@link SessionContext} if found, otherwise `null`.
+ * @since 1.0.0
+ */
+export declare function getSessionData(storageName: string, key: string): Promise<SessionContext | null>;
+/**
+ * Writes session data to Nitro storage with optional TTL.
+ *
+ * @param storageName - The Nitro storage name.
+ * @param key - The storage key including prefix.
+ * @param data - The {@link SessionContext} to store.
+ * @param ttl - Optional TTL in seconds. When omitted, storage default applies.
+ * @returns A promise that resolves when the write completes.
+ * @since 1.0.0
+ */
+export declare function setSessionData(storageName: string, key: string, data: SessionContext, ttl?: number): Promise<void>;
+/**
+ * Removes session data from Nitro storage.
+ *
+ * @param storageName - The Nitro storage name.
+ * @param key - The storage key including prefix.
+ * @returns A promise that resolves when removal completes.
+ * @since 1.0.0
+ */
+export declare function removeSessionData(storageName: string, key: string): Promise<void>;
+/**
+ * Checks whether session data exists in Nitro storage.
+ *
+ * @param storageName - The Nitro storage name.
+ * @param key - The storage key including prefix.
+ * @returns `true` if the key exists, `false` otherwise.
+ * @since 1.0.0
+ */
+export declare function hasSessionData(storageName: string, key: string): Promise<boolean>;

package/dist/runtime/server/adapters/storage.js

@@ -0,0 +1,14 @@
+import { useStorage } from "nitropack/runtime";
+export async function getSessionData(storageName, key) {
+  return useStorage(storageName).getItem(key);
+}
+export async function setSessionData(storageName, key, data, ttl) {
+  const opts = ttl !== void 0 ? { ttl } : void 0;
+  return useStorage(storageName).setItem(key, data, opts);
+}
+export async function removeSessionData(storageName, key) {
+  return useStorage(storageName).removeItem(key);
+}
+export async function hasSessionData(storageName, key) {
+  return useStorage(storageName).hasItem(key);
+}

package/dist/runtime/server/adapters/utils.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Recursively merges source objects into a new object based on target shape.
+ * Matches lodash merge semantics: arrays overwrite (no concat), undefined values skipped.
+ * Does NOT mutate the target argument.
+ *
+ * @param target - The base object (not mutated).
+ * @param sources - One or more partial source objects to merge in order.
+ * @returns A new merged object.
+ * @since 1.0.0
+ */
+export declare function deepMerge<T extends object>(target: T, ...sources: object[]): T;
+/**
+ * Returns a new object excluding the specified keys.
+ * Does NOT mutate the source object.
+ *
+ * @param obj - The source object.
+ * @param keys - Array of keys to exclude.
+ * @returns A new object without the excluded keys.
+ * @since 1.0.0
+ */
+export declare function omit<T extends object, K extends keyof T>(obj: T, keys: K[]): Omit<T, K>;
+/**
+ * Returns a new object containing only the specified keys.
+ * Does NOT mutate the source object.
+ *
+ * @param obj - The source object.
+ * @param keys - Array of keys to include.
+ * @returns A new object with only the picked keys.
+ * @since 1.0.0
+ */
+export declare function pick<T extends object, K extends keyof T>(obj: T, keys: K[]): Pick<T, K>;

package/dist/runtime/server/adapters/utils.js

@@ -0,0 +1,28 @@
+export function deepMerge(target, ...sources) {
+  const result = { ...target };
+  for (const source of sources) {
+    if (!source || typeof source !== "object") continue;
+    for (const key of Object.keys(source)) {
+      const srcVal = source[key];
+      const tgtVal = result[key];
+      if (srcVal !== null && typeof srcVal === "object" && !Array.isArray(srcVal) && tgtVal !== null && typeof tgtVal === "object" && !Array.isArray(tgtVal)) {
+        result[key] = deepMerge(tgtVal, srcVal);
+      } else if (srcVal !== void 0) {
+        result[key] = srcVal;
+      }
+    }
+  }
+  return result;
+}
+export function omit(obj, keys) {
+  return Object.fromEntries(Object.entries(obj).filter(([k]) => !keys.includes(k)));
+}
+export function pick(obj, keys) {
+  const result = {};
+  for (const key of keys) {
+    if (key in obj) {
+      result[key] = obj[key];
+    }
+  }
+  return result;
+}

package/dist/runtime/server/composables/useServerLogger.d.ts

@@ -1,6 +1,7 @@
 import { type ConsolaInstance, type LogLevel } from 'consola';
 import type { H3Event } from 'h3';
-export default function useServerLogger(event?: H3Event, opts?: {
+export default function useServerLogger(options?: Partial<{
+    event?: H3Event;
     tag?: string;
     level: LogLevel;
-}): ConsolaInstance;
+}>): ConsolaInstance;

package/dist/runtime/server/composables/useServerLogger.js

@@ -1,13 +1,13 @@
 import { consola } from "consola";
 import { useRuntimeConfig } from "nitropack/runtime";
 let globalServerLogger;
-export default function useServerLogger(event, opts) {
+export default function useServerLogger(options) {
+  const { tag, ...opts } = useRuntimeConfig(options?.event).nuxtCore.logging.server;
   if (!globalServerLogger) {
-    const { tag: tag2, ...opts2 } = useRuntimeConfig(event).nuxtCore.logging.server;
-    globalServerLogger = consola.create(opts2).withTag(tag2);
+    globalServerLogger = consola.create(opts).withTag(tag);
   }
-  const { tag, level } = opts || {};
   let _logger = globalServerLogger;
+  const { level } = opts || {};
   if (level != void 0) {
     _logger = _logger.create({ level });
   }

package/dist/runtime/server/core/crypto.d.ts

@@ -0,0 +1,70 @@
+/** Shape of an AES-256-GCM encrypted tokenSet stored in Nitro storage. */
+export type EncryptedTokenSet = {
+    encrypted: true;
+    iv: string;
+    authTag: string;
+    ciphertext: string;
+};
+/**
+ * Generates a cryptographically secure 256-bit session ID.
+ * Returns a 64-character lowercase hex string.
+ * Replaces uuid v4 generation (SEC-04, D-04).
+ *
+ * @returns {string} A 64-character lowercase hex string.
+ * @since 1.0.0
+ */
+export declare function generateSessionId(): string;
+/**
+ * Validates that a session ID matches the expected hex-64 format.
+ * Replaces uuid.validate() (SEC-04, D-05).
+ * UUID v4 format (36 chars with hyphens) is intentionally rejected.
+ *
+ * @param id - The session ID string to validate.
+ * @returns {boolean} True if the ID is a valid 64-character lowercase hex string.
+ * @since 1.0.0
+ */
+export declare function isValidSessionId(id: string): boolean;
+/**
+ * HMAC-SHA256 signs a session ID for use as a cookie value.
+ * Returns '{sessionId}.{hmacHex}' — exactly 129 characters (SEC-03, D-07, D-08).
+ *
+ * @param sessionId - The 64-character hex session ID to sign.
+ * @param secret - The HMAC signing secret from sessions.secret config.
+ * @returns {string} Signed cookie value in '{sessionId}.{hmac}' format.
+ * @since 1.0.0
+ */
+export declare function signSessionId(sessionId: string, secret: string): string;
+/**
+ * Verifies a session cookie value and returns the raw session ID if valid.
+ * Returns null if the cookie is undefined, malformed, or the HMAC does not match.
+ * When secret is empty, passes through the raw value for backward-compat (D-09).
+ * Uses timingSafeEqual to prevent timing attacks.
+ *
+ * @param cookieValue - The raw session cookie value from the request.
+ * @param secret - The HMAC signing secret from sessions.secret config.
+ * @returns {string | null} The session ID if valid, or null on failure.
+ * @since 1.0.0
+ */
+export declare function verifySessionId(cookieValue: string | undefined, secret: string): string | null;
+/**
+ * Encrypts a tokenSet object with AES-256-GCM using a key derived from sessions.secret.
+ * A random 12-byte IV is generated per encryption operation (SEC-05, D-12, D-13).
+ * The returned shape is stored verbatim in the tokenSet field of Nitro storage.
+ *
+ * @param tokenSet - The token set object to encrypt.
+ * @param secret - The encryption secret from sessions.secret config.
+ * @returns {EncryptedTokenSet} The encrypted token set with iv, authTag, and ciphertext.
+ * @since 1.0.0
+ */
+export declare function encryptTokenSet(tokenSet: object, secret: string): EncryptedTokenSet;
+/**
+ * Decrypts an EncryptedTokenSet and returns the parsed object, or null on any failure.
+ * Returns null on auth tag mismatch (tamper detection), malformed data, or any crypto error.
+ * Callers must treat null as inaccessible tokenSet — do not throw (SEC-05, D-15).
+ *
+ * @param encrypted - The encrypted token set to decrypt.
+ * @param secret - The decryption secret from sessions.secret config.
+ * @returns {object | null} The decrypted token set object, or null on failure.
+ * @since 1.0.0
+ */
+export declare function decryptTokenSet(encrypted: EncryptedTokenSet, secret: string): object | null;

package/dist/runtime/server/core/crypto.js

@@ -0,0 +1,55 @@
+import { createCipheriv, createDecipheriv, createHmac, hkdfSync, randomBytes, timingSafeEqual } from "node:crypto";
+function deriveAesKey(secret) {
+  return Buffer.from(hkdfSync("sha256", secret, Buffer.alloc(0), "devcoffee-authts-tokenset-v1", 32));
+}
+export function generateSessionId() {
+  return randomBytes(32).toString("hex");
+}
+export function isValidSessionId(id) {
+  return /^[0-9a-f]{64}$/i.test(id);
+}
+export function signSessionId(sessionId, secret) {
+  const sig = createHmac("sha256", secret).update(sessionId).digest("hex");
+  return `${sessionId}.${sig}`;
+}
+export function verifySessionId(cookieValue, secret) {
+  if (!cookieValue) return null;
+  if (!secret) return cookieValue;
+  const dotIndex = cookieValue.lastIndexOf(".");
+  if (dotIndex !== 64 || cookieValue.length !== 129) {
+    return null;
+  }
+  const sessionId = cookieValue.slice(0, 64);
+  const providedSig = cookieValue.slice(65);
+  const expected = createHmac("sha256", secret).update(sessionId).digest("hex");
+  const valid = timingSafeEqual(Buffer.from(providedSig, "hex"), Buffer.from(expected, "hex"));
+  return valid ? sessionId : null;
+}
+export function encryptTokenSet(tokenSet, secret) {
+  const key = deriveAesKey(secret);
+  const iv = randomBytes(12);
+  const cipher = createCipheriv("aes-256-gcm", key, iv);
+  const ciphertext = Buffer.concat([cipher.update(JSON.stringify(tokenSet), "utf8"), cipher.final()]);
+  const authTag = cipher.getAuthTag();
+  return {
+    encrypted: true,
+    iv: iv.toString("hex"),
+    authTag: authTag.toString("hex"),
+    ciphertext: ciphertext.toString("hex")
+  };
+}
+export function decryptTokenSet(encrypted, secret) {
+  try {
+    const key = deriveAesKey(secret);
+    const decipher = createDecipheriv("aes-256-gcm", key, Buffer.from(encrypted.iv, "hex"));
+    decipher.setAuthTag(Buffer.from(encrypted.authTag, "hex"));
+    const plain = Buffer.concat([
+      decipher.update(Buffer.from(encrypted.ciphertext, "hex")),
+      decipher.final()
+      // throws synchronously if auth tag invalid
+    ]).toString("utf8");
+    return JSON.parse(plain);
+  } catch {
+    return null;
+  }
+}

package/dist/runtime/server/core/helpers.d.ts

@@ -0,0 +1,194 @@
+import type { SessionContext } from '@devcoffee/nuxt-core';
+import type { ClientMetadata, ServerMetadata, TokenEndpointResponse } from '#devcoffee-core/server/adapters/oidc';
+/** Options used for session creation and validation. */
+type SessionCreateOptions = {
+    storageName: string;
+    storagePrefix: string;
+    expiresIn: number;
+    secret: string;
+};
+/**
+ * Check whether a candidate redirect URL is same-origin with the request URL.
+ *
+ * Uses the WHATWG URL constructor — malformed URLs and relative paths return false
+ * instead of throwing, guarding against attacker-controlled input.
+ *
+ * @param redirectUrl - The candidate redirect URL string (from query param or cookie).
+ * @param requestUrl - The trusted request URL from the h3 event.
+ * @returns `true` if both URLs share the same origin, `false` otherwise.
+ * @since 1.0.0
+ */
+export declare function isSameOrigin(redirectUrl: string, requestUrl: URL): boolean;
+/**
+ * Retrieve an existing session from storage.
+ *
+ * @param sessionId - The session ID string.
+ * @param opts - Options containing the storage prefix.
+ * @returns The stored {@link SessionContext} if found, otherwise `null`.
+ * @since 1.0.0
+ */
+export declare function getSession(sessionId: string, opts: Pick<SessionCreateOptions, 'storagePrefix' | 'storageName' | 'secret'>): Promise<any>;
+/**
+ * Validate or create a new session.
+ *
+ * - If the provided cookie value is missing or invalid, a new UUID is generated.
+ * - Expired sessions are reinitialized with a default unauthenticated context.
+ * - Session expiry is automatically updated and persisted.
+ *
+ * @param sessionCookieId - The session cookie value (may be undefined).
+ * @param opts - Session creation options including prefix and expiration time.
+ * @returns Object containing the resolved session ID and expiry date.
+ * @since 1.0.0
+ */
+export declare function validateSession(sessionCookieId: string | undefined, opts: SessionCreateOptions): Promise<SessionContext>;
+/**
+ * Update an existing session’s properties and refresh its expiry.
+ *
+ * Throws if the session ID does not exist.
+ *
+ * @param sessionId - The session ID.
+ * @param input - Partial update fields for the session (excluding ID, issuedAt, expiresAt).
+ * @param opts - Expiration configuration (in milliseconds).
+ * @returns The updated {@link SessionContext}.
+ * @throws {Error} If session cannot be found in storage.
+ * @since 1.0.0
+ */
+export declare function updateSession(sessionId: string, input: DeepPartial<Omit<SessionContext, 'id' | 'expiresAt' | 'issuedAt'>>, opts: SessionCreateOptions): Promise<SessionContext>;
+export declare function renewSession(sessionId: string, opts: SessionCreateOptions): Promise<SessionContext>;
+/**
+ * Delete a session from storage by ID.
+ *
+ * Removes the session entry from Nitro storage. Does NOT create a replacement.
+ * The Nitro request hook (`validateSession`) will create a fresh anonymous session
+ * on the next incoming request naturally.
+ *
+ * Used by the LOGOUT action to ensure the old session ID resolves to nothing
+ * in storage after logout — closes the zombie-session gap (SEC-02).
+ *
+ * @param sessionId - The session ID to delete.
+ * @param opts - Options containing the storage name and prefix.
+ * @returns A promise that resolves when deletion is complete (void).
+ * @since 1.0.0
+ */
+export declare function deleteSession(sessionId: string, opts: Pick<SessionCreateOptions, 'storageName' | 'storagePrefix'>): Promise<void>;
+/** Options for OpenID Connect discovery and caching. */
+type OpenIdDiscoveryOptions = {
+    cache: {
+        /** Cache key prefix. */
+        prefix: string;
+        /** Cache expiration time in seconds. */
+        expires: number;
+    };
+    clientId: string;
+    clientSecret: string;
+};
+/** Structure of stored OpenID metadata. */
+type OpenIDMetaStorageValue = {
+    server: ServerMetadata;
+    client: ClientMetadata;
+};
+/**
+ * Discover OpenID Connect configuration and cache it.
+ *
+ * Fetches `.well-known/openid-configuration` from the issuer if not cached.
+ *
+ * @param wellKnownUrl - The OpenID Connect discovery endpoint.
+ * @param opts - Discovery and cache options.
+ * @returns The cached or newly fetched server/client metadata.
+ * @since 1.0.0
+ */
+export declare function discoveryOpendId(wellKnownUrl: string, opts: OpenIdDiscoveryOptions): Promise<OpenIDMetaStorageValue>;
+/**
+ * Retrieve a reusable OpenID configuration object.
+ *
+ * @param wellKnownUrl - The OpenID Connect discovery endpoint.
+ * @param opts - Discovery and client configuration options.
+ * @returns An initialized `openid-client` Configuration instance.
+ * @since 1.0.0
+ */
+export declare function getOpenIdConfiguration(wellKnownUrl: string, opts: OpenIdDiscoveryOptions): Promise<any>;
+/** Result of a built authorization URL request. */
+type AuthorizationUrlResult = {
+    state: string;
+    authorizeUrl: string;
+    pkceCodeVerifier?: string;
+};
+/**
+ * Build an OpenID Connect authorization URL and update session status.
+ *
+ * Handles optional PKCE challenge and state generation.
+ *
+ * @param session - The current session context.
+ * @param opt - OpenID configuration and authorization parameters.
+ * @returns The generated authorization URL, state, and optional PKCE verifier.
+ * @since 1.0.0
+ */
+export declare function buildAuthorizationUrl(session: SessionContext, opt: OpenIdDiscoveryOptions & {
+    origin: URL;
+    wellKnownUrl: string;
+    redirectUri: string;
+    usePkce: boolean;
+    scopes: string[];
+    codeChallengeMethod: string;
+    sessionStorageName: string;
+    sessionStoragePrefix: string;
+    sessionExpires: number;
+    sessionSecret?: string;
+}): Promise<AuthorizationUrlResult>;
+/**
+ * Exchange an authorization code for tokens via the Authorization Code Grant.
+ *
+ * @param authorizeParams - Authorization code, state, and PKCE verification values.
+ * @param opts - OpenID discovery and PKCE configuration.
+ * @returns Token response from the OpenID Provider.
+ * @since 1.0.0
+ */
+export declare function authorizationCodeGrant(authorizeParams: {
+    code?: string;
+    state?: string;
+    checks: {
+        expectedState?: string;
+        pkceCodeVerifier?: string;
+    };
+}, opts: OpenIdDiscoveryOptions & {
+    codeChallengeMethod: string;
+    wellKnownUrl: string;
+    origin: URL;
+    redirectUri: string;
+    usePkce: boolean;
+}): Promise<any>;
+export declare function constructTokenSet(input: TokenEndpointResponse): {
+    tokenType: string;
+    idToken: any;
+    accessToken: any;
+    refreshToken: any;
+    scopes: any;
+    expiresAt: number;
+};
+export declare function refreshTokenIfNeeded(session: SessionContext, opts: {
+    wellKnownUrl: string;
+    cache: {
+        prefix: string;
+        expires: number;
+    };
+    clientId: string;
+    clientSecret: string;
+    tokenRefreshBufferMs: number;
+    distributedLock?: boolean;
+}): Promise<any>;
+/**
+ * Fetch user profile information from the OpenID Provider using the access token.
+ *
+ * @param tokenSet - The token response returned from the token endpoint.
+ * @param sub - The subject identifier of the authenticated user.
+ * @param opts - OpenID discovery and client configuration options.
+ * @returns Simplified user information (id, sub, email, first/last name).
+ * @since 1.0.0
+ */
+export declare function fetchUserInfo(accessToken: string, sub: string, opts: OpenIdDiscoveryOptions & {
+    wellKnownUrl: string;
+}): Promise<any>;
+export declare function revokeTokens(tokens: string[], opts: OpenIdDiscoveryOptions & {
+    wellKnownUrl: string;
+}): Promise<PromiseSettledResult<any>[]>;
+export {};