@classytic/arc 1.1.0 → 2.1.3

package/dist/audit/index.d.mts

@@ -0,0 +1,81 @@
+import "../elevation-DGo5shaX.mjs";
+import "../interface-e9XfSsUV.mjs";
+import "../types-RLkFVgaw.mjs";
+import { a as AuditContext, c as AuditStore, i as AuditAction, l as AuditStoreOptions, n as MongoAuditStoreOptions, o as AuditEntry, r as MongoConnection, s as AuditQueryOptions, u as createAuditEntry } from "../mongodb-ClykrfGo.mjs";
+import { FastifyPluginAsync } from "fastify";
+
+//#region src/audit/auditPlugin.d.ts
+interface AuditPluginOptions {
+  /** Enable audit logging (default: false) */
+  enabled?: boolean;
+  /** Storage backends to use */
+  stores?: ('memory' | 'mongodb')[];
+  /** MongoDB connection (required if using mongodb store) */
+  mongoConnection?: MongoConnection;
+  /** MongoDB collection name (default: 'audit_logs') */
+  mongoCollection?: string;
+  /** TTL in days for MongoDB (default: 90) */
+  ttlDays?: number;
+  /** Custom stores (advanced) */
+  customStores?: AuditStore[];
+  /**
+   * Automatically audit CRUD operations via the hook system (default: true when enabled).
+   * When enabled, create/update/delete operations are auto-logged without manual calls.
+   *
+   * - `true`: Auto-audit all CRUD operations on all resources
+   * - `{ operations: ['create', 'delete'] }`: Only auto-audit specific operations
+   * - `{ exclude: ['health', 'metrics'] }`: Skip specific resources
+   * - `false`: Disable auto-audit (manual calls only)
+   */
+  autoAudit?: boolean | {
+    operations?: ('create' | 'update' | 'delete')[];
+    exclude?: string[];
+  };
+}
+declare module 'fastify' {
+  interface FastifyInstance {
+    /** Log an audit entry */
+    audit: AuditLogger;
+  }
+  interface FastifyRequest {
+    /** Audit context for current request */
+    auditContext?: AuditContext;
+  }
+}
+interface AuditLogger {
+  /** Log a create action */
+  create: (resource: string, documentId: string, data: Record<string, unknown>, context?: AuditContext) => Promise<void>;
+  /** Log an update action */
+  update: (resource: string, documentId: string, before: Record<string, unknown>, after: Record<string, unknown>, context?: AuditContext) => Promise<void>;
+  /** Log a delete action */
+  delete: (resource: string, documentId: string, data: Record<string, unknown>, context?: AuditContext) => Promise<void>;
+  /** Log a restore action (soft delete undo) */
+  restore: (resource: string, documentId: string, data: Record<string, unknown>, context?: AuditContext) => Promise<void>;
+  /** Log a custom action */
+  custom: (resource: string, documentId: string, action: string, data?: Record<string, unknown>, context?: AuditContext) => Promise<void>;
+  /** Query audit logs (if stores support it) */
+  query: (options: AuditQueryOptions) => Promise<AuditEntry[]>;
+}
+declare const auditPlugin: FastifyPluginAsync<AuditPluginOptions>;
+declare const _default: FastifyPluginAsync<AuditPluginOptions>;
+//#endregion
+//#region src/audit/stores/memory.d.ts
+interface MemoryAuditStoreOptions {
+  /** Maximum entries to keep (default: 1000) */
+  maxEntries?: number;
+}
+declare class MemoryAuditStore implements AuditStore {
+  readonly name = "memory";
+  private entries;
+  private maxEntries;
+  constructor(options?: MemoryAuditStoreOptions);
+  log(entry: AuditEntry): Promise<void>;
+  query(options?: AuditQueryOptions): Promise<AuditEntry[]>;
+  close(): Promise<void>;
+  /** Get all entries (for testing) */
+  getAll(): AuditEntry[];
+  /** Clear all entries (for testing) */
+  clear(): void;
+}
+//#endregion
+export { type AuditAction, type AuditContext, type AuditEntry, type AuditLogger, type AuditPluginOptions, type AuditQueryOptions, type AuditStore, type AuditStoreOptions, MemoryAuditStore, type MemoryAuditStoreOptions, type MongoAuditStoreOptions, _default as auditPlugin, auditPlugin as auditPluginFn, createAuditEntry };

package/dist/audit/index.mjs

@@ -0,0 +1,275 @@
+import { t as MongoAuditStore } from "../mongodb-DNKEExbf.mjs";
+import fp from "fastify-plugin";
+
+//#region src/audit/stores/interface.ts
+/**
+* Create audit entry from context
+*/
+function createAuditEntry(resource, documentId, action, context, data) {
+	const changes = data?.before && data?.after ? detectChanges(data.before, data.after) : void 0;
+	return {
+		id: generateAuditId(),
+		resource,
+		documentId,
+		action,
+		userId: context.user?._id?.toString() ?? context.user?.id,
+		organizationId: context.organizationId,
+		before: data?.before,
+		after: data?.after,
+		changes,
+		requestId: context.requestId,
+		ipAddress: context.ipAddress,
+		userAgent: context.userAgent,
+		metadata: data?.metadata,
+		timestamp: /* @__PURE__ */ new Date()
+	};
+}
+/**
+* Detect changed fields between two objects
+*/
+function detectChanges(before, after) {
+	const changes = [];
+	const allKeys = new Set([...Object.keys(before), ...Object.keys(after)]);
+	for (const key of allKeys) {
+		if (key.startsWith("_") || key === "updatedAt") continue;
+		if (JSON.stringify(before[key]) !== JSON.stringify(after[key])) changes.push(key);
+	}
+	return changes;
+}
+/**
+* Generate unique audit ID
+*/
+function generateAuditId() {
+	return `aud_${Date.now().toString(36)}${Math.random().toString(36).substring(2, 10)}`;
+}
+
+//#endregion
+//#region src/audit/stores/memory.ts
+var MemoryAuditStore = class {
+	name = "memory";
+	entries = [];
+	maxEntries;
+	constructor(options = {}) {
+		this.maxEntries = options.maxEntries ?? 1e3;
+	}
+	async log(entry) {
+		this.entries.unshift(entry);
+		if (this.entries.length > this.maxEntries) this.entries = this.entries.slice(0, this.maxEntries);
+	}
+	async query(options = {}) {
+		let results = [...this.entries];
+		if (options.resource) results = results.filter((e) => e.resource === options.resource);
+		if (options.documentId) results = results.filter((e) => e.documentId === options.documentId);
+		if (options.userId) results = results.filter((e) => e.userId === options.userId);
+		if (options.organizationId) results = results.filter((e) => e.organizationId === options.organizationId);
+		if (options.action) {
+			const actions = Array.isArray(options.action) ? options.action : [options.action];
+			results = results.filter((e) => actions.includes(e.action));
+		}
+		if (options.from) results = results.filter((e) => e.timestamp >= options.from);
+		if (options.to) results = results.filter((e) => e.timestamp <= options.to);
+		const offset = options.offset ?? 0;
+		const limit = options.limit ?? 100;
+		results = results.slice(offset, offset + limit);
+		return results;
+	}
+	async close() {
+		this.entries = [];
+	}
+	/** Get all entries (for testing) */
+	getAll() {
+		return [...this.entries];
+	}
+	/** Clear all entries (for testing) */
+	clear() {
+		this.entries = [];
+	}
+};
+
+//#endregion
+//#region src/audit/auditPlugin.ts
+/**
+* Audit Plugin
+*
+* Optional audit trail with flexible storage options.
+* Disabled by default - enable explicitly for enterprise use cases.
+*
+* @example
+* import { auditPlugin } from '@classytic/arc/audit';
+*
+* // Development: in-memory
+* await fastify.register(auditPlugin, {
+*   enabled: true,
+*   stores: ['memory'],
+* });
+*
+* // Production: MongoDB with TTL
+* await fastify.register(auditPlugin, {
+*   enabled: true,
+*   stores: ['mongodb'],
+*   mongoConnection: mongoose.connection,
+*   ttlDays: 90,
+* });
+*/
+const auditPlugin = async (fastify, opts = {}) => {
+	const { enabled = false, stores: storeTypes = ["memory"], mongoConnection, mongoCollection = "audit_logs", ttlDays = 90, customStores = [] } = opts;
+	if (!enabled) {
+		fastify.decorate("audit", createNoopLogger());
+		fastify.decorateRequest("auditContext", void 0);
+		fastify.log?.debug?.("Audit plugin disabled");
+		return;
+	}
+	const stores = [...customStores];
+	for (const type of storeTypes) switch (type) {
+		case "memory":
+			stores.push(new MemoryAuditStore());
+			break;
+		case "mongodb":
+			if (!mongoConnection) throw new Error("Audit: mongoConnection required for mongodb store");
+			stores.push(new MongoAuditStore({
+				connection: mongoConnection,
+				collection: mongoCollection,
+				ttlDays
+			}));
+			break;
+	}
+	if (stores.length === 0) throw new Error("Audit: at least one store must be configured");
+	async function logToStores(entry) {
+		await Promise.all(stores.map((store) => store.log(entry)));
+	}
+	const audit = {
+		async create(resource, documentId, data, context) {
+			await logToStores(createAuditEntry(resource, documentId, "create", context ?? {}, { after: data }));
+		},
+		async update(resource, documentId, before, after, context) {
+			await logToStores(createAuditEntry(resource, documentId, "update", context ?? {}, {
+				before,
+				after
+			}));
+		},
+		async delete(resource, documentId, data, context) {
+			await logToStores(createAuditEntry(resource, documentId, "delete", context ?? {}, { before: data }));
+		},
+		async restore(resource, documentId, data, context) {
+			await logToStores(createAuditEntry(resource, documentId, "restore", context ?? {}, { after: data }));
+		},
+		async custom(resource, documentId, action, data, context) {
+			await logToStores(createAuditEntry(resource, documentId, "custom", context ?? {}, { metadata: {
+				customAction: action,
+				...data
+			} }));
+		},
+		async query(options) {
+			for (const store of stores) if (store.query) return store.query(options);
+			return [];
+		}
+	};
+	fastify.decorate("audit", audit);
+	fastify.decorateRequest("auditContext", void 0);
+	fastify.addHook("onRequest", async (request) => {
+		const user = request.user;
+		request.context;
+		const scope = request.scope;
+		request.auditContext = {
+			user,
+			organizationId: scope?.kind === "member" ? scope.organizationId : scope?.kind === "elevated" ? scope.organizationId : void 0,
+			requestId: request.id,
+			ipAddress: request.ip,
+			userAgent: request.headers["user-agent"],
+			endpoint: void 0,
+			duration: void 0
+		};
+	});
+	fastify.addHook("onResponse", async (request, reply) => {
+		if (request.auditContext) {
+			request.auditContext.endpoint = `${request.method} ${request.routeOptions?.url ?? request.url}`;
+			request.auditContext.duration = Math.round(reply.elapsedTime);
+		}
+	});
+	fastify.addHook("onClose", async () => {
+		await Promise.all(stores.map((store) => store.close?.()));
+	});
+	const autoAuditConfig = opts.autoAudit ?? true;
+	if (autoAuditConfig !== false) {
+		const defaultOps = [
+			"create",
+			"update",
+			"delete"
+		];
+		const ops = typeof autoAuditConfig === "object" ? autoAuditConfig.operations ?? defaultOps : defaultOps;
+		const excludeResources = new Set(typeof autoAuditConfig === "object" ? autoAuditConfig.exclude ?? [] : []);
+		fastify.addHook("onReady", async () => {
+			const arc = "arc" in fastify ? fastify.arc : void 0;
+			if (!arc?.hooks) {
+				fastify.log?.debug?.("Auto-audit skipped: arc-core plugin not registered");
+				return;
+			}
+			for (const op of ops) arc.hooks.after("*", op, async (ctx) => {
+				if (excludeResources.has(ctx.resource)) return;
+				const docId = autoAuditExtractId(ctx.result);
+				const scope = ctx.context?._scope;
+				const auditCtx = {
+					user: ctx.user,
+					organizationId: scope ? autoAuditGetOrgId(scope) : void 0
+				};
+				try {
+					if (op === "create") await audit.create(ctx.resource, docId, autoAuditToPlain(ctx.result), auditCtx);
+					else if (op === "update") await audit.update(ctx.resource, docId, autoAuditToPlain(ctx.meta?.existing), autoAuditToPlain(ctx.result), auditCtx);
+					else if (op === "delete") await audit.delete(ctx.resource, docId, autoAuditToPlain(ctx.result), auditCtx);
+				} catch (err) {
+					fastify.log?.warn?.({
+						resource: ctx.resource,
+						op,
+						err
+					}, "Auto-audit failed");
+				}
+			}, 90);
+			fastify.log?.debug?.({
+				ops,
+				exclude: [...excludeResources]
+			}, "Auto-audit hooks registered");
+		});
+	}
+	fastify.log?.debug?.({ stores: storeTypes }, "Audit plugin enabled");
+};
+/** Extract document ID from a result */
+function autoAuditExtractId(doc) {
+	if (!doc || typeof doc !== "object") return "";
+	const d = doc;
+	const rawId = d._id ?? d.id;
+	return rawId != null ? String(rawId) : "";
+}
+/** Convert Mongoose doc or plain object to plain object */
+function autoAuditToPlain(doc) {
+	if (!doc || typeof doc !== "object") return {};
+	if (typeof doc.toObject === "function") return doc.toObject();
+	return doc;
+}
+/** Extract org ID from scope (avoids importing scope module to prevent circular deps) */
+function autoAuditGetOrgId(scope) {
+	if (!scope || typeof scope !== "object") return void 0;
+	const s = scope;
+	if (s.kind === "member" || s.kind === "elevated") return s.organizationId;
+}
+/**
+* Create no-op logger for when audit is disabled
+*/
+function createNoopLogger() {
+	const noop = async () => {};
+	return {
+		create: noop,
+		update: noop,
+		delete: noop,
+		restore: noop,
+		custom: noop,
+		query: async () => []
+	};
+}
+var auditPlugin_default = fp(auditPlugin, {
+	name: "arc-audit",
+	fastify: "5.x",
+	dependencies: ["arc-core"]
+});
+
+//#endregion
+export { MemoryAuditStore, auditPlugin_default as auditPlugin, auditPlugin as auditPluginFn, createAuditEntry };

package/dist/audit/mongodb.d.mts

@@ -0,0 +1,5 @@
+import "../elevation-DGo5shaX.mjs";
+import "../interface-e9XfSsUV.mjs";
+import "../types-RLkFVgaw.mjs";
+import { n as MongoAuditStoreOptions, t as MongoAuditStore } from "../mongodb-ClykrfGo.mjs";
+export { MongoAuditStore, type MongoAuditStoreOptions };

package/dist/audit/mongodb.mjs

@@ -0,0 +1,3 @@
+import { t as MongoAuditStore } from "../mongodb-DNKEExbf.mjs";
+
+export { MongoAuditStore };

package/dist/audited-CGdLiSlE.mjs

@@ -0,0 +1,140 @@
+import { c as isElevated, n as PUBLIC_SCOPE } from "./types-Beqn1Un7.mjs";
+import { allowPublic, requireRoles } from "./permissions/index.mjs";
+
+//#region src/presets/softDelete.ts
+function softDeletePreset() {
+	return {
+		name: "softDelete",
+		additionalRoutes: (permissions) => [{
+			method: "GET",
+			path: "/deleted",
+			handler: "getDeleted",
+			summary: "Get soft-deleted items",
+			permissions: permissions.list ?? requireRoles(["admin"]),
+			wrapHandler: true,
+			operation: "listDeleted"
+		}, {
+			method: "POST",
+			path: "/:id/restore",
+			handler: "restore",
+			summary: "Restore soft-deleted item",
+			permissions: permissions.update ?? requireRoles(["admin"]),
+			wrapHandler: true,
+			operation: "restore"
+		}]
+	};
+}
+
+//#endregion
+//#region src/presets/slugLookup.ts
+function slugLookupPreset(options = {}) {
+	const { slugField = "slug" } = options;
+	return {
+		name: "slugLookup",
+		additionalRoutes: (permissions) => [{
+			method: "GET",
+			path: `/slug/:${slugField}`,
+			handler: "getBySlug",
+			summary: "Get by slug",
+			permissions: permissions.get ?? allowPublic(),
+			wrapHandler: true,
+			operation: "getBySlug"
+		}],
+		controllerOptions: { slugField }
+	};
+}
+
+//#endregion
+//#region src/presets/ownedByUser.ts
+/**
+* Create ownership check middleware.
+* Elevated scope (platform admin) bypasses ownership checks.
+*/
+function createOwnershipCheck(ownerField) {
+	return async (request, _reply) => {
+		const user = request.user;
+		if (!user) return;
+		if (isElevated(request.scope ?? PUBLIC_SCOPE)) return;
+		const userWithId = user;
+		const userId = userWithId._id ?? userWithId.id;
+		if (userId) request._ownershipCheck = {
+			field: ownerField,
+			userId
+		};
+	};
+}
+function ownedByUserPreset(options = {}) {
+	const { ownerField = "userId" } = options;
+	const ownershipMiddleware = createOwnershipCheck(ownerField);
+	return {
+		name: "ownedByUser",
+		middlewares: {
+			update: [ownershipMiddleware],
+			delete: [ownershipMiddleware]
+		}
+	};
+}
+
+//#endregion
+//#region src/presets/tree.ts
+function treePreset(options = {}) {
+	const { parentField = "parent" } = options;
+	return {
+		name: "tree",
+		additionalRoutes: (permissions) => [{
+			method: "GET",
+			path: "/tree",
+			handler: "getTree",
+			summary: "Get hierarchical tree",
+			permissions: permissions.list ?? allowPublic(),
+			wrapHandler: true,
+			operation: "getTree"
+		}, {
+			method: "GET",
+			path: `/:${parentField}/children`,
+			handler: "getChildren",
+			summary: "Get children of parent",
+			permissions: permissions.list ?? allowPublic(),
+			wrapHandler: true,
+			operation: "getChildren"
+		}],
+		controllerOptions: { parentField }
+	};
+}
+
+//#endregion
+//#region src/presets/audited.ts
+/**
+* Audited preset - adds createdBy/updatedBy tracking
+*/
+function auditedPreset(options = {}) {
+	const { createdByField = "createdBy", updatedByField = "updatedBy" } = options;
+	const injectCreatedBy = async (request, _reply) => {
+		const userWithId = request.user;
+		if (userWithId?._id || userWithId?.id) {
+			const userId = userWithId._id ?? userWithId.id;
+			request.body[createdByField] = userId;
+			request.body[updatedByField] = userId;
+		}
+	};
+	const injectUpdatedBy = async (request, _reply) => {
+		const userWithId = request.user;
+		if (userWithId?._id || userWithId?.id) request.body[updatedByField] = userWithId._id ?? userWithId.id;
+	};
+	return {
+		name: "audited",
+		schemaOptions: { fieldRules: {
+			[createdByField]: { systemManaged: true },
+			[updatedByField]: { systemManaged: true },
+			createdAt: { systemManaged: true },
+			updatedAt: { systemManaged: true }
+		} },
+		middlewares: {
+			create: [injectCreatedBy],
+			update: [injectUpdatedBy]
+		}
+	};
+}
+
+//#endregion
+export { softDeletePreset as a, slugLookupPreset as i, treePreset as n, ownedByUserPreset as r, auditedPreset as t };

package/dist/auth/index.d.mts

@@ -0,0 +1,188 @@
+import "../elevation-DGo5shaX.mjs";
+import "../interface-e9XfSsUV.mjs";
+import { t as PermissionCheck } from "../types-RLkFVgaw.mjs";
+import { AuthHelpers, AuthPluginOptions } from "../types/index.mjs";
+import { t as ExternalOpenApiPaths } from "../externalPaths-SyPF2tgK.mjs";
+import { a as SessionManagerOptions, c as createSessionManager, i as SessionData, n as MemorySessionStoreOptions, o as SessionManagerResult, r as SessionCookieOptions, s as SessionStore, t as MemorySessionStore } from "../sessionManager-D_iEHjQl.mjs";
+import { FastifyPluginAsync, FastifyReply as FastifyReply$1, FastifyRequest as FastifyRequest$1 } from "fastify";
+
+//#region src/auth/authPlugin.d.ts
+declare module 'fastify' {
+  interface FastifyInstance {
+    /** Authenticate middleware - use in preHandler for protected routes */
+    authenticate: (request: FastifyRequest, reply: FastifyReply) => Promise<void>;
+    /** Optional authenticate - parses JWT if present, doesn't fail if absent */
+    optionalAuthenticate: (request: FastifyRequest, reply: FastifyReply) => Promise<void>;
+    /** Authorize middleware factory - checks if user has required roles */
+    authorize: (...roles: string[]) => (request: FastifyRequest, reply: FastifyReply) => Promise<void>;
+    /** Auth helpers - issueTokens, jwt utilities */
+    auth: AuthHelpers;
+  }
+}
+declare const authPlugin: FastifyPluginAsync<AuthPluginOptions>;
+declare const _default: FastifyPluginAsync<AuthPluginOptions>;
+//#endregion
+//#region src/auth/betterAuth.d.ts
+declare module 'fastify' {
+  interface FastifyRequest {
+    /** Raw request body (from @fastify/raw-body plugin, if registered) */
+    rawBody?: Buffer | string;
+  }
+}
+/**
+ * Minimal interface for a Better Auth instance.
+ * We only require the `handler` method -- the full Better Auth type
+ * comes from the user's `better-auth` installation.
+ */
+interface BetterAuthHandler {
+  handler: (request: Request) => Promise<Response>;
+  /** The API endpoint map — each value has .path and .options. Used for OpenAPI docs extraction. */
+  api?: Record<string, unknown>;
+}
+interface BetterAuthAdapterOptions {
+  /** Better Auth instance (from betterAuth() in user's app) */
+  auth: BetterAuthHandler;
+  /** Base path for auth routes (default: '/api/auth') */
+  basePath?: string;
+  /**
+   * Enable org context extraction from Better Auth's organization plugin.
+   * When enabled, the adapter will look up the user's active organization
+   * membership and populate `request.scope` with org roles.
+   *
+   * @default false
+   */
+  orgContext?: boolean;
+  /**
+   * OpenAPI documentation for auth endpoints.
+   * - `true` (default): auto-extract from auth.api if available
+   * - `false`: disable (auth routes won't appear in OpenAPI docs)
+   * - `ExternalOpenApiPaths`: manual spec override
+   */
+  openapi?: boolean | ExternalOpenApiPaths;
+  /**
+   * Additional user fields from Better Auth config.
+   * These get merged into signUpEmail/updateUser request body schemas
+   * and the User component schema in OpenAPI docs.
+   *
+   * Fields with `input: false` are excluded from request bodies
+   * but still appear in the User component schema (output-only).
+   *
+   * @example
+   * ```typescript
+   * userFields: {
+   *   department: { type: 'string', description: 'Department', required: true },
+   *   roles: { type: 'array', description: 'User roles', input: false },
+   * }
+   * ```
+   */
+  userFields?: Record<string, {
+    type: string;
+    description?: string;
+    required?: boolean;
+    input?: boolean;
+  }>;
+  /**
+   * Expose detailed auth error messages in 401 responses.
+   * When false (default), returns generic "Authentication required".
+   * When true, includes the actual error message for debugging.
+   */
+  exposeAuthErrors?: boolean;
+}
+interface BetterAuthAdapterResult {
+  /** Fastify plugin that registers catch-all auth routes */
+  plugin: FastifyPluginAsync;
+  /** Authenticate preHandler -- validates session via Better Auth */
+  authenticate: (request: FastifyRequest$1, reply: FastifyReply$1) => Promise<void>;
+  /** Optional authenticate -- resolves session silently, continues as unauthenticated on failure */
+  optionalAuthenticate: (request: FastifyRequest$1, reply: FastifyReply$1) => Promise<void>;
+  /** Permission helpers bound to this auth adapter (available when orgContext is enabled) */
+  permissions: {
+    requireOrgRole: (...roles: string[]) => PermissionCheck;
+    requireOrgMembership: () => PermissionCheck;
+    requireTeamMembership: () => PermissionCheck;
+  };
+  /** OpenAPI paths extracted from Better Auth endpoints (undefined if openapi: false) */
+  openapi?: ExternalOpenApiPaths;
+}
+declare module 'fastify' {
+  interface FastifyInstance {
+    /**
+     * Authenticate middleware (Better Auth variant).
+     * Validates session by calling Better Auth's session endpoint internally.
+     * Set by the Better Auth adapter plugin.
+     */
+    authenticate: (request: FastifyRequest$1, reply: FastifyReply$1) => Promise<void>;
+    /**
+     * Optional authenticate middleware (Better Auth variant).
+     * Tries to resolve session silently — populates request.user if valid,
+     * continues as unauthenticated if no session or invalid session.
+     * Used on allowPublic() routes so downstream middleware can apply
+     * org-scoped queries when a user IS authenticated.
+     */
+    optionalAuthenticate: (request: FastifyRequest$1, reply: FastifyReply$1) => Promise<void>;
+  }
+}
+/**
+ * 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);
+ * ```
+ */
+declare function createBetterAuthAdapter(options: BetterAuthAdapterOptions): BetterAuthAdapterResult;
+//#endregion
+//#region src/auth/betterAuthOpenApi.d.ts
+interface BetterAuthOpenApiOptions {
+  /** Base path prefix for auth routes (default: '/api/auth') */
+  basePath?: string;
+  /** Tag name for auth routes in OpenAPI (default: 'Authentication') */
+  tagName?: string;
+  /** Tag description */
+  tagDescription?: string;
+  /** Exclude specific paths from the spec (e.g. ['/ok', '/error']) */
+  excludePaths?: string[];
+  /** Exclude SERVER_ONLY endpoints (default: true) */
+  excludeServerOnly?: boolean;
+  /**
+   * Additional user fields from Better Auth config.
+   * These get merged into signUpEmail/updateUser request body schemas
+   * and the User component schema for $ref resolution.
+   *
+   * Fields with `input: false` are excluded from request bodies
+   * but still appear in the User component schema (output-only).
+   */
+  userFields?: Record<string, {
+    type: string;
+    description?: string; /** Whether this field is required in sign-up (default: false) */
+    required?: boolean; /** Whether this field is accepted in request body (default: true). Set false for output-only fields. */
+    input?: boolean;
+  }>;
+}
+/**
+ * Extract OpenAPI paths from a Better Auth instance's API object.
+ *
+ * Walks `authApi` (the `auth.api` object from Better Auth), discovers
+ * endpoints, converts their Zod schemas to JSON Schema via `z.toJSONSchema()`,
+ * and returns a complete `ExternalOpenApiPaths` object ready for Arc's spec builder.
+ */
+declare function extractBetterAuthOpenApi(authApi: Record<string, unknown>, options?: BetterAuthOpenApiOptions): ExternalOpenApiPaths;
+//#endregion
+export { type AuthPluginOptions, type BetterAuthAdapterOptions, type BetterAuthAdapterResult, type BetterAuthHandler, type BetterAuthOpenApiOptions, MemorySessionStore, type MemorySessionStoreOptions, type SessionCookieOptions, type SessionData, type SessionManagerOptions, type SessionManagerResult, type SessionStore, _default as authPlugin, authPlugin as authPluginFn, createBetterAuthAdapter, createSessionManager, extractBetterAuthOpenApi };