@classytic/arc 1.1.0 → 2.1.3

package/dist/auth/index.mjs

@@ -0,0 +1,1096 @@
+import { t as AUTHENTICATED_SCOPE } from "../types-Beqn1Un7.mjs";
+import { n as normalizeRoles, t as getUserRoles } from "../types-DelU6kln.mjs";
+import { t as ArcError } from "../errors-DBANPbGr.mjs";
+import { requireOrgMembership, requireOrgRole, requireTeamMembership } from "../permissions/index.mjs";
+import { n as extractBetterAuthOpenApi } from "../betterAuthOpenApi-DjWDddNc.mjs";
+import { createHmac, randomUUID, timingSafeEqual } from "node:crypto";
+import fp from "fastify-plugin";
+
+//#region src/auth/authPlugin.ts
+/**
+* Auth Plugin - Flexible, Database-Agnostic Authentication
+*
+* Arc provides JWT infrastructure and calls your authenticator.
+* You control ALL authentication logic.
+*
+* Design principles:
+* - Arc handles plumbing (JWT sign/verify utilities)
+* - App handles business logic (how to authenticate, where users live)
+* - Works with any database (Prisma, MongoDB, Postgres, none)
+* - Supports multiple auth strategies (JWT, API keys, sessions, etc.)
+*
+* @example
+* ```typescript
+* // In createApp
+* auth: {
+*   jwt: { secret: process.env.JWT_SECRET },
+*   authenticate: async (request, { jwt }) => {
+*     // Your auth logic - Arc never touches your database
+*     const token = request.headers.authorization?.split(' ')[1];
+*     if (!token) return null;
+*     const decoded = jwt.verify(token);
+*     return userRepo.findById(decoded.id);
+*   },
+* }
+* ```
+*/
+/**
+* Parse expiration string to seconds
+*/
+function parseExpiresIn(input, defaultValue) {
+	if (!input) return defaultValue;
+	if (/^\d+$/.test(input)) return parseInt(input, 10);
+	const match = /^(\d+)\s*([smhd])$/i.exec(input);
+	if (!match) return defaultValue;
+	return parseInt(match[1], 10) * ({
+		s: 1,
+		m: 60,
+		h: 3600,
+		d: 86400
+	}[match[2].toLowerCase()] ?? 1);
+}
+/**
+* Extract Bearer token from Authorization header
+*/
+function extractBearerToken(request) {
+	const auth = request.headers.authorization;
+	if (!auth?.startsWith("Bearer ")) return null;
+	return auth.slice(7);
+}
+const authPlugin = async (fastify, opts = {}) => {
+	const { jwt: jwtConfig, authenticate: appAuthenticator, onFailure, userProperty = "user", exposeAuthErrors = false } = opts;
+	let jwtContext = null;
+	if (jwtConfig?.secret) {
+		if (jwtConfig.secret.length < 32) throw new Error(`JWT secret must be at least 32 characters (current: ${jwtConfig.secret.length}).\nUse a strong random secret for production.`);
+		const jwtPlugin = await import("@fastify/jwt");
+		await fastify.register(jwtPlugin.default ?? jwtPlugin, {
+			secret: jwtConfig.secret,
+			sign: {
+				expiresIn: jwtConfig.expiresIn ?? "15m",
+				...jwtConfig.sign ?? {}
+			},
+			verify: { ...jwtConfig.verify ?? {} }
+		});
+		const fastifyWithJwt = fastify;
+		jwtContext = {
+			verify: (token) => {
+				return fastifyWithJwt.jwt.verify(token);
+			},
+			sign: (payload, options) => {
+				return fastifyWithJwt.jwt.sign(payload, options);
+			},
+			decode: (token) => {
+				try {
+					return fastifyWithJwt.jwt.decode(token);
+				} catch {
+					return null;
+				}
+			}
+		};
+		fastify.log.debug("Auth: JWT infrastructure enabled");
+	}
+	const authContext = {
+		jwt: jwtContext,
+		fastify
+	};
+	/**
+	* Authenticate middleware
+	*
+	* Arc adds this to preHandler for non-public routes.
+	* Calls app's authenticator or falls back to default JWT verify.
+	*/
+	const authenticate = async (request, reply) => {
+		try {
+			let user = null;
+			if (appAuthenticator) user = await appAuthenticator(request, authContext);
+			else if (jwtContext) {
+				const token = extractBearerToken(request);
+				if (token) {
+					const decoded = jwtContext.verify(token);
+					if (decoded.type === "refresh") throw new Error("Refresh tokens cannot be used for authentication");
+					user = decoded;
+				}
+			} else throw new Error("No authenticator configured. Provide auth.authenticate function or auth.jwt.secret.");
+			if (!user) throw new Error("Authentication required");
+			const reqRecord = request;
+			reqRecord.user = user;
+			reqRecord[userProperty] = user;
+			if (!request.scope || request.scope.kind === "public") {
+				const userRecord = user;
+				if (userRecord.organizationId) request.scope = {
+					kind: "member",
+					organizationId: String(userRecord.organizationId),
+					orgRoles: Array.isArray(userRecord.orgRoles) ? userRecord.orgRoles : []
+				};
+				else request.scope = AUTHENTICATED_SCOPE;
+			}
+		} catch (err) {
+			const error = err instanceof Error ? err : new Error(String(err));
+			if (onFailure) {
+				await onFailure(request, reply, error);
+				return;
+			}
+			const message = exposeAuthErrors ? error.message : "Authentication required";
+			reply.code(401).send({
+				success: false,
+				error: "Unauthorized",
+				message
+			});
+		}
+	};
+	/**
+	* Optional authenticate middleware
+	*
+	* Parses JWT if a Bearer token is present and populates request.user.
+	* Does NOT fail if no token or invalid token — treats as unauthenticated.
+	*
+	* Used on allowPublic() routes so that downstream middleware (e.g. multiTenant
+	* flexible filter) can apply org-scoped queries when a user IS authenticated.
+	*/
+	const optionalAuthenticate = async (request, _reply) => {
+		try {
+			let user = null;
+			if (appAuthenticator) user = await appAuthenticator(request, authContext);
+			else if (jwtContext) {
+				const token = extractBearerToken(request);
+				if (token) {
+					const decoded = jwtContext.verify(token);
+					if (decoded.type === "refresh") return;
+					user = decoded;
+				}
+			}
+			if (user) {
+				const reqRecord = request;
+				reqRecord.user = user;
+				reqRecord[userProperty] = user;
+				if (!request.scope || request.scope.kind === "public") {
+					const userRecord = user;
+					if (userRecord.organizationId) request.scope = {
+						kind: "member",
+						organizationId: String(userRecord.organizationId),
+						orgRoles: Array.isArray(userRecord.orgRoles) ? userRecord.orgRoles : []
+					};
+					else request.scope = AUTHENTICATED_SCOPE;
+				}
+			}
+		} catch {}
+	};
+	const refreshSecret = jwtConfig?.refreshSecret ?? jwtConfig?.secret;
+	const accessExpiresIn = jwtConfig?.expiresIn ?? "15m";
+	const refreshExpiresIn = jwtConfig?.refreshExpiresIn ?? "7d";
+	/**
+	* Issue access + refresh tokens
+	* App calls this after validating credentials (login, OAuth, etc.)
+	*/
+	const issueTokens = (payload, options) => {
+		if (!jwtContext) throw new Error("JWT not configured. Provide auth.jwt.secret to use issueTokens.");
+		const accessTtl = options?.expiresIn ?? accessExpiresIn;
+		const refreshTtl = options?.refreshExpiresIn ?? refreshExpiresIn;
+		const accessToken = jwtContext.sign({
+			...payload,
+			type: "access"
+		}, { expiresIn: accessTtl });
+		const refreshPayload = payload.id ? {
+			id: payload.id,
+			type: "refresh"
+		} : payload._id ? {
+			id: payload._id,
+			type: "refresh"
+		} : {
+			...payload,
+			type: "refresh"
+		};
+		let refreshToken;
+		if (refreshSecret) refreshToken = fastify.jwt.sign(refreshPayload, {
+			expiresIn: refreshTtl,
+			...refreshSecret !== jwtConfig?.secret ? { key: refreshSecret } : {}
+		});
+		return {
+			accessToken,
+			refreshToken,
+			expiresIn: parseExpiresIn(accessTtl, 900),
+			refreshExpiresIn: refreshToken ? parseExpiresIn(refreshTtl, 604800) : void 0,
+			tokenType: "Bearer"
+		};
+	};
+	/**
+	* Verify refresh token
+	* App calls this in refresh endpoint
+	*/
+	const verifyRefreshToken = (token) => {
+		if (!jwtContext) throw new Error("JWT not configured. Provide auth.jwt.secret to use verifyRefreshToken.");
+		const decoded = fastify.jwt.verify(token, { ...refreshSecret !== jwtConfig?.secret ? { key: refreshSecret } : {} });
+		if (decoded.type !== "refresh") throw new Error("Invalid token type: expected refresh token");
+		return decoded;
+	};
+	/**
+	* Authorize middleware factory
+	* Creates a middleware that checks if user has required roles
+	*
+	* @example
+	* preHandler: [fastify.authenticate, fastify.authorize('admin', 'superadmin')]
+	*/
+	const authorize = (...allowedRoles) => {
+		return async (request, reply) => {
+			const reqRecord = request;
+			const user = reqRecord[userProperty] ?? reqRecord.user;
+			if (!user) {
+				reply.code(401).send({
+					success: false,
+					error: "Unauthorized",
+					message: "No user context"
+				});
+				return;
+			}
+			const userRoles = getUserRoles(user);
+			if (allowedRoles.length === 1 && allowedRoles[0] === "*") return;
+			if (!allowedRoles.some((role) => userRoles.includes(role))) {
+				reply.code(403).send({
+					success: false,
+					error: "Forbidden",
+					message: `Requires one of: ${allowedRoles.join(", ")}`
+				});
+				return;
+			}
+		};
+	};
+	const authHelpers = {
+		jwt: jwtContext,
+		issueTokens,
+		verifyRefreshToken
+	};
+	fastify.decorate("authenticate", authenticate);
+	fastify.decorate("optionalAuthenticate", optionalAuthenticate);
+	fastify.decorate("authorize", authorize);
+	fastify.decorate("auth", authHelpers);
+	fastify.log.debug(`Auth: Plugin registered (jwt=${!!jwtContext}, customAuth=${!!appAuthenticator})`);
+};
+var authPlugin_default = fp(authPlugin, {
+	name: "arc-auth",
+	fastify: "5.x"
+});
+
+//#endregion
+//#region src/auth/betterAuth.ts
+/**
+* Better Auth Adapter for Arc/Fastify
+*
+* Bridges Fastify <-> Better Auth's Fetch API (Request/Response).
+* Better Auth is the USER's dependency -- Arc only provides this thin adapter.
+*
+* @example
+* import { betterAuth } from 'better-auth';
+* import { createBetterAuthAdapter } from '@classytic/arc/auth';
+*
+* const auth = betterAuth({ ... });
+*
+* const app = await createApp({
+*   auth: { type: 'betterAuth', betterAuth: createBetterAuthAdapter({ auth }) },
+* });
+*/
+/**
+* Convert a Fastify request into a Fetch API Request.
+*
+* Better Auth expects standard Web API Request objects.
+* We reconstruct one from Fastify's request properties.
+*/
+function toFetchRequest(request) {
+	const url = `${request.protocol ?? "http"}://${request.hostname ?? "localhost"}${request.url}`;
+	const headers = new Headers();
+	for (const [key, value] of Object.entries(request.headers)) {
+		if (value === void 0) continue;
+		if (Array.isArray(value)) for (const v of value) headers.append(key, v);
+		else headers.set(key, value);
+	}
+	const hasBody = request.method !== "GET" && request.method !== "HEAD";
+	let body;
+	if (hasBody && request.body != null) {
+		const contentType = (request.headers["content-type"] ?? "").toLowerCase();
+		if (request.rawBody) body = request.rawBody;
+		else if (contentType.includes("application/x-www-form-urlencoded")) {
+			const params = new URLSearchParams();
+			for (const [k, v] of Object.entries(request.body)) if (v != null) params.set(k, String(v));
+			body = params.toString();
+		} else if (typeof request.body === "string") body = request.body;
+		else if (contentType.includes("application/json") || contentType.includes("text/") || !contentType) body = JSON.stringify(request.body);
+		else request.log?.warn?.("toFetchRequest: cannot reconstruct %s body without rawBody plugin", contentType);
+	}
+	return new Request(url, {
+		method: request.method,
+		headers,
+		body
+	});
+}
+/**
+* Pipe a Fetch API Response back into Fastify's reply.
+*
+* Transfers status code, all response headers, and the body.
+* Handles both buffered (JSON) and streaming (SSE) responses.
+*/
+async function sendFetchResponse(response, reply) {
+	reply.status(response.status);
+	response.headers.forEach((value, key) => {
+		if (key.toLowerCase() === "transfer-encoding") return;
+		reply.header(key, value);
+	});
+	const contentType = response.headers.get("content-type") ?? "";
+	if (response.body && (contentType.includes("text/event-stream") || contentType.includes("application/octet-stream"))) await reply.send(response.body);
+	else {
+		const body = await response.text();
+		await reply.send(body);
+	}
+}
+/**
+* Try to get session via Better Auth's direct JS API.
+* Returns null if the API method is not available (older Better Auth versions).
+*/
+async function tryDirectGetSession(auth, headers) {
+	const api = auth.api;
+	if (!api || typeof api.getSession !== "function") return null;
+	try {
+		const result = await api.getSession({ headers });
+		if (result?.user) return result;
+		return null;
+	} catch {
+		return null;
+	}
+}
+/**
+* Try to get active org member via direct JS API.
+* Returns roles array or null if not available.
+*/
+async function tryDirectGetActiveMember(auth, headers) {
+	const getActiveMember = auth.api?.organization?.getActiveMember;
+	if (typeof getActiveMember !== "function") return null;
+	try {
+		const memberData = await getActiveMember({ headers });
+		if (memberData) return extractRolesFromMembership(memberData);
+		return null;
+	} catch {
+		return null;
+	}
+}
+/**
+* Look up member role by explicit organizationId (query param).
+*
+* Better Auth's `getActiveMemberRole` endpoint accepts an `organizationId`
+* query parameter, bypassing the session's `activeOrganizationId`.
+* This is essential for API key auth where the synthetic session has no
+* active organization set — callers pass org context via `x-organization-id` header.
+*/
+async function tryDirectGetMemberRole(auth, headers, organizationId) {
+	const getActiveMemberRole = auth.api?.organization?.getActiveMemberRole;
+	if (typeof getActiveMemberRole !== "function") return null;
+	try {
+		const result = await getActiveMemberRole({
+			headers,
+			query: { organizationId }
+		});
+		if (result?.role) return normalizeRoles(result.role);
+		return null;
+	} catch {
+		return null;
+	}
+}
+/**
+* Try to list teams via direct JS API.
+*/
+async function tryDirectListTeams(auth, headers) {
+	const listTeams = auth.api?.organization?.listTeams;
+	if (typeof listTeams !== "function") return null;
+	try {
+		const result = await listTeams({ headers });
+		const teams = Array.isArray(result) ? result : result?.teams;
+		return Array.isArray(teams) ? teams : null;
+	} catch {
+		return null;
+	}
+}
+/** Build a Headers object from Fastify request headers */
+function buildHeaders(request) {
+	const headers = new Headers();
+	for (const [key, value] of Object.entries(request.headers)) {
+		if (value === void 0) continue;
+		if (Array.isArray(value)) for (const v of value) headers.append(key, v);
+		else headers.set(key, value);
+	}
+	return headers;
+}
+/** Normalize unknown ID-like values to comparable string form */
+function normalizeId(value) {
+	if (value == null) return null;
+	if (typeof value === "string") return value;
+	if (typeof value === "number" || typeof value === "bigint") return String(value);
+	if (typeof value === "object") {
+		const obj = value;
+		const nested = obj._id ?? obj.id ?? obj.organizationId;
+		if (nested != null && nested !== value) return normalizeId(nested);
+	}
+	return String(value);
+}
+/** Extract role field from heterogeneous org membership shapes */
+function extractRolesFromMembership(membership) {
+	const direct = normalizeRoles(membership.role ?? membership.roles ?? membership.orgRole);
+	if (direct.length > 0) return direct;
+	const nestedMembership = membership.membership;
+	if (nestedMembership) {
+		const nested = normalizeRoles(nestedMembership.role ?? nestedMembership.roles);
+		if (nested.length > 0) return nested;
+	}
+	return [];
+}
+/** Match an organization membership entry against the active org id */
+function membershipMatchesOrg(membership, activeOrgId) {
+	return [
+		normalizeId(membership.organizationId),
+		normalizeId(membership.orgId),
+		normalizeId(membership.id),
+		normalizeId(membership.organization?._id),
+		normalizeId(membership.organization?.id),
+		normalizeId(membership.organization?.organizationId)
+	].filter(Boolean).includes(activeOrgId);
+}
+/**
+* Resolve org roles with fallback chain:
+* 1) GET /organization/get-active-member (requires activeOrganizationId in session)
+* 2) GET /organization/get-active-member-role?organizationId=... (explicit org — works for API key auth)
+* 3) GET /organization/list (fallback for type mismatch/legacy ID storage)
+*/
+async function resolveOrgRoles(auth, protocol, host, normalizedBase, headers, activeOrgId) {
+	const memberUrl = `${protocol}://${host}${normalizedBase}/organization/get-active-member`;
+	const memberRequest = new Request(memberUrl, {
+		method: "GET",
+		headers
+	});
+	const memberResponse = await auth.handler(memberRequest);
+	if (memberResponse.ok) {
+		const memberData = await memberResponse.json();
+		if (memberData) return extractRolesFromMembership(memberData);
+	}
+	const roleUrl = `${protocol}://${host}${normalizedBase}/organization/get-active-member-role?organizationId=${encodeURIComponent(activeOrgId)}`;
+	const roleRequest = new Request(roleUrl, {
+		method: "GET",
+		headers
+	});
+	const roleResponse = await auth.handler(roleRequest);
+	if (roleResponse.ok) {
+		const roleData = await roleResponse.json();
+		if (roleData?.role) return normalizeRoles(roleData.role);
+	}
+	const listUrl = `${protocol}://${host}${normalizedBase}/organization/list`;
+	const listRequest = new Request(listUrl, {
+		method: "GET",
+		headers
+	});
+	const listResponse = await auth.handler(listRequest);
+	if (!listResponse.ok) return null;
+	const listData = await listResponse.json();
+	const memberships = Array.isArray(listData) ? listData : listData?.organizations ?? listData?.data ?? [];
+	if (!Array.isArray(memberships)) return null;
+	const target = memberships.find((entry) => {
+		if (!entry || typeof entry !== "object") return false;
+		return membershipMatchesOrg(entry, activeOrgId);
+	});
+	if (!target) return null;
+	return extractRolesFromMembership(target);
+}
+/**
+* Create a Better Auth adapter for Arc/Fastify.
+*
+* Returns a Fastify plugin (registers catch-all auth routes) and an
+* `authenticate` preHandler that validates sessions via Better Auth.
+*
+* @example
+* ```typescript
+* import { betterAuth } from 'better-auth';
+* import { createBetterAuthAdapter } from '@classytic/arc/auth';
+*
+* const auth = betterAuth({
+*   database: ...,
+*   emailAndPassword: { enabled: true },
+* });
+*
+* const { plugin, authenticate } = createBetterAuthAdapter({ auth });
+*
+* // Register the plugin (catch-all auth routes)
+* await fastify.register(plugin);
+*
+* // Use authenticate as a preHandler on protected routes
+* fastify.get('/me', { preHandler: [authenticate] }, handler);
+* ```
+*/
+function createBetterAuthAdapter(options) {
+	const { auth, basePath = "/api/auth", orgContext: orgContextOpt = false, openapi: openapiOpt = true, userFields, exposeAuthErrors = false } = options;
+	const normalizedBase = basePath.replace(/\/+$/, "");
+	const orgEnabled = !!orgContextOpt;
+	/**
+	* Validates the current session by forwarding cookies/headers
+	* to Better Auth's `GET /api/auth/get-session` endpoint.
+	*
+	* On success, sets `request.user` and `request.session`.
+	* When orgContext is enabled, also sets `request.scope` to
+	* `{ kind: 'member', organizationId, orgRoles, teamId? }`.
+	* On failure, replies with 401.
+	*/
+	const authenticate = async (request, reply) => {
+		try {
+			const protocol = request.protocol ?? "http";
+			const host = request.hostname ?? "localhost";
+			const headers = buildHeaders(request);
+			let sessionData = null;
+			sessionData = await tryDirectGetSession(auth, headers);
+			if (!sessionData) {
+				const sessionUrl = `${protocol}://${host}${normalizedBase}/get-session`;
+				const sessionRequest = new Request(sessionUrl, {
+					method: "GET",
+					headers
+				});
+				const sessionResponse = await auth.handler(sessionRequest);
+				if (!sessionResponse.ok) {
+					reply.code(401).send({
+						success: false,
+						error: "Unauthorized",
+						message: "Invalid or expired session"
+					});
+					return;
+				}
+				sessionData = await sessionResponse.json();
+			}
+			if (!sessionData?.user) {
+				reply.code(401).send({
+					success: false,
+					error: "Unauthorized",
+					message: "No active session"
+				});
+				return;
+			}
+			const req = request;
+			req.user = sessionData.user;
+			req.session = sessionData.session;
+			req.scope = AUTHENTICATED_SCOPE;
+			if (orgEnabled) {
+				const session = sessionData.session;
+				const activeOrgId = session?.activeOrganizationId || request.headers["x-organization-id"];
+				if (activeOrgId) {
+					let orgRoles = await tryDirectGetActiveMember(auth, headers);
+					if (!orgRoles) orgRoles = await tryDirectGetMemberRole(auth, headers, activeOrgId);
+					if (!orgRoles) orgRoles = await resolveOrgRoles(auth, protocol, host, normalizedBase, headers, activeOrgId);
+					if (orgRoles) {
+						const scope = {
+							kind: "member",
+							organizationId: activeOrgId,
+							orgRoles
+						};
+						const activeTeamId = session?.activeTeamId;
+						if (activeTeamId) {
+							let teams = await tryDirectListTeams(auth, headers);
+							if (!teams) {
+								const teamsUrl = `${protocol}://${host}${normalizedBase}/organization/list-teams`;
+								const teamsRequest = new Request(teamsUrl, {
+									method: "GET",
+									headers
+								});
+								const teamsResponse = await auth.handler(teamsRequest);
+								if (teamsResponse.ok) {
+									const teamsData = await teamsResponse.json();
+									teams = Array.isArray(teamsData) ? teamsData : teamsData?.teams ?? [];
+								}
+							}
+							if (teams && teams.some((t) => t.id === activeTeamId)) scope.teamId = activeTeamId;
+						}
+						req.scope = scope;
+					}
+				}
+			}
+		} catch (err) {
+			const message = exposeAuthErrors ? err instanceof Error ? err.message : String(err) : "Authentication required";
+			reply.code(401).send({
+				success: false,
+				error: "Unauthorized",
+				message
+			});
+		}
+	};
+	/**
+	* Silently resolves session without failing.
+	* Populates request.user + request.scope if a valid session exists.
+	* On failure or missing session, continues as unauthenticated (scope stays 'public').
+	*
+	* Used by allowPublic() routes so downstream middleware (e.g. multiTenant
+	* flexible filter) can apply org-scoped queries when a user IS authenticated.
+	*/
+	const optionalAuthenticate = async (request, _reply) => {
+		try {
+			const headers = buildHeaders(request);
+			let sessionData = null;
+			sessionData = await tryDirectGetSession(auth, headers);
+			if (!sessionData) {
+				const sessionUrl = `${request.protocol ?? "http"}://${request.hostname ?? "localhost"}${normalizedBase}/get-session`;
+				const sessionRequest = new Request(sessionUrl, {
+					method: "GET",
+					headers
+				});
+				const sessionResponse = await auth.handler(sessionRequest);
+				if (sessionResponse.ok) sessionData = await sessionResponse.json();
+			}
+			if (!sessionData?.user) return;
+			const req = request;
+			req.user = sessionData.user;
+			req.session = sessionData.session;
+			req.scope = AUTHENTICATED_SCOPE;
+			if (orgEnabled) {
+				const activeOrgId = sessionData.session?.activeOrganizationId || request.headers["x-organization-id"];
+				if (activeOrgId) {
+					let orgRoles = await tryDirectGetActiveMember(auth, headers);
+					if (!orgRoles) orgRoles = await tryDirectGetMemberRole(auth, headers, activeOrgId);
+					if (!orgRoles) orgRoles = await resolveOrgRoles(auth, request.protocol ?? "http", request.hostname ?? "localhost", normalizedBase, headers, activeOrgId);
+					if (orgRoles) req.scope = {
+						kind: "member",
+						organizationId: activeOrgId,
+						orgRoles
+					};
+				}
+			}
+		} catch {}
+	};
+	let extractedOpenApi;
+	if (openapiOpt === false) extractedOpenApi = void 0;
+	else if (typeof openapiOpt === "object") extractedOpenApi = openapiOpt;
+	const betterAuthPlugin = async (fastify) => {
+		fastify.all(`${normalizedBase}/*`, async (request, reply) => {
+			try {
+				const fetchRequest = toFetchRequest(request);
+				await sendFetchResponse(await auth.handler(fetchRequest), reply);
+			} catch (err) {
+				throw new ArcError("Authentication service error", {
+					code: "AUTH_SERVICE_ERROR",
+					statusCode: 500,
+					cause: err instanceof Error ? err : new Error(String(err))
+				});
+			}
+		});
+		if (!fastify.hasDecorator("authenticate")) fastify.decorate("authenticate", authenticate);
+		if (!fastify.hasDecorator("optionalAuthenticate")) fastify.decorate("optionalAuthenticate", optionalAuthenticate);
+		if (!extractedOpenApi && openapiOpt !== false && auth.api && typeof auth.api === "object") {
+			const { extractBetterAuthOpenApi } = await import("../betterAuthOpenApi-DjWDddNc.mjs").then((n) => n.t);
+			extractedOpenApi = extractBetterAuthOpenApi(auth.api, {
+				basePath,
+				userFields
+			});
+		}
+		if (extractedOpenApi) {
+			const arc = fastify.arc;
+			if (arc?.externalOpenApiPaths) arc.externalOpenApiPaths.push(extractedOpenApi);
+		}
+		fastify.log.debug(`Better Auth: Routes registered at ${normalizedBase}/*`);
+	};
+	return {
+		plugin: fp(betterAuthPlugin, {
+			name: "arc-better-auth",
+			fastify: "5.x"
+		}),
+		authenticate,
+		optionalAuthenticate,
+		permissions: {
+			requireOrgRole: (...roles) => requireOrgRole(roles),
+			requireOrgMembership: () => requireOrgMembership(),
+			requireTeamMembership: () => requireTeamMembership()
+		},
+		openapi: extractedOpenApi
+	};
+}
+
+//#endregion
+//#region src/auth/sessionManager.ts
+/**
+* Session Management for Arc
+*
+* Lightweight cookie-based session manager that coexists with JWT and Better Auth.
+* Users pick their auth strategy — this is one option alongside authPlugin and
+* createBetterAuthAdapter.
+*
+* Features:
+* - Cookie-based session tokens (HMAC-signed)
+* - Session refresh with throttling (updateAge)
+* - Fresh session concept for sensitive operations (freshAge)
+* - Session revocation (single, all, all-except-current)
+* - Pluggable session stores (Memory, Redis, etc.)
+*
+* @example
+* ```typescript
+* import { createSessionManager, MemorySessionStore } from '@classytic/arc/auth';
+*
+* const sessions = createSessionManager({
+*   store: new MemorySessionStore(),
+*   secret: process.env.SESSION_SECRET,
+*   maxAge: 7 * 24 * 60 * 60, // 7 days
+*   updateAge: 24 * 60 * 60,  // refresh every 24h
+*   freshAge: 10 * 60,        // 10 min for sensitive ops
+* });
+*
+* // Register plugin
+* await fastify.register(sessions.plugin);
+*
+* // Protect sensitive routes
+* fastify.post('/change-password', {
+*   preHandler: [fastify.authenticate, sessions.requireFresh],
+* }, handler);
+* ```
+*/
+/**
+* Sign a session ID using HMAC-SHA256.
+* Returns `sessionId.signature` format.
+*/
+function signSessionId(sessionId, secret) {
+	return `${sessionId}.${createHmac("sha256", secret).update(sessionId).digest("base64url")}`;
+}
+/**
+* Verify and extract session ID from a signed cookie value.
+* Returns the session ID if valid, null otherwise.
+*/
+function verifySessionId(signedValue, secret) {
+	const lastDotIndex = signedValue.lastIndexOf(".");
+	if (lastDotIndex === -1) return null;
+	const sessionId = signedValue.slice(0, lastDotIndex);
+	const signature = signedValue.slice(lastDotIndex + 1);
+	if (!sessionId || !signature) return null;
+	const expectedSignature = createHmac("sha256", secret).update(sessionId).digest("base64url");
+	const sigBuf = Buffer.from(signature);
+	const expectedBuf = Buffer.from(expectedSignature);
+	if (sigBuf.length !== expectedBuf.length) return null;
+	return timingSafeEqual(sigBuf, expectedBuf) ? sessionId : null;
+}
+/**
+* Parse cookies from a Cookie header string.
+* Returns a map of cookie name to value.
+*/
+function parseCookies(header) {
+	const cookies = /* @__PURE__ */ new Map();
+	if (!header) return cookies;
+	const pairs = header.split(";");
+	for (const pair of pairs) {
+		const eqIndex = pair.indexOf("=");
+		if (eqIndex === -1) continue;
+		const name = pair.slice(0, eqIndex).trim();
+		const value = pair.slice(eqIndex + 1).trim();
+		if (name) try {
+			cookies.set(name, decodeURIComponent(value));
+		} catch {
+			cookies.set(name, value);
+		}
+	}
+	return cookies;
+}
+/**
+* Build a Set-Cookie header value.
+*/
+function buildSetCookieHeader(name, value, maxAgeSeconds, options) {
+	const parts = [
+		`${name}=${encodeURIComponent(value)}`,
+		`Max-Age=${maxAgeSeconds}`,
+		`Path=${options.path ?? "/"}`
+	];
+	if (options.httpOnly !== false) parts.push("HttpOnly");
+	if (options.secure ?? process.env.NODE_ENV === "production") parts.push("Secure");
+	parts.push(`SameSite=${capitalize(options.sameSite ?? "lax")}`);
+	if (options.domain) parts.push(`Domain=${options.domain}`);
+	return parts.join("; ");
+}
+/**
+* Build a Set-Cookie header that clears (expires) the cookie.
+*/
+function buildClearCookieHeader(name, options) {
+	return buildSetCookieHeader(name, "", 0, options);
+}
+function capitalize(s) {
+	return s.charAt(0).toUpperCase() + s.slice(1);
+}
+/**
+* In-memory session store for development and single-instance deployments.
+* NOT suitable for multi-instance/clustered deployments — use Redis or similar.
+*/
+var MemorySessionStore = class {
+	sessions = /* @__PURE__ */ new Map();
+	/** Reverse index: userId -> Set<sessionId> for efficient bulk operations */
+	userIndex = /* @__PURE__ */ new Map();
+	cleanupInterval = null;
+	constructor(options = {}) {
+		const intervalMs = options.cleanupIntervalMs ?? 6e4;
+		this.cleanupInterval = setInterval(() => {
+			this.cleanup();
+		}, intervalMs);
+		if (this.cleanupInterval.unref) this.cleanupInterval.unref();
+	}
+	async get(sessionId) {
+		const session = this.sessions.get(sessionId);
+		if (!session) return null;
+		if (Date.now() > session.expiresAt) {
+			await this.delete(sessionId);
+			return null;
+		}
+		return session;
+	}
+	async set(sessionId, data) {
+		this.sessions.set(sessionId, data);
+		let userSessions = this.userIndex.get(data.userId);
+		if (!userSessions) {
+			userSessions = /* @__PURE__ */ new Set();
+			this.userIndex.set(data.userId, userSessions);
+		}
+		userSessions.add(sessionId);
+	}
+	async delete(sessionId) {
+		const session = this.sessions.get(sessionId);
+		if (session) {
+			const userSessions = this.userIndex.get(session.userId);
+			if (userSessions) {
+				userSessions.delete(sessionId);
+				if (userSessions.size === 0) this.userIndex.delete(session.userId);
+			}
+		}
+		this.sessions.delete(sessionId);
+	}
+	async deleteAll(userId) {
+		const userSessions = this.userIndex.get(userId);
+		if (!userSessions) return;
+		for (const sessionId of userSessions) this.sessions.delete(sessionId);
+		this.userIndex.delete(userId);
+	}
+	async deleteAllExcept(userId, currentSessionId) {
+		const userSessions = this.userIndex.get(userId);
+		if (!userSessions) return;
+		for (const sessionId of userSessions) if (sessionId !== currentSessionId) this.sessions.delete(sessionId);
+		if (userSessions.has(currentSessionId)) this.userIndex.set(userId, new Set([currentSessionId]));
+		else this.userIndex.delete(userId);
+	}
+	/**
+	* Close the store and clean up resources.
+	*/
+	close() {
+		if (this.cleanupInterval) {
+			clearInterval(this.cleanupInterval);
+			this.cleanupInterval = null;
+		}
+		this.sessions.clear();
+		this.userIndex.clear();
+	}
+	/**
+	* Get current stats (for debugging/monitoring).
+	*/
+	getStats() {
+		return {
+			sessions: this.sessions.size,
+			users: this.userIndex.size
+		};
+	}
+	/**
+	* Remove expired sessions.
+	*/
+	cleanup() {
+		const now = Date.now();
+		for (const [sessionId, session] of this.sessions) if (now > session.expiresAt) {
+			const userSessions = this.userIndex.get(session.userId);
+			if (userSessions) {
+				userSessions.delete(sessionId);
+				if (userSessions.size === 0) this.userIndex.delete(session.userId);
+			}
+			this.sessions.delete(sessionId);
+		}
+	}
+};
+/**
+* Create a session manager for Arc.
+*
+* Returns a Fastify plugin and a `requireFresh` preHandler.
+*
+* The plugin:
+* - Parses session cookie on each request
+* - Validates session against the store
+* - Sets `request.user` and `request.session` from session data
+* - Refreshes session token if older than `updateAge`
+* - Provides `fastify.authenticate` decorator
+* - Provides `fastify.sessionManager` decorator for session CRUD
+*
+* @example
+* ```typescript
+* import { createSessionManager, MemorySessionStore } from '@classytic/arc/auth';
+*
+* const sessions = createSessionManager({
+*   store: new MemorySessionStore(),
+*   secret: process.env.SESSION_SECRET!,
+*   maxAge: 7 * 24 * 60 * 60,
+*   updateAge: 24 * 60 * 60,
+*   freshAge: 10 * 60,
+* });
+*
+* await fastify.register(sessions.plugin);
+*
+* // Login route
+* fastify.post('/login', async (request, reply) => {
+*   const user = await authenticateUser(request.body);
+*   const { cookie } = await fastify.sessionManager.createSession(user.id);
+*   reply.header('Set-Cookie', cookie);
+*   return { success: true, user };
+* });
+*
+* // Protected route
+* fastify.get('/me', {
+*   preHandler: [fastify.authenticate],
+* }, async (request) => {
+*   return { user: request.user };
+* });
+*
+* // Sensitive route (requires fresh session)
+* fastify.post('/change-password', {
+*   preHandler: [fastify.authenticate, sessions.requireFresh],
+* }, handler);
+* ```
+*/
+function createSessionManager(options) {
+	const { store, secret, maxAge: maxAgeSeconds = 10080 * 60, updateAge: updateAgeSeconds = 1440 * 60, freshAge: freshAgeSeconds = 600, cookieName = "arc.session", cookie: cookieOptions = {} } = options;
+	if (secret.length < 32) throw new Error(`Session secret must be at least 32 characters (current: ${secret.length}). Use a strong random secret for production.`);
+	const maxAgeMs = maxAgeSeconds * 1e3;
+	const updateAgeMs = updateAgeSeconds * 1e3;
+	const freshAgeMs = freshAgeSeconds * 1e3;
+	/**
+	* Create a new session and return the signed cookie value.
+	*/
+	async function createSession(userId, metadata) {
+		const sessionId = randomUUID();
+		const now = Date.now();
+		const sessionData = {
+			userId,
+			createdAt: now,
+			updatedAt: now,
+			expiresAt: now + maxAgeMs,
+			metadata
+		};
+		await store.set(sessionId, sessionData);
+		return {
+			sessionId,
+			cookie: buildSetCookieHeader(cookieName, signSessionId(sessionId, secret), maxAgeSeconds, cookieOptions)
+		};
+	}
+	/**
+	* Refresh a session: update the updatedAt timestamp and optionally extend expiry.
+	*/
+	async function refreshSession(sessionId) {
+		const session = await store.get(sessionId);
+		if (!session) return null;
+		const now = Date.now();
+		const updatedSession = {
+			...session,
+			updatedAt: now,
+			expiresAt: Math.max(session.expiresAt, now + maxAgeMs)
+		};
+		await store.set(sessionId, updatedSession);
+		return updatedSession;
+	}
+	/**
+	* PreHandler that rejects requests if the session is not "fresh".
+	* A session is fresh if it was last updated within `freshAge` seconds.
+	* Use this for sensitive operations like password changes, email changes, etc.
+	*/
+	const requireFresh = async (request, reply) => {
+		const session = request.session;
+		if (!session) {
+			reply.code(401).send({
+				success: false,
+				error: "Unauthorized",
+				message: "Authentication required"
+			});
+			return;
+		}
+		if (Date.now() - session.updatedAt > freshAgeMs) {
+			reply.code(403).send({
+				success: false,
+				error: "SessionNotFresh",
+				message: "Session is not fresh. Please re-authenticate to perform this action.",
+				code: "SESSION_NOT_FRESH"
+			});
+			return;
+		}
+	};
+	const sessionPlugin = async (fastify) => {
+		const authenticate = async (request, reply) => {
+			const cookieHeader = request.headers.cookie;
+			const signedValue = parseCookies(typeof cookieHeader === "string" ? cookieHeader : void 0).get(cookieName);
+			if (!signedValue) {
+				reply.code(401).send({
+					success: false,
+					error: "Unauthorized",
+					message: "No session cookie"
+				});
+				return;
+			}
+			const sessionId = verifySessionId(signedValue, secret);
+			if (!sessionId) {
+				reply.header("Set-Cookie", buildClearCookieHeader(cookieName, cookieOptions));
+				reply.code(401).send({
+					success: false,
+					error: "Unauthorized",
+					message: "Invalid session"
+				});
+				return;
+			}
+			const session = await store.get(sessionId);
+			if (!session) {
+				reply.header("Set-Cookie", buildClearCookieHeader(cookieName, cookieOptions));
+				reply.code(401).send({
+					success: false,
+					error: "Unauthorized",
+					message: "Session expired or revoked"
+				});
+				return;
+			}
+			if (Date.now() > session.expiresAt) {
+				await store.delete(sessionId);
+				reply.header("Set-Cookie", buildClearCookieHeader(cookieName, cookieOptions));
+				reply.code(401).send({
+					success: false,
+					error: "Unauthorized",
+					message: "Session expired"
+				});
+				return;
+			}
+			request.user = {
+				id: session.userId,
+				...session.metadata
+			};
+			request.session = {
+				...session,
+				id: sessionId
+			};
+			if (Date.now() - session.updatedAt > updateAgeMs) {
+				const updatedSession = await refreshSession(sessionId);
+				if (updatedSession) {
+					const newCookie = buildSetCookieHeader(cookieName, signSessionId(sessionId, secret), maxAgeSeconds, cookieOptions);
+					reply.header("Set-Cookie", newCookie);
+					request.session = {
+						...updatedSession,
+						id: sessionId
+					};
+				}
+			}
+		};
+		if (!fastify.hasDecorator("authenticate")) fastify.decorate("authenticate", authenticate);
+		fastify.decorate("sessionManager", {
+			createSession,
+			revokeSession: (sessionId) => store.delete(sessionId),
+			revokeAllSessions: (userId) => store.deleteAll(userId),
+			revokeOtherSessions: (userId, currentSessionId) => store.deleteAllExcept(userId, currentSessionId),
+			refreshSession
+		});
+		fastify.log.debug(`Session: Plugin registered (cookieName=${cookieName}, maxAge=${maxAgeSeconds}s, updateAge=${updateAgeSeconds}s, freshAge=${freshAgeSeconds}s)`);
+	};
+	return {
+		plugin: fp(sessionPlugin, {
+			name: "arc-session",
+			fastify: "5.x"
+		}),
+		requireFresh
+	};
+}
+
+//#endregion
+export { MemorySessionStore, authPlugin_default as authPlugin, authPlugin as authPluginFn, createBetterAuthAdapter, createSessionManager, extractBetterAuthOpenApi };