@classytic/arc 1.1.0 → 2.1.3

package/dist/types/index.mjs

@@ -0,0 +1,14 @@
+import { a as getTeamId, c as isElevated, i as getOrgRoles, l as isMember, n as PUBLIC_SCOPE, o as hasOrgAccess, r as getOrgId, s as isAuthenticated, t as AUTHENTICATED_SCOPE } from "../types-Beqn1Un7.mjs";
+
+//#region src/types/index.ts
+/**
+* Extract user ID from a user object (supports both id and _id)
+*/
+function getUserId(user) {
+	if (!user) return void 0;
+	const id = user.id ?? user._id;
+	return id ? String(id) : void 0;
+}
+
+//#endregion
+export { AUTHENTICATED_SCOPE, PUBLIC_SCOPE, getOrgId, getOrgRoles, getTeamId, getUserId, hasOrgAccess, isAuthenticated, isElevated, isMember };

package/dist/types-B0dhNrnd.d.mts

@@ -0,0 +1,445 @@
+import { n as ElevationOptions } from "./elevation-DGo5shaX.mjs";
+import { Authenticator } from "./types/index.mjs";
+import { t as ExternalOpenApiPaths } from "./externalPaths-SyPF2tgK.mjs";
+import { i as CacheStore } from "./interface-DTbsvIWe.mjs";
+import { r as QueryCachePluginOptions } from "./queryCachePlugin-Q6SYuHZ6.mjs";
+import { i as EventTransport } from "./EventTransport-BkUDYZEb.mjs";
+import { t as EventPluginOptions } from "./eventPlugin-H6wDDjGO.mjs";
+import { o as CachingOptions, r as SSEOptions, t as ErrorHandlerOptions } from "./errorHandler-CW3OOeYq.mjs";
+import { r as IdempotencyStore } from "./interface-CSNjltAc.mjs";
+import { FastifyInstance, FastifyPluginAsync, FastifyReply, FastifyRequest, FastifyServerOptions } from "fastify";
+import { FastifyCorsOptions } from "@fastify/cors";
+import { FastifyHelmetOptions } from "@fastify/helmet";
+import { RateLimitOptions } from "@fastify/rate-limit";
+
+//#region src/factory/types.d.ts
+/**
+ * Arc's built-in JWT auth
+ *
+ * Registers @fastify/jwt, wires up `fastify.authenticate`, and
+ * exposes `fastify.auth` helpers (issueTokens, verifyRefreshToken).
+ *
+ * @example
+ * ```typescript
+ * const app = await createApp({
+ *   auth: {
+ *     type: 'jwt',
+ *     jwt: { secret: process.env.JWT_SECRET },
+ *   },
+ * });
+ *
+ * // With custom authenticator
+ * const app = await createApp({
+ *   auth: {
+ *     type: 'jwt',
+ *     jwt: { secret: process.env.JWT_SECRET },
+ *     authenticate: async (request, { jwt }) => {
+ *       const token = request.headers.authorization?.split(' ')[1];
+ *       if (!token) return null;
+ *       const decoded = jwt.verify(token);
+ *       return userRepo.findById(decoded.id);
+ *     },
+ *   },
+ * });
+ * ```
+ */
+interface JwtAuthOption {
+  type: 'jwt';
+  /**
+   * JWT configuration (optional but recommended)
+   * If provided, jwt utilities are available in authenticator context
+   */
+  jwt?: {
+    /** JWT secret (required for JWT features) */secret: string; /** Access token expiry (default: '15m') */
+    expiresIn?: string; /** Refresh token secret (defaults to main secret) */
+    refreshSecret?: string; /** Refresh token expiry (default: '7d') */
+    refreshExpiresIn?: string; /** Additional @fastify/jwt sign options */
+    sign?: Record<string, unknown>; /** Additional @fastify/jwt verify options */
+    verify?: Record<string, unknown>;
+  };
+  /**
+   * Custom authenticator function (recommended)
+   *
+   * Arc calls this for non-public routes.
+   * Return user object to authenticate, null/undefined to reject.
+   *
+   * If not provided and jwt.secret is set, uses default jwtVerify.
+   */
+  authenticate?: Authenticator;
+  /**
+   * Custom auth failure handler
+   * Customize the 401 response when authentication fails
+   */
+  onFailure?: (request: FastifyRequest, reply: FastifyReply, error?: Error) => void | Promise<void>;
+  /**
+   * Expose detailed auth error messages in 401 responses.
+   * When false (default), returns generic "Authentication required".
+   * When true, includes the actual error message for debugging.
+   * Decoupled from log level — set explicitly per environment.
+   */
+  exposeAuthErrors?: boolean;
+  /**
+   * Property name to store user on request (default: 'user')
+   */
+  userProperty?: string;
+}
+/**
+ * Better Auth adapter integration
+ *
+ * When provided, Arc registers the Better Auth plugin (which sets up
+ * auth routes and decorates fastify.authenticate) and skips Arc's
+ * built-in JWT auth setup entirely.
+ *
+ * @example
+ * ```typescript
+ * import { createBetterAuthAdapter } from '@classytic/arc-better-auth';
+ *
+ * const app = await createApp({
+ *   auth: { type: 'betterAuth', betterAuth: createBetterAuthAdapter({ auth: myBetterAuth }) },
+ * });
+ * ```
+ */
+interface BetterAuthOption {
+  type: 'betterAuth';
+  /** Better Auth adapter — pass the result of createBetterAuthAdapter() */
+  betterAuth: {
+    plugin: FastifyPluginAsync;
+    openapi?: ExternalOpenApiPaths;
+  };
+}
+/**
+ * Custom auth plugin — full control over authentication setup
+ *
+ * The plugin is registered directly on the Fastify instance.
+ * It must decorate `fastify.authenticate` for protected routes to work.
+ *
+ * @example
+ * ```typescript
+ * const app = await createApp({
+ *   auth: {
+ *     type: 'custom',
+ *     plugin: async (fastify) => {
+ *       fastify.decorate('authenticate', async (request, reply) => { ... });
+ *     },
+ *   },
+ * });
+ * ```
+ */
+interface CustomPluginAuthOption {
+  type: 'custom';
+  /** Custom Fastify plugin that sets up authentication */
+  plugin: FastifyPluginAsync;
+}
+/**
+ * Custom authenticator function — lightweight alternative to a full plugin
+ *
+ * Arc decorates `fastify.authenticate` with this function directly.
+ * No JWT setup, no Arc auth plugin — just your function.
+ *
+ * @example
+ * ```typescript
+ * const app = await createApp({
+ *   auth: {
+ *     type: 'authenticator',
+ *     authenticate: async (request, reply) => {
+ *       const session = await validateSession(request);
+ *       if (!session) reply.code(401).send({ error: 'Unauthorized' });
+ *       request.user = session.user;
+ *     },
+ *   },
+ * });
+ * ```
+ */
+interface CustomAuthenticatorOption {
+  type: 'authenticator';
+  /** Authenticate function — decorates fastify.authenticate directly */
+  authenticate: (request: FastifyRequest, reply: FastifyReply) => Promise<void>;
+}
+/**
+ * All supported auth configuration shapes
+ *
+ * - `false` — Disable authentication entirely
+ * - `JwtAuthOption` — Arc's built-in JWT auth (`type: 'jwt'`)
+ * - `BetterAuthOption` — Better Auth adapter integration (`type: 'betterAuth'`)
+ * - `CustomPluginAuthOption` — Your own Fastify auth plugin (`type: 'custom'`)
+ * - `CustomAuthenticatorOption` — A bare authenticate function (`type: 'authenticator'`)
+ */
+type AuthOption = false | JwtAuthOption | BetterAuthOption | CustomPluginAuthOption | CustomAuthenticatorOption;
+/**
+ * CreateApp Options
+ *
+ * Configuration for creating an Arc application.
+ *
+ * @example
+ * ```typescript
+ * // Minimal setup
+ * const app = await createApp({
+ *   preset: 'development',
+ *   auth: {
+ *     type: 'jwt',
+ *     jwt: { secret: process.env.JWT_SECRET },
+ *   },
+ * });
+ *
+ * // With custom authenticator
+ * const app = await createApp({
+ *   preset: 'production',
+ *   auth: {
+ *     type: 'jwt',
+ *     jwt: { secret: process.env.JWT_SECRET },
+ *     authenticate: async (request, { jwt }) => {
+ *       // Check API key first
+ *       const apiKey = request.headers['x-api-key'];
+ *       if (apiKey) {
+ *         const result = await apiKeyService.verify(apiKey);
+ *         if (result) return { _id: result.userId, isApiKey: true };
+ *       }
+ *       // Then check JWT
+ *       const token = request.headers.authorization?.split(' ')[1];
+ *       if (token) {
+ *         const decoded = jwt.verify(token);
+ *         return userRepo.findById(decoded.id);
+ *       }
+ *       return null;
+ *     },
+ *   },
+ * });
+ * ```
+ */
+interface CreateAppOptions {
+  /** Environment preset: 'production', 'development', 'testing', or 'edge' */
+  preset?: 'production' | 'development' | 'testing' | 'edge';
+  /**
+   * Runtime profile for store backends.
+   * - 'memory' (default): Uses in-memory stores. Suitable for single-instance deployments.
+   * - 'distributed': Requires Redis-compatible adapters for cache, events, idempotency.
+   *   Startup fails fast if any required distributed adapter is missing.
+   */
+  runtime?: 'memory' | 'distributed';
+  /**
+   * Store and transport instances for runtime profile validation.
+   * When `runtime` is `'distributed'`, Arc validates that these are
+   * not memory-backed. Provide Redis or other durable adapters.
+   */
+  stores?: {
+    /** Event transport (e.g., RedisEventTransport) */events?: EventTransport; /** Cache store (e.g., RedisCacheStore) */
+    cache?: CacheStore; /** Idempotency store (e.g., RedisIdempotencyStore) */
+    idempotency?: IdempotencyStore; /** QueryCache store (e.g., RedisCacheStore). Default: MemoryCacheStore. */
+    queryCache?: CacheStore;
+  };
+  /** Fastify logger configuration */
+  logger?: FastifyServerOptions['logger'];
+  /**
+   * Enable Arc debug logging.
+   *
+   * - `true` — all Arc modules
+   * - `string` — comma-separated module names (e.g., `'scope,elevation,sse'`)
+   * - `false` or omit — disabled (default)
+   *
+   * Also configurable via `ARC_DEBUG` environment variable.
+   *
+   * @example
+   * ```typescript
+   * // All modules
+   * const app = await createApp({ debug: true });
+   *
+   * // Specific modules
+   * const app = await createApp({ debug: 'scope,elevation' });
+   * ```
+   */
+  debug?: boolean | string;
+  /** Trust proxy headers (X-Forwarded-For, etc.) */
+  trustProxy?: boolean;
+  /**
+   * Auth configuration
+   *
+   * Set to false to disable authentication entirely.
+   * Each auth strategy requires a `type` discriminant field.
+   *
+   * @example
+   * ```typescript
+   * // Disable auth
+   * auth: false,
+   *
+   * // Arc JWT
+   * auth: {
+   *   type: 'jwt',
+   *   jwt: { secret: process.env.JWT_SECRET },
+   * },
+   *
+   * // Arc JWT + custom authenticator
+   * auth: {
+   *   type: 'jwt',
+   *   jwt: { secret: process.env.JWT_SECRET },
+   *   authenticate: async (request, { jwt }) => {
+   *     const token = request.headers.authorization?.split(' ')[1];
+   *     if (!token) return null;
+   *     const decoded = jwt.verify(token);
+   *     return userRepo.findById(decoded.id);
+   *   },
+   * },
+   *
+   * // Better Auth adapter
+   * auth: { type: 'betterAuth', betterAuth: createBetterAuthAdapter({ auth: myBetterAuth }) },
+   *
+   * // Custom auth plugin
+   * auth: {
+   *   type: 'custom',
+   *   plugin: async (fastify) => {
+   *     fastify.decorate('authenticate', async (req, reply) => { ... });
+   *   },
+   * },
+   *
+   * // Custom authenticator function
+   * auth: {
+   *   type: 'authenticator',
+   *   authenticate: async (request, reply) => {
+   *     const session = await validateSession(request);
+   *     if (!session) reply.code(401).send({ error: 'Unauthorized' });
+   *     request.user = session.user;
+   *   },
+   * },
+   * ```
+   */
+  auth?: AuthOption;
+  /**
+   * Platform admin elevation — opt-in for apps with superadmins.
+   *
+   * When configured, platform admins can explicitly elevate their scope
+   * by sending `x-arc-scope: platform` header. Without this header,
+   * superadmins are treated as normal users.
+   *
+   * Set to `false` or omit to disable elevation entirely.
+   *
+   * @example
+   * ```typescript
+   * elevation: {
+   *   platformRoles: ['superadmin'],
+   *   onElevation: (event) => auditLog.write({
+   *     action: 'platform_elevation',
+   *     userId: event.userId,
+   *     targetOrg: event.organizationId,
+   *   }),
+   * }
+   * ```
+   */
+  elevation?: ElevationOptions | false;
+  /** Helmet security headers. Set to false to disable. */
+  helmet?: FastifyHelmetOptions | false;
+  /** CORS configuration. Set to false to disable. */
+  cors?: FastifyCorsOptions | false;
+  /** Rate limiting. Set to false to disable. */
+  rateLimit?: RateLimitOptions | false;
+  /** Under pressure health monitoring. Set to false to disable. */
+  underPressure?: UnderPressureOptions | false;
+  /** @fastify/sensible (HTTP helpers). Set to false to disable. */
+  sensible?: boolean | false;
+  /** @fastify/multipart (file uploads). Set to false to disable. */
+  multipart?: MultipartOptions | false;
+  /** Raw body parsing (for webhooks). Set to false to disable. */
+  rawBody?: RawBodyOptions | false;
+  /** Enable Arc plugins (requestId, health, gracefulShutdown, events, caching, sse) */
+  arcPlugins?: {
+    /** Request ID tracking (default: true) */requestId?: boolean; /** Health endpoints (default: true) */
+    health?: boolean; /** Graceful shutdown handling (default: true) */
+    gracefulShutdown?: boolean; /** Emit events for CRUD operations (default: true) */
+    emitEvents?: boolean;
+    /**
+     * Event plugin configuration. Default: true (enabled with MemoryEventTransport).
+     * Set to false to disable event plugin registration entirely.
+     * Set to true for defaults (memory transport), or pass EventPluginOptions for fine control.
+     * Transport is sourced from `stores.events` if provided, otherwise defaults to memory.
+     *
+     * When enabled, registers `eventPlugin` which provides `fastify.events` for
+     * pub/sub. Combined with `emitEvents: true`, CRUD operations automatically
+     * emit domain events (e.g., `product.created`, `order.updated`).
+     *
+     * @example
+     * ```typescript
+     * // Memory transport (default)
+     * const app = await createApp({ arcPlugins: { events: true } });
+     *
+     * // With retry and logging
+     * const app = await createApp({
+     *   stores: { events: new RedisEventTransport({ url: 'redis://...' }) },
+     *   arcPlugins: {
+     *     events: {
+     *       logEvents: true,
+     *       retry: { maxRetries: 3, backoffMs: 1000 },
+     *     },
+     *   },
+     * });
+     * ```
+     */
+    events?: Omit<EventPluginOptions, 'transport'> | boolean;
+    /**
+     * Caching headers (ETag + Cache-Control). Default: false (opt-in).
+     * Set to true for defaults, or pass CachingOptions for fine control.
+     */
+    caching?: CachingOptions | boolean;
+    /**
+     * SSE event streaming. Default: false (opt-in).
+     * Set to true for defaults, or pass SSEOptions for fine control.
+     * Requires emitEvents to be enabled (or events plugin registered).
+     */
+    sse?: SSEOptions | boolean;
+    /**
+     * QueryCache — TanStack Query-inspired server cache with SWR.
+     * Default: false (opt-in). Set to true for memory store defaults.
+     * Requires per-resource `cache` config on defineResource().
+     */
+    queryCache?: QueryCachePluginOptions | boolean;
+  };
+  /**
+   * Type provider for schema inference.
+   *
+   * When set to `'typebox'`, enables TypeBox type provider for
+   * automatic TypeScript inference from route schemas.
+   *
+   * Requires `@sinclair/typebox` and `@fastify/type-provider-typebox` installed.
+   *
+   * @example
+   * ```typescript
+   * import { Type } from '@classytic/arc/schemas';
+   *
+   * const app = await createApp({
+   *   typeProvider: 'typebox',
+   * });
+   *
+   * // Now route schemas built with Type.* give full TS inference
+   * ```
+   */
+  typeProvider?: 'typebox';
+  /**
+   * Error handler plugin. Normalizes AJV, Mongoose, and ArcError responses
+   * into a consistent JSON envelope. Enabled by default.
+   * Set to false to disable, or pass ErrorHandlerOptions for fine control.
+   */
+  errorHandler?: ErrorHandlerOptions | false;
+  /** Custom plugin registration function */
+  plugins?: (fastify: FastifyInstance) => Promise<void>;
+  /** Hook called after all plugins are loaded and the app is ready */
+  onReady?: (fastify: FastifyInstance) => void | Promise<void>;
+  /** Hook called when the app is shutting down */
+  onClose?: (fastify: FastifyInstance) => void | Promise<void>;
+}
+interface UnderPressureOptions {
+  exposeStatusRoute?: boolean;
+  maxEventLoopDelay?: number;
+  maxHeapUsedBytes?: number;
+  maxRssBytes?: number;
+}
+interface MultipartOptions {
+  limits?: {
+    fileSize?: number;
+    files?: number;
+  };
+}
+interface RawBodyOptions {
+  field?: string;
+  global?: boolean;
+  encoding?: string;
+  runFirst?: boolean;
+}
+//#endregion
+export { CustomPluginAuthOption as a, RawBodyOptions as c, CustomAuthenticatorOption as i, UnderPressureOptions as l, BetterAuthOption as n, JwtAuthOption as o, CreateAppOptions as r, MultipartOptions as s, AuthOption as t };

package/dist/types-Beqn1Un7.mjs

@@ -0,0 +1,38 @@
+//#region src/scope/types.ts
+/** Check if scope is `member` kind */
+function isMember(scope) {
+	return scope.kind === "member";
+}
+/** Check if scope is `elevated` kind */
+function isElevated(scope) {
+	return scope.kind === "elevated";
+}
+/** Check if scope has org access (member OR elevated) */
+function hasOrgAccess(scope) {
+	return scope.kind === "member" || scope.kind === "elevated";
+}
+/** Check if request is authenticated (any kind except public) */
+function isAuthenticated(scope) {
+	return scope.kind !== "public";
+}
+/** Get organizationId from scope (if present) */
+function getOrgId(scope) {
+	if (scope.kind === "member") return scope.organizationId;
+	if (scope.kind === "elevated") return scope.organizationId;
+}
+/** Get org roles from scope (empty array if not a member) */
+function getOrgRoles(scope) {
+	if (scope.kind === "member") return scope.orgRoles;
+	return [];
+}
+/** Get team ID from scope (only available on member kind) */
+function getTeamId(scope) {
+	if (scope.kind === "member") return scope.teamId;
+}
+/** Default public scope — used as initial decoration value */
+const PUBLIC_SCOPE = Object.freeze({ kind: "public" });
+/** Default authenticated scope — used when user is logged in but no org */
+const AUTHENTICATED_SCOPE = Object.freeze({ kind: "authenticated" });
+
+//#endregion
+export { getTeamId as a, isElevated as c, getOrgRoles as i, isMember as l, PUBLIC_SCOPE as n, hasOrgAccess as o, getOrgId as r, isAuthenticated as s, AUTHENTICATED_SCOPE as t };

package/dist/types-DelU6kln.mjs

@@ -0,0 +1,25 @@
+//#region src/permissions/types.ts
+/**
+* Extract normalized roles from a user object.
+*
+* Reads `user.role` which can be:
+* - A comma-separated string: `"superadmin,user"` (Better Auth admin plugin)
+* - A string array: `["admin", "user"]` (JWT / custom auth)
+* - A single string: `"admin"`
+*/
+/**
+* Normalize a raw role value (string, comma-separated string, or array) into a string[].
+* Shared low-level helper used by both getUserRoles() and the Better Auth adapter.
+*/
+function normalizeRoles(value) {
+	if (Array.isArray(value)) return value.map((r) => String(r).trim()).filter(Boolean);
+	if (typeof value === "string" && value.length > 0) return value.split(",").map((r) => r.trim()).filter(Boolean);
+	return [];
+}
+function getUserRoles(user) {
+	if (!user) return [];
+	return normalizeRoles(user.role);
+}
+
+//#endregion
+export { normalizeRoles as n, getUserRoles as t };

package/dist/types-RLkFVgaw.d.mts

@@ -0,0 +1,101 @@
+import { FastifyRequest } from "fastify";
+
+//#region src/permissions/types.d.ts
+/**
+ * User base interface - minimal shape Arc expects
+ * Your actual User can have any additional fields
+ */
+interface UserBase {
+  id?: string;
+  _id?: string;
+  /** User roles — string (comma-separated), string[], or undefined. Matches Better Auth's admin plugin pattern. */
+  role?: string | string[];
+  [key: string]: unknown;
+}
+/**
+ * Extract normalized roles from a user object.
+ *
+ * Reads `user.role` which can be:
+ * - A comma-separated string: `"superadmin,user"` (Better Auth admin plugin)
+ * - A string array: `["admin", "user"]` (JWT / custom auth)
+ * - A single string: `"admin"`
+ */
+/**
+ * Normalize a raw role value (string, comma-separated string, or array) into a string[].
+ * Shared low-level helper used by both getUserRoles() and the Better Auth adapter.
+ */
+declare function normalizeRoles(value: unknown): string[];
+declare function getUserRoles(user: UserBase | null | undefined): string[];
+/**
+ * Context passed to permission check functions
+ */
+interface PermissionContext<TDoc = any> {
+  /** Authenticated user or null if unauthenticated */
+  user: UserBase | null;
+  /** Fastify request object */
+  request: FastifyRequest;
+  /** Resource name being accessed */
+  resource: string;
+  /** Action being performed (list, get, create, update, delete, or custom operation name) */
+  action: string;
+  /** Resource ID for single-resource operations (shortcut for params.id) */
+  resourceId?: string;
+  /** All route parameters (slug, parentId, custom params, etc.) */
+  params?: Record<string, string>;
+  /** Request body data */
+  data?: Partial<TDoc> | Record<string, unknown>;
+}
+/**
+ * Result from permission check
+ */
+interface PermissionResult {
+  /** Whether access is granted */
+  granted: boolean;
+  /** Reason for denial (for error messages) */
+  reason?: string;
+  /** Query filters to apply (for ownership patterns) */
+  filters?: Record<string, unknown>;
+}
+/**
+ * Permission Check Function
+ *
+ * THE ONLY way to define permissions in Arc.
+ * Returns boolean, PermissionResult, or Promise of either.
+ *
+ * @example
+ * ```typescript
+ * // Simple boolean return
+ * const isAdmin: PermissionCheck = (ctx) => getUserRoles(ctx.user).includes('admin');
+ *
+ * // With filters for ownership
+ * const ownedByUser: PermissionCheck = (ctx) => ({
+ *   granted: true,
+ *   filters: { userId: ctx.user?.id }
+ * });
+ *
+ * // Async check
+ * const canAccessOrg: PermissionCheck = async (ctx) => {
+ *   const isMember = await checkMembership(ctx.user?.id, ctx.organizationId);
+ *   return { granted: isMember, reason: isMember ? undefined : 'Not a member' };
+ * };
+ * ```
+ */
+type PermissionCheck<TDoc = any> = ((context: PermissionContext<TDoc>) => boolean | PermissionResult | Promise<boolean | PermissionResult>) & PermissionCheckMeta;
+/**
+ * Optional metadata attached to permission check functions.
+ * Used for OpenAPI docs, introspection, and route-level auth decisions.
+ */
+interface PermissionCheckMeta {
+  /** Set by allowPublic() — marks the endpoint as publicly accessible */
+  _isPublic?: boolean;
+  /** Set by requireRoles() — the roles required for access */
+  _roles?: readonly string[];
+  /** Set by requireOrgMembership() — org-level permission type */
+  _orgPermission?: string;
+  /** Set by requireOrgRole() — the org roles required for access */
+  _orgRoles?: readonly string[];
+  /** Set by requireTeamMembership() — team-level permission type */
+  _teamPermission?: string;
+}
+//#endregion
+export { getUserRoles as a, UserBase as i, PermissionContext as n, normalizeRoles as o, PermissionResult as r, PermissionCheck as t };