@rimelight/auth 0.0.8 → 0.0.9

package/dist/adapters/auth0.d.mts

@@ -111,5 +111,12 @@ export declare function mapAuth0PayloadToSession(payload: Record<string, any>, o
   permissionsClaim: string;
   defaultRole: string;
 }): UserSessionContext;
+export declare function getAuth0ConfigFromEnv(overrides?: Partial<Auth0AdapterOptions>): Auth0AdapterOptions;
+/**
+ * Creates an Auth0 auth adapter automatically configured from environment variables.
+ */
+export declare function createAuth0FromEnv(overrides?: Partial<Auth0AdapterOptions> & {
+  devFallback?: boolean;
+}): AuthAdapter;
 //#endregion
 export { decodeJwt };

package/dist/adapters/auth0.mjs

@@ -252,5 +252,60 @@ function mapAuth0PayloadToSession(payload, options) {
 		metadata: payload
 	};
 }
+function getEnv(key, fallback = "") {
+	if (typeof process !== "undefined" && process.env?.[key]) return process.env[key];
+	if (typeof import.meta !== "undefined" && import.meta.env?.[key]) return import.meta.env[key];
+	return fallback;
+}
+function getAuth0ConfigFromEnv(overrides = {}) {
+	return {
+		domain: overrides.domain || getEnv("AUTH0_DOMAIN", "rimelight.eu.auth0.com"),
+		audience: overrides.audience || (getEnv("AUTH0_USE_CUSTOM_AUDIENCE") === "true" ? getEnv("AUTH0_AUDIENCE") || void 0 : void 0),
+		clientId: overrides.clientId || getEnv("AUTH0_CLIENT_ID", ""),
+		clientSecret: overrides.clientSecret || getEnv("AUTH0_CLIENT_SECRET", ""),
+		rolesClaim: overrides.rolesClaim || getEnv("AUTH0_ROLES_CLAIM", "https://rimelight.com/roles"),
+		userTypeClaim: overrides.userTypeClaim || getEnv("AUTH0_USER_TYPE_CLAIM", "https://rimelight.com/user_type"),
+		permissionsClaim: overrides.permissionsClaim || "permissions",
+		sessionCookieName: overrides.sessionCookieName || "rimelight_session",
+		sessionSecret: overrides.sessionSecret || getEnv("AUTH0_SECRET", "rimelight_default_development_secret_key_32bytes_minimum_length"),
+		loginUrl: overrides.loginUrl || "/api/auth/login",
+		defaultRole: overrides.defaultRole || "user",
+		...overrides
+	};
+}
+/**
+* Creates an Auth0 auth adapter automatically configured from environment variables.
+*/
+function createAuth0FromEnv(overrides = {}) {
+	const config = getAuth0ConfigFromEnv(overrides);
+	const baseAdapter = auth0Auth(config);
+	if (!overrides.devFallback) return baseAdapter;
+	return {
+		name: "auth0",
+		options: config,
+		async getSession(req) {
+			const session = await baseAdapter.getSession(req);
+			if (session) return session;
+			if ((typeof process !== "undefined" && process.env?.["NODE_ENV"] === "development" || typeof import.meta !== "undefined" && import.meta.env?.DEV) && (!config.clientId || config.clientId === "" || config.clientId === "default_client_id")) return {
+				userId: "dev-admin-user",
+				email: "admin@rimelight.com",
+				name: "Admin (Dev)",
+				avatar: "https://cdn.rimelight.com/Images/default_avatar.png",
+				roles: [
+					"admin",
+					"owner",
+					"editor"
+				],
+				permissions: ["*"],
+				userType: "employee",
+				metadata: { isDev: true }
+			};
+			return null;
+		},
+		handleUnauthorized(req) {
+			return baseAdapter.handleUnauthorized?.(req) ?? new Response("Unauthorized", { status: 401 });
+		}
+	};
+}
 //#endregion
-export { auth0Auth, createAuth0AuthorizeUrl, createAuth0LogoutUrl, createSessionToken, decodeJwt, exchangeAuth0Code, loginWithAuth0Password, mapAuth0PayloadToSession, refreshAuth0Token, verifyAuth0Jwt, verifySessionToken };
+export { auth0Auth, createAuth0AuthorizeUrl, createAuth0FromEnv, createAuth0LogoutUrl, createSessionToken, decodeJwt, exchangeAuth0Code, getAuth0ConfigFromEnv, loginWithAuth0Password, mapAuth0PayloadToSession, refreshAuth0Token, verifyAuth0Jwt, verifySessionToken };

package/dist/adapters/cf-access.d.mts

@@ -9,4 +9,8 @@ export interface CfAccessAdapterOptions {
   loginUrl?: string | undefined;
 }
 export declare function cfAccessAuth(options?: CfAccessAdapterOptions): AuthAdapter;
+/**
+ * Creates a Cloudflare Access auth adapter automatically configured from environment variables.
+ */
+export declare function createCfAccessFromEnv(overrides?: Partial<CfAccessAdapterOptions>): AuthAdapter;
 //#endregion

package/dist/adapters/cf-access.mjs

@@ -62,5 +62,23 @@ function cfAccessAuth(options = {}) {
 		}
 	};
 }
+function getEnv(key, fallback = "") {
+	if (typeof process !== "undefined" && process.env?.[key]) return process.env[key];
+	if (typeof import.meta !== "undefined" && import.meta.env?.[key]) return import.meta.env[key];
+	return fallback;
+}
+/**
+* Creates a Cloudflare Access auth adapter automatically configured from environment variables.
+*/
+function createCfAccessFromEnv(overrides = {}) {
+	return cfAccessAuth({
+		teamDomain: overrides.teamDomain || getEnv("CF_ACCESS_TEAM_DOMAIN"),
+		aud: overrides.aud || getEnv("CF_ACCESS_AUD"),
+		verifyJwt: overrides.verifyJwt ?? (getEnv("CF_ACCESS_VERIFY_JWT") === "true" || typeof import.meta !== "undefined" && import.meta.env?.["CF_ACCESS_VERIFY_JWT"] === "true"),
+		adminEmails: overrides.adminEmails || (getEnv("CF_ACCESS_ADMIN_EMAILS") ? getEnv("CF_ACCESS_ADMIN_EMAILS").split(",").map((e) => e.trim()) : []),
+		defaultRole: overrides.defaultRole || "admin",
+		...overrides
+	});
+}
 //#endregion
-export { cfAccessAuth };
+export { cfAccessAuth, createCfAccessFromEnv };

package/dist/client/index.d.mts

@@ -0,0 +1,32 @@
+import { UserSessionContext } from "../types.mjs";
+//#region src/client/index.d.ts
+export interface AuthClientSession<TUser = UserSessionContext> {
+  user: TUser | null;
+  session: {
+    id: string;
+    userId: string;
+    roles?: string[];
+    userType?: string;
+  } | null;
+}
+export interface AuthClientOptions {
+  sessionEndpoint?: string;
+  meEndpoint?: string;
+  loginEndpoint?: string;
+  logoutEndpoint?: string;
+  fetch?: typeof fetch;
+}
+export interface AuthClient<TUser = UserSessionContext> {
+  getSession(): Promise<AuthClientSession<TUser>>;
+  getMe(): Promise<TUser | null>;
+  login(returnTo?: string, extraParams?: Record<string, string>): void;
+  signup(returnTo?: string, extraParams?: Record<string, string>): void;
+  signOut(returnTo?: string): void;
+}
+/**
+ * Universal browser-side Auth Client factory.
+ */
+export declare function createAuthClient<TUser = UserSessionContext>(options?: AuthClientOptions): AuthClient<TUser>;
+export declare const authClient: AuthClient<UserSessionContext>;
+//#endregion
+export { authClient as default };

package/dist/client/index.mjs

@@ -0,0 +1,62 @@
+//#region src/client/index.ts
+/**
+* Universal browser-side Auth Client factory.
+*/
+function createAuthClient(options = {}) {
+	const { sessionEndpoint = "/api/auth/session", meEndpoint = "/api/auth/me", loginEndpoint = "/api/auth/login", logoutEndpoint = "/api/auth/logout", fetch: customFetch = typeof fetch !== "undefined" ? fetch : void 0 } = options;
+	return {
+		async getSession() {
+			try {
+				if (!customFetch) return {
+					user: null,
+					session: null
+				};
+				const res = await customFetch(sessionEndpoint);
+				if (!res.ok) return {
+					user: null,
+					session: null
+				};
+				return await res.json();
+			} catch {
+				return {
+					user: null,
+					session: null
+				};
+			}
+		},
+		async getMe() {
+			try {
+				if (!customFetch) return null;
+				const res = await customFetch(meEndpoint);
+				if (!res.ok) return null;
+				return (await res.json())?.user ?? null;
+			} catch {
+				return null;
+			}
+		},
+		login(returnTo = "/", extraParams = {}) {
+			if (typeof window === "undefined") return;
+			const url = new URL(loginEndpoint, window.location.origin);
+			url.searchParams.set("returnTo", returnTo);
+			for (const [k, v] of Object.entries(extraParams)) url.searchParams.set(k, v);
+			window.location.href = url.toString();
+		},
+		signup(returnTo = "/", extraParams = {}) {
+			if (typeof window === "undefined") return;
+			const url = new URL(loginEndpoint, window.location.origin);
+			url.searchParams.set("screen_hint", "signup");
+			url.searchParams.set("returnTo", returnTo);
+			for (const [k, v] of Object.entries(extraParams)) url.searchParams.set(k, v);
+			window.location.href = url.toString();
+		},
+		signOut(returnTo = "/") {
+			if (typeof window === "undefined") return;
+			const url = new URL(logoutEndpoint, window.location.origin);
+			url.searchParams.set("returnTo", returnTo);
+			window.location.href = url.toString();
+		}
+	};
+}
+const authClient = createAuthClient();
+//#endregion
+export { authClient, authClient as default, createAuthClient };

package/dist/index.d.mts

@@ -1,8 +1,15 @@
-import { AuthAdapter, UserSessionContext, UserType } from "./types.mjs";
-import { Auth0AdapterOptions, Auth0AuthorizeUrlOptions, Auth0CodeExchangeOptions, Auth0PasswordLoginOptions, Auth0RefreshTokenOptions, Auth0TokenResponse, auth0Auth, createAuth0AuthorizeUrl, createAuth0LogoutUrl, createSessionToken, decodeJwt, exchangeAuth0Code, loginWithAuth0Password, mapAuth0PayloadToSession, refreshAuth0Token, verifyAuth0Jwt, verifySessionToken } from "./adapters/auth0.mjs";
-import { CfAccessAdapterOptions, cfAccessAuth } from "./adapters/cf-access.mjs";
+import { AuthAdapter, AuthMiddlewareOptions, RoleGuard, UserSessionContext, UserType } from "./types.mjs";
+import { Auth0AdapterOptions, Auth0AuthorizeUrlOptions, Auth0CodeExchangeOptions, Auth0PasswordLoginOptions, Auth0RefreshTokenOptions, Auth0TokenResponse, auth0Auth, createAuth0AuthorizeUrl, createAuth0FromEnv, createAuth0LogoutUrl, createSessionToken, decodeJwt, exchangeAuth0Code, getAuth0ConfigFromEnv, loginWithAuth0Password, mapAuth0PayloadToSession, refreshAuth0Token, verifyAuth0Jwt, verifySessionToken } from "./adapters/auth0.mjs";
+import { CfAccessAdapterOptions, cfAccessAuth, createCfAccessFromEnv } from "./adapters/cf-access.mjs";
 import { MockAuthOptions, mockAuth } from "./adapters/mock.mjs";
+import { AuthClient, AuthClientOptions, AuthClientSession, authClient, createAuthClient } from "./client/index.mjs";
 import { AccessControl, AccessRole, StatementMap, adminAc, createAccessControl, createPermissions, defaultStatements, evaluateAccess, hasPermission, hasRole, memberAc, ownerAc } from "./permissions/index.mjs";
 import { RESTRICTED_SET, STANDARD_RESTRICTED_GROUPS, createRestrictedUsernameSet, normalizeUsername } from "./plugins/reserved-usernames/index.mjs";
 import { CONSTRUCTION_GUEST_COOKIE, GuestEnv, isConstructionGuest, signInConstructionGuest } from "./plugins/construction-guest/index.mjs";
-export { AccessControl, AccessRole, Auth0AdapterOptions, Auth0AuthorizeUrlOptions, Auth0CodeExchangeOptions, Auth0PasswordLoginOptions, Auth0RefreshTokenOptions, Auth0TokenResponse, AuthAdapter, CONSTRUCTION_GUEST_COOKIE, CfAccessAdapterOptions, GuestEnv, MockAuthOptions, RESTRICTED_SET, STANDARD_RESTRICTED_GROUPS, StatementMap, UserSessionContext, UserType, adminAc, auth0Auth, cfAccessAuth, createAccessControl, createAuth0AuthorizeUrl, createAuth0LogoutUrl, createPermissions, createRestrictedUsernameSet, createSessionToken, decodeJwt, defaultStatements, evaluateAccess, exchangeAuth0Code, hasPermission, hasRole, isConstructionGuest, loginWithAuth0Password, mapAuth0PayloadToSession, memberAc, mockAuth, normalizeUsername, ownerAc, refreshAuth0Token, signInConstructionGuest, verifyAuth0Jwt, verifySessionToken };
+import { authMiddleware } from "./middleware/index.mjs";
+import { RimelightAuthPlugin, RimelightAuthPluginOptions } from "./vite.mjs";
+//#region src/index.d.ts
+export declare const auth: AuthAdapter;
+export declare const authAdapter: AuthAdapter;
+//#endregion
+export { AccessControl, AccessRole, Auth0AdapterOptions, Auth0AuthorizeUrlOptions, Auth0CodeExchangeOptions, Auth0PasswordLoginOptions, Auth0RefreshTokenOptions, Auth0TokenResponse, AuthAdapter, AuthClient, AuthClientOptions, AuthClientSession, AuthMiddlewareOptions, CONSTRUCTION_GUEST_COOKIE, CfAccessAdapterOptions, GuestEnv, MockAuthOptions, RESTRICTED_SET, RimelightAuthPlugin, RimelightAuthPluginOptions, RoleGuard, STANDARD_RESTRICTED_GROUPS, StatementMap, UserSessionContext, UserType, adminAc, auth as default, auth0Auth, authClient, authMiddleware, cfAccessAuth, createAccessControl, createAuth0AuthorizeUrl, createAuth0FromEnv, createAuth0LogoutUrl, createAuthClient, createCfAccessFromEnv, createPermissions, createRestrictedUsernameSet, createSessionToken, decodeJwt, defaultStatements, evaluateAccess, exchangeAuth0Code, getAuth0ConfigFromEnv, hasPermission, hasRole, isConstructionGuest, loginWithAuth0Password, mapAuth0PayloadToSession, memberAc, mockAuth, normalizeUsername, ownerAc, refreshAuth0Token, signInConstructionGuest, verifyAuth0Jwt, verifySessionToken };

package/dist/index.mjs

@@ -1,8 +1,28 @@
-import { auth0Auth, createAuth0AuthorizeUrl, createAuth0LogoutUrl, createSessionToken, decodeJwt, exchangeAuth0Code, loginWithAuth0Password, mapAuth0PayloadToSession, refreshAuth0Token, verifyAuth0Jwt, verifySessionToken } from "./adapters/auth0.mjs";
-import { cfAccessAuth } from "./adapters/cf-access.mjs";
+import { auth0Auth, createAuth0AuthorizeUrl, createAuth0FromEnv, createAuth0LogoutUrl, createSessionToken, decodeJwt, exchangeAuth0Code, getAuth0ConfigFromEnv, loginWithAuth0Password, mapAuth0PayloadToSession, refreshAuth0Token, verifyAuth0Jwt, verifySessionToken } from "./adapters/auth0.mjs";
+import { cfAccessAuth, createCfAccessFromEnv } from "./adapters/cf-access.mjs";
 import { mockAuth } from "./adapters/mock.mjs";
+import { authClient, createAuthClient } from "./client/index.mjs";
 import "./types.mjs";
 import { AccessControl, adminAc, createAccessControl, createPermissions, defaultStatements, evaluateAccess, hasPermission, hasRole, memberAc, ownerAc } from "./permissions/index.mjs";
 import { RESTRICTED_SET, STANDARD_RESTRICTED_GROUPS, createRestrictedUsernameSet, normalizeUsername } from "./plugins/reserved-usernames/index.mjs";
 import { CONSTRUCTION_GUEST_COOKIE, isConstructionGuest, signInConstructionGuest } from "./plugins/construction-guest/index.mjs";
-export { AccessControl, CONSTRUCTION_GUEST_COOKIE, RESTRICTED_SET, STANDARD_RESTRICTED_GROUPS, adminAc, auth0Auth, cfAccessAuth, createAccessControl, createAuth0AuthorizeUrl, createAuth0LogoutUrl, createPermissions, createRestrictedUsernameSet, createSessionToken, decodeJwt, defaultStatements, evaluateAccess, exchangeAuth0Code, hasPermission, hasRole, isConstructionGuest, loginWithAuth0Password, mapAuth0PayloadToSession, memberAc, mockAuth, normalizeUsername, ownerAc, refreshAuth0Token, signInConstructionGuest, verifyAuth0Jwt, verifySessionToken };
+import { authMiddleware } from "./middleware/index.mjs";
+import "./vite.mjs";
+//#region src/index.ts
+let _defaultAuth = null;
+function getDefaultAuth() {
+	if (!_defaultAuth) _defaultAuth = typeof process !== "undefined" && Boolean(process.env?.["AUTH0_DOMAIN"]) || typeof import.meta !== "undefined" && Boolean(import.meta.env?.["AUTH0_DOMAIN"]) ? createAuth0FromEnv({ devFallback: true }) : createCfAccessFromEnv();
+	return _defaultAuth;
+}
+const auth = {
+	name: "auto",
+	async getSession(req) {
+		return getDefaultAuth().getSession(req);
+	},
+	handleUnauthorized(req) {
+		return getDefaultAuth().handleUnauthorized?.(req) ?? new Response("Unauthorized", { status: 401 });
+	}
+};
+const authAdapter = auth;
+//#endregion
+export { AccessControl, CONSTRUCTION_GUEST_COOKIE, RESTRICTED_SET, STANDARD_RESTRICTED_GROUPS, adminAc, auth, auth as default, auth0Auth, authAdapter, authClient, authMiddleware, cfAccessAuth, createAccessControl, createAuth0AuthorizeUrl, createAuth0FromEnv, createAuth0LogoutUrl, createAuthClient, createCfAccessFromEnv, createPermissions, createRestrictedUsernameSet, createSessionToken, decodeJwt, defaultStatements, evaluateAccess, exchangeAuth0Code, getAuth0ConfigFromEnv, hasPermission, hasRole, isConstructionGuest, loginWithAuth0Password, mapAuth0PayloadToSession, memberAc, mockAuth, normalizeUsername, ownerAc, refreshAuth0Token, signInConstructionGuest, verifyAuth0Jwt, verifySessionToken };

package/dist/middleware/index.d.mts

@@ -0,0 +1,20 @@
+import { AuthMiddlewareOptions } from "../types.mjs";
+//#region src/middleware/index.d.ts
+/**
+ * Universal Authentication & Authorization middleware for Hono applications.
+ *
+ * @example
+ *   import { authMiddleware } from "@rimelight/auth/middleware"
+ *   import { auth } from "#auth/auth"
+ *
+ *   app.use(
+ *     authMiddleware({
+ *       auth,
+ *       roleGuards: {
+ *         "/admin": ["admin", "owner"]
+ *       }
+ *     })
+ *   )
+ */
+export declare const authMiddleware: (options?: AuthMiddlewareOptions) => (c: any, next: () => Promise<any> | any) => Promise<Response | any>;
+//#endregion

package/dist/middleware/index.mjs

@@ -0,0 +1,174 @@
+import { isConstructionGuest } from "../plugins/construction-guest/index.mjs";
+//#region src/middleware/index.ts
+const STATIC_ASSET_REGEX = /\.(css|js|map|png|jpg|jpeg|gif|svg|webp|woff|woff2|ttf|ico|json|webmanifest)$/i;
+const DEFAULT_IGNORED_ROUTES = ["/docs/"];
+const DEFAULT_PROTECTED_ROUTES = ["/internal"];
+const DEFAULT_GUEST_ONLY_ROUTES = ["/auth/sign-in", "/auth/sign-up"];
+function matchesPattern(path, pattern) {
+	if (typeof pattern === "function") return pattern(path);
+	if (typeof pattern === "string") return path.startsWith(pattern) || path.includes(pattern);
+	return pattern.test(path);
+}
+/**
+* Universal Authentication & Authorization middleware for Hono applications.
+*
+* @example
+*   import { authMiddleware } from "@rimelight/auth/middleware"
+*   import { auth } from "#auth/auth"
+*
+*   app.use(
+*     authMiddleware({
+*       auth,
+*       roleGuards: {
+*         "/admin": ["admin", "owner"]
+*       }
+*     })
+*   )
+*/
+const authMiddleware = (options = {}) => {
+	const { auth, allowConstructionGuest = true, skipStaticAssets = true, ignoredRoutes = DEFAULT_IGNORED_ROUTES, protectedRoutes = DEFAULT_PROTECTED_ROUTES, roleGuards = {}, guestOnlyRoutes = DEFAULT_GUEST_ONLY_ROUTES, authRedirectUrl = "/auth/sign-in", signInUrl = "/auth/sign-in", homeUrl = "/", onUnauthorized, onForbidden } = options;
+	return async (c, next) => {
+		const rawUrl = c?.req?.url || "http://localhost/";
+		const pathname = new URL(rawUrl).pathname;
+		const isApi = pathname.startsWith("/api/");
+		if (skipStaticAssets) {
+			if (pathname.startsWith("/_astro/") || pathname.startsWith("/assets/") || pathname === "/favicon.ico" || pathname.startsWith("/open-graph/") || STATIC_ASSET_REGEX.test(pathname)) return await next();
+		}
+		if (typeof ignoredRoutes === "function" ? ignoredRoutes(pathname) : ignoredRoutes.some((pattern) => matchesPattern(pathname, pattern))) {
+			if (typeof c?.set === "function") {
+				c.set("user", null);
+				c.set("session", null);
+			}
+		} else {
+			let sessionCtx = null;
+			if (auth) try {
+				if (typeof auth === "function") sessionCtx = await auth(c);
+				else if (typeof auth.getSession === "function") {
+					const req = c.req?.raw || c.req;
+					sessionCtx = await auth.getSession(req);
+				}
+			} catch (err) {
+				console.error("[authMiddleware] Failed to resolve session:", err);
+			}
+			let isGuest = false;
+			if (!sessionCtx && allowConstructionGuest) try {
+				isGuest = await isConstructionGuest(c);
+			} catch {
+				isGuest = false;
+			}
+			const user = sessionCtx ?? (isGuest ? {
+				userId: "construction-guest",
+				email: "guest",
+				name: "Guest",
+				roles: ["guest"],
+				permissions: [],
+				userType: "user",
+				metadata: {}
+			} : null);
+			const session = sessionCtx ? {
+				id: sessionCtx.userId,
+				userId: sessionCtx.userId,
+				roles: sessionCtx.roles,
+				userType: sessionCtx.userType
+			} : isGuest ? {
+				id: "construction-guest",
+				userId: "construction-guest",
+				roles: ["guest"],
+				userType: "user"
+			} : null;
+			if (typeof c?.set === "function") {
+				c.set("user", user);
+				c.set("session", session);
+			}
+		}
+		const session = typeof c?.get === "function" ? c.get("session") : null;
+		const user = typeof c?.get === "function" ? c.get("user") : null;
+		if (pathname === "/auth") return c.redirect(authRedirectUrl);
+		if (guestOnlyRoutes.some((route) => matchesPattern(pathname, route)) && session) return c.redirect(homeUrl);
+		if (pathname.includes("/construction") && session) return c.redirect(homeUrl);
+		if ((typeof protectedRoutes === "function" ? protectedRoutes(pathname) : protectedRoutes.some((pattern) => matchesPattern(pathname, pattern))) && !session) {
+			if (onUnauthorized) return onUnauthorized(c, {
+				isApi,
+				path: pathname
+			});
+			if (isApi) {
+				if (typeof c.json === "function") return c.json({
+					error: "Unauthorized",
+					message: "Authentication required."
+				}, 401);
+				return new Response(JSON.stringify({
+					error: "Unauthorized",
+					message: "Authentication required."
+				}), {
+					status: 401,
+					headers: { "Content-Type": "application/json" }
+				});
+			}
+			return c.redirect(signInUrl);
+		}
+		for (const [guardPath, guardConfig] of Object.entries(roleGuards)) if (matchesPattern(pathname, guardPath)) {
+			if (!session) {
+				if (onUnauthorized) return onUnauthorized(c, {
+					isApi,
+					path: pathname
+				});
+				if (isApi) {
+					if (typeof c.json === "function") return c.json({
+						error: "Unauthorized",
+						message: "Authentication required."
+					}, 401);
+					return new Response(JSON.stringify({
+						error: "Unauthorized",
+						message: "Authentication required."
+					}), {
+						status: 401,
+						headers: { "Content-Type": "application/json" }
+					});
+				}
+				return c.redirect(signInUrl);
+			}
+			let isAllowed = false;
+			const userRoles = (user?.roles || []).map((r) => r.toLowerCase());
+			const userType = user?.userType;
+			if (Array.isArray(guardConfig)) {
+				const allowedRoles = guardConfig.map((r) => r.toLowerCase());
+				isAllowed = userRoles.includes("*") || allowedRoles.some((r) => userRoles.includes(r));
+			} else if (typeof guardConfig === "object" && guardConfig !== null) {
+				const { roles, userTypes, check } = guardConfig;
+				if (check) isAllowed = await check(user, c);
+				else {
+					const roleMatch = roles ? userRoles.includes("*") || roles.some((r) => userRoles.includes(r.toLowerCase())) : true;
+					const typeMatch = userTypes ? userType ? userTypes.includes(userType) : false : true;
+					isAllowed = roleMatch && typeMatch;
+				}
+			}
+			if (!isAllowed) {
+				if (onForbidden) {
+					const requiredRoles = Array.isArray(guardConfig) ? guardConfig : guardConfig.roles;
+					return onForbidden(c, {
+						isApi,
+						path: pathname,
+						requiredRoles
+					});
+				}
+				if (isApi) {
+					if (typeof c.json === "function") return c.json({
+						error: "Forbidden",
+						message: "Forbidden: insufficient permissions."
+					}, 403);
+					return new Response(JSON.stringify({
+						error: "Forbidden",
+						message: "Forbidden: insufficient permissions."
+					}), {
+						status: 403,
+						headers: { "Content-Type": "application/json" }
+					});
+				}
+				return c.redirect(homeUrl);
+			}
+		}
+		return await next();
+	};
+};
+//#endregion
+export { authMiddleware };

package/dist/types.d.mts

@@ -54,4 +54,86 @@ export interface AuthAdapter {
    */
   handleUnauthorized?: ((request: Request) => Response | Promise<Response>) | undefined;
 }
+export interface RoleGuard {
+  roles?: string[];
+  userTypes?: UserType[];
+  check?: (user: UserSessionContext | null, c: any) => boolean | Promise<boolean>;
+}
+export interface AuthMiddlewareOptions {
+  /**
+   * The auth adapter instance or custom session resolver function.
+   */
+  auth?: AuthAdapter | {
+    getSession(req: Request): Promise<UserSessionContext | null>;
+  } | ((c: any) => Promise<UserSessionContext | null>);
+  /**
+   * Fall back to construction guest session if no user is signed in.
+   *
+   * @default true
+   */
+  allowConstructionGuest?: boolean;
+  /**
+   * Whether to automatically skip static asset paths.
+   *
+   * @default true
+   */
+  skipStaticAssets?: boolean;
+  /**
+   * Route patterns to completely bypass session resolution.
+   *
+   * @default ["/docs/"]
+   */
+  ignoredRoutes?: (string | RegExp)[] | ((path: string) => boolean);
+  /**
+   * Route patterns that require an authenticated session.
+   *
+   * @default ["/internal"]
+   */
+  protectedRoutes?: (string | RegExp)[] | ((path: string) => boolean);
+  /**
+   * Role / permission requirements for specific route prefixes. E.g.: { "/admin": ["admin",
+   * "owner"], "/internal": { roles: ["employee", "staff", "admin", "owner"], userTypes:
+   * ["employee"] } }
+   */
+  roleGuards?: Record<string, string[] | RoleGuard>;
+  /**
+   * Routes that should redirect to home/dashboard if user is already logged in.
+   *
+   * @default ["/auth/sign-in", "/auth/sign-up"]
+   */
+  guestOnlyRoutes?: (string | RegExp)[];
+  /**
+   * URL to redirect to when `/auth` is accessed directly.
+   *
+   * @default "/auth/sign-in"
+   */
+  authRedirectUrl?: string;
+  /**
+   * URL to redirect unauthenticated users accessing protected pages.
+   *
+   * @default "/auth/sign-in"
+   */
+  signInUrl?: string;
+  /**
+   * Home URL to redirect logged-in users away from guest routes or forbidden pages.
+   *
+   * @default "/"
+   */
+  homeUrl?: string;
+  /**
+   * Custom response when unauthorized (not logged in).
+   */
+  onUnauthorized?: (c: any, meta: {
+    isApi: boolean;
+    path: string;
+  }) => Response | Promise<Response>;
+  /**
+   * Custom response when forbidden (insufficient role/permissions).
+   */
+  onForbidden?: (c: any, meta: {
+    isApi: boolean;
+    path: string;
+    requiredRoles?: string[];
+  }) => Response | Promise<Response>;
+}
 //#endregion

package/dist/vite.d.mts

@@ -0,0 +1,33 @@
+//#region src/vite.d.ts
+export interface RimelightAuthPluginOptions {
+  /**
+   * Auth adapter to initialize: "cf-access" (default), "auth0", "mock", or "custom".
+   *
+   * @default "cf-access"
+   */
+  adapter?: "cf-access" | "auth0" | "mock" | "custom" | (string & {});
+  /**
+   * Path to custom auth module if adapter is set to "custom".
+   */
+  customModule?: string;
+  /**
+   * Additional adapter-specific configuration overrides.
+   */
+  [key: string]: any;
+}
+export interface RimelightAuthPlugin {
+  name: string;
+  resolveId: (id: string) => string | null | undefined;
+  load: (id: string) => string | null | undefined;
+}
+/**
+ * Pure Vite Auth Plugin for Rimelight applications.
+ *
+ * Exposes virtual modules:
+ *
+ * - `virtual:rimelight-auth` (alias `#auth/auth`, `#auth`)
+ * - `virtual:rimelight-auth-client` (alias `#auth/auth-client`)
+ * - `virtual:rimelight-auth-config`
+ */
+export declare function auth(options?: RimelightAuthPluginOptions): RimelightAuthPlugin;
+//#endregion

package/dist/vite.mjs

@@ -0,0 +1,66 @@
+//#region src/vite.ts
+/**
+* Pure Vite Auth Plugin for Rimelight applications.
+*
+* Exposes virtual modules:
+*
+* - `virtual:rimelight-auth` (alias `#auth/auth`, `#auth`)
+* - `virtual:rimelight-auth-client` (alias `#auth/auth-client`)
+* - `virtual:rimelight-auth-config`
+*/
+function auth(options = {}) {
+	const adapter = options.adapter || "cf-access";
+	const virtualAuthId = "virtual:rimelight-auth";
+	const resolvedVirtualAuthId = "\0" + virtualAuthId;
+	const virtualClientId = "virtual:rimelight-auth-client";
+	const resolvedVirtualClientId = "\0" + virtualClientId;
+	const virtualConfigId = "virtual:rimelight-auth-config";
+	const resolvedVirtualConfigId = "\0" + virtualConfigId;
+	return {
+		name: "vite-plugin-rimelight-auth",
+		resolveId(id) {
+			if (id === virtualAuthId || id === "#auth" || id === "#auth/auth") return resolvedVirtualAuthId;
+			if (id === virtualClientId || id === "#auth/auth-client") return resolvedVirtualClientId;
+			if (id === virtualConfigId) return resolvedVirtualConfigId;
+			return null;
+		},
+		load(id) {
+			if (id === resolvedVirtualConfigId) return `export const config = ${JSON.stringify(options)};`;
+			if (id === resolvedVirtualClientId) return `
+import { createAuthClient, authClient } from "@rimelight/auth/client";
+export { createAuthClient, authClient };
+export default authClient;
+`;
+			if (id === resolvedVirtualAuthId) {
+				if (adapter === "custom" && options.customModule) return `
+export * from "${options.customModule}";
+export { default } from "${options.customModule}";
+`;
+				if (adapter === "auth0") return `
+import { createAuth0FromEnv } from "@rimelight/auth/auth0";
+export const auth = createAuth0FromEnv(${JSON.stringify({
+					devFallback: true,
+					...options
+				})});
+export const authAdapter = auth;
+export default auth;
+`;
+				if (adapter === "mock") return `
+import { mockAuth } from "@rimelight/auth/mock";
+export const auth = mockAuth(${JSON.stringify(options)});
+export const authAdapter = auth;
+export default auth;
+`;
+				return `
+import { createCfAccessFromEnv } from "@rimelight/auth/cf-access";
+export const auth = createCfAccessFromEnv(${JSON.stringify(options)});
+export const authAdapter = auth;
+export default auth;
+`;
+			}
+			return null;
+		}
+	};
+}
+//#endregion
+export { auth };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rimelight/auth",
-  "version": "0.0.8",
+  "version": "0.0.9",
   "private": false,
   "description": "Rimelight Entertainment's Universal Authentication & Identity Package",
   "homepage": "https://rimelight.com/docs",
@@ -51,6 +51,18 @@
     "./plugins/construction-guest": {
       "types": "./dist/plugins/construction-guest/index.d.mts",
       "import": "./dist/plugins/construction-guest/index.mjs"
+    },
+    "./middleware": {
+      "types": "./dist/middleware/index.d.mts",
+      "import": "./dist/middleware/index.mjs"
+    },
+    "./client": {
+      "types": "./dist/client/index.d.mts",
+      "import": "./dist/client/index.mjs"
+    },
+    "./vite": {
+      "types": "./dist/vite.d.mts",
+      "import": "./dist/vite.mjs"
     }
   },
   "publishConfig": {
@@ -61,7 +73,7 @@
     "jose": "6.2.12"
   },
   "devDependencies": {
-    "@rimelight/config": "0.0.12",
+    "@rimelight/config": "0.0.13",
     "@types/node": "26.5.1"
   },
   "peerDependencies": {
@@ -77,7 +89,7 @@
     }
   },
   "engines": {
-    "node": ">=26.9.0"
+    "node": ">=26.8.2"
   },
   "scripts": {
     "build": "vp pack",