@classytic/arc 1.1.0 → 2.1.3

package/dist/discovery/index.d.mts

@@ -0,0 +1,46 @@
+import { FastifyPluginAsync } from "fastify";
+
+//#region src/discovery/index.d.ts
+/** A discovered resource — must have toPlugin() method */
+interface DiscoverableResource {
+  toPlugin(): FastifyPluginAsync;
+  name?: string;
+  definition?: {
+    name: string;
+  };
+}
+interface DiscoveryOptions {
+  /** Directories to scan (relative to cwd or absolute) */
+  paths: string[];
+  /**
+   * File name pattern to match.
+   * Supports simple globs: *.resource.ts, *.resource.js
+   * Default: '*.resource.{ts,js}'
+   */
+  pattern?: string;
+  /** Export name to look for in each file (default: 'default' then first ResourceDefinition) */
+  exportName?: string;
+  /** Filter function to include/exclude discovered resources */
+  filter?: (resource: DiscoverableResource, filePath: string) => boolean;
+  /** Called for each discovered resource (for logging) */
+  onDiscover?: (name: string, filePath: string) => void;
+  /** Whether to scan recursively (default: true) */
+  recursive?: boolean;
+}
+interface DiscoveryPluginOptions extends DiscoveryOptions {
+  /** URL prefix applied to all discovered resources */
+  prefix?: string;
+}
+/**
+ * Discover and import resource files.
+ *
+ * @returns Array of discovered resources with their file paths
+ */
+declare function discoverResources(options: DiscoveryOptions): Promise<Array<{
+  resource: DiscoverableResource;
+  filePath: string;
+}>>;
+/** Auto-discovery plugin for Arc resources */
+declare const discoveryPlugin: FastifyPluginAsync<DiscoveryPluginOptions>;
+//#endregion
+export { DiscoverableResource, DiscoveryOptions, DiscoveryPluginOptions, discoveryPlugin as default, discoveryPlugin, discoverResources };

package/dist/discovery/index.mjs

@@ -0,0 +1,109 @@
+import { extname, join, resolve } from "node:path";
+import { readdir } from "node:fs/promises";
+import { pathToFileURL } from "node:url";
+
+//#region src/discovery/index.ts
+/**
+* Match a filename against a simple pattern.
+* Supports: *.resource.ts, *.resource.js, *.resource.{ts,js}
+*/
+function matchPattern(filename, pattern) {
+	if (pattern.includes("{") && pattern.includes("}")) {
+		const match = pattern.match(/\{([^}]+)\}/);
+		if (match) return match[1].split(",").map((s) => s.trim()).some((alt) => {
+			return matchPattern(filename, pattern.replace(match[0], alt));
+		});
+	}
+	if (pattern.startsWith("*")) {
+		const suffix = pattern.slice(1);
+		return filename.endsWith(suffix);
+	}
+	return filename === pattern;
+}
+/**
+* Recursively scan directories for files matching a pattern.
+*/
+async function scanDirectory(dir, pattern, recursive) {
+	const results = [];
+	const resolvedDir = resolve(dir);
+	const entries = await readdir(resolvedDir, { withFileTypes: true }).catch(() => []);
+	for (const entry of entries) {
+		const fullPath = join(resolvedDir, String(entry.name));
+		if (entry.isDirectory() && recursive) {
+			const nested = await scanDirectory(fullPath, pattern, recursive);
+			results.push(...nested);
+		} else if (entry.isFile()) {
+			const filePattern = pattern.replace(/^\*\*\//, "");
+			if (matchPattern(String(entry.name), filePattern)) results.push(fullPath);
+		}
+	}
+	return results;
+}
+/**
+* Discover and import resource files.
+*
+* @returns Array of discovered resources with their file paths
+*/
+async function discoverResources(options) {
+	const { paths, pattern = "*.resource.{ts,js}", exportName, filter, onDiscover, recursive = true } = options;
+	const discovered = [];
+	const allFiles = [];
+	for (const dir of paths) {
+		const files = await scanDirectory(dir, pattern, recursive);
+		allFiles.push(...files);
+	}
+	allFiles.sort();
+	for (const filePath of allFiles) {
+		extname(filePath);
+		const fileUrl = pathToFileURL(filePath).href;
+		let module;
+		try {
+			module = await import(fileUrl);
+		} catch (err) {
+			const message = err instanceof Error ? err.message : String(err);
+			throw new Error(`Failed to import resource file: ${filePath}\n${message}`);
+		}
+		let resource = null;
+		if (exportName && module[exportName]) resource = module[exportName];
+		if (!resource && module.default && typeof module.default.toPlugin === "function") resource = module.default;
+		if (!resource) {
+			for (const value of Object.values(module)) if (value && typeof value === "object" && typeof value.toPlugin === "function") {
+				resource = value;
+				break;
+			}
+		}
+		if (!resource) throw new Error(`No resource found in: ${filePath}\nResource files must export an object with a toPlugin() method.
+Use defineResource() or export the resource as default.`);
+		if (filter && !filter(resource, filePath)) continue;
+		const name = resource.definition?.name ?? resource.name ?? filePath;
+		onDiscover?.(name, filePath);
+		discovered.push({
+			resource,
+			filePath
+		});
+	}
+	return discovered;
+}
+const discoveryPluginImpl = async (fastify, options) => {
+	const { prefix, ...discoveryOptions } = options;
+	const discovered = await discoverResources({
+		...discoveryOptions,
+		onDiscover: discoveryOptions.onDiscover ?? ((name, filePath) => {
+			fastify.log.debug({
+				resource: name,
+				file: filePath
+			}, "Auto-discovered resource");
+		})
+	});
+	for (const { resource } of discovered) {
+		const plugin = resource.toPlugin();
+		if (prefix) await fastify.register(plugin, { prefix });
+		else await fastify.register(plugin);
+	}
+	fastify.log.debug(`Auto-discovery: registered ${discovered.length} resource(s)`);
+};
+/** Auto-discovery plugin for Arc resources */
+const discoveryPlugin = discoveryPluginImpl;
+
+//#endregion
+export { discoveryPlugin as default, discoveryPlugin, discoverResources };

package/dist/docs/index.d.mts

@@ -0,0 +1,162 @@
+import "../elevation-DGo5shaX.mjs";
+import "../interface-e9XfSsUV.mjs";
+import "../types-RLkFVgaw.mjs";
+import { RegistryEntry } from "../types/index.mjs";
+import { t as ExternalOpenApiPaths } from "../externalPaths-SyPF2tgK.mjs";
+import { FastifyPluginAsync } from "fastify";
+
+//#region src/docs/openapi.d.ts
+interface OpenApiOptions {
+  /** API title */
+  title?: string;
+  /** API version */
+  version?: string;
+  /** API description */
+  description?: string;
+  /** Server URL */
+  serverUrl?: string;
+  /** Route prefix for spec endpoint (default: '/_docs') */
+  prefix?: string;
+  /** API prefix for all resource paths (e.g., '/api/v1') */
+  apiPrefix?: string;
+  /** Auth roles required to access spec (default: [] = public) */
+  authRoles?: string[];
+  /** Include internal routes (default: false) */
+  includeInternal?: boolean;
+  /** Custom OpenAPI extensions */
+  extensions?: Record<string, unknown>;
+}
+interface OpenApiSpec {
+  openapi: string;
+  info: {
+    title: string;
+    version: string;
+    description?: string;
+  };
+  servers?: Array<{
+    url: string;
+    description?: string;
+  }>;
+  paths: Record<string, PathItem>;
+  components: {
+    schemas: Record<string, SchemaObject>;
+    securitySchemes?: Record<string, SecurityScheme>;
+  };
+  tags: Array<{
+    name: string;
+    description?: string;
+  }>;
+  security?: Array<Record<string, string[]>>;
+}
+interface OpenApiBuildOptions {
+  title?: string;
+  version?: string;
+  description?: string;
+  serverUrl?: string;
+  apiPrefix?: string;
+}
+interface PathItem {
+  get?: Operation;
+  post?: Operation;
+  put?: Operation;
+  patch?: Operation;
+  delete?: Operation;
+  options?: Operation;
+  head?: Operation;
+}
+interface Operation {
+  tags: string[];
+  summary: string;
+  description?: string;
+  operationId: string;
+  parameters?: Parameter[];
+  requestBody?: RequestBody;
+  responses: Record<string, Response>;
+  security?: Array<Record<string, string[]>>;
+  /** Arc permission metadata (OpenAPI extension) */
+  'x-arc-permission'?: {
+    type: string;
+    roles?: readonly string[];
+  };
+  /** Arc pipeline steps (OpenAPI extension) */
+  'x-arc-pipeline'?: Array<{
+    type: string;
+    name: string;
+  }>;
+}
+interface Parameter {
+  name: string;
+  in: 'path' | 'query' | 'header';
+  required?: boolean;
+  schema: SchemaObject;
+  description?: string;
+}
+interface RequestBody {
+  required?: boolean;
+  content: Record<string, {
+    schema: SchemaObject;
+  }>;
+}
+interface Response {
+  description: string;
+  content?: Record<string, {
+    schema: SchemaObject;
+  }>;
+}
+interface SchemaObject {
+  type?: string;
+  format?: string;
+  properties?: Record<string, SchemaObject>;
+  items?: SchemaObject;
+  required?: string[];
+  $ref?: string;
+  description?: string;
+  example?: unknown;
+  additionalProperties?: boolean | SchemaObject;
+  enum?: string[];
+  minimum?: number;
+  maximum?: number;
+  minLength?: number;
+  maxLength?: number;
+  pattern?: string;
+}
+interface SecurityScheme {
+  type: string;
+  scheme?: string;
+  bearerFormat?: string;
+  in?: string;
+  name?: string;
+}
+declare const openApiPlugin: FastifyPluginAsync<OpenApiOptions>;
+/**
+ * Build OpenAPI spec from registry resources.
+ * Shared by HTTP docs endpoint and CLI export command.
+ */
+declare function buildOpenApiSpec(resources: RegistryEntry[], options?: OpenApiBuildOptions, externalPaths?: ExternalOpenApiPaths[]): OpenApiSpec;
+declare const _default: FastifyPluginAsync<OpenApiOptions>;
+//#endregion
+//#region src/docs/scalar.d.ts
+interface ScalarOptions {
+  /** Route prefix for UI (default: '/docs') */
+  routePrefix?: string;
+  /** OpenAPI spec URL (default: '/_docs/openapi.json') */
+  specUrl?: string;
+  /** Page title */
+  title?: string;
+  /** Theme (default: 'default') */
+  theme?: 'default' | 'alternate' | 'moon' | 'purple' | 'solarized' | 'bluePlanet' | 'saturn' | 'kepler' | 'mars' | 'deepSpace';
+  /** Show sidebar (default: true) */
+  showSidebar?: boolean;
+  /** Dark mode (default: false) */
+  darkMode?: boolean;
+  /** Auth roles required to access docs */
+  authRoles?: string[];
+  /** Custom CSS */
+  customCss?: string;
+  /** Favicon URL */
+  favicon?: string;
+}
+declare const scalarPlugin: FastifyPluginAsync<ScalarOptions>;
+declare const _default$1: FastifyPluginAsync<ScalarOptions>;
+//#endregion
+export { type ExternalOpenApiPaths, type OpenApiBuildOptions, type OpenApiOptions, type OpenApiSpec, type ScalarOptions, buildOpenApiSpec, _default as openApiPlugin, openApiPlugin as openApiPluginFn, _default$1 as scalarPlugin, scalarPlugin as scalarPluginFn };

package/dist/docs/index.mjs

@@ -0,0 +1,74 @@
+import { t as getUserRoles } from "../types-DelU6kln.mjs";
+import { n as openApiPlugin, r as openapi_default, t as buildOpenApiSpec } from "../openapi-9nB_kiuR.mjs";
+import fp from "fastify-plugin";
+
+//#region src/docs/scalar.ts
+/**
+* Scalar API Reference Plugin
+*
+* Beautiful, modern API documentation UI.
+* Lighter and more modern than Swagger UI.
+*
+* @example
+* import { scalarPlugin } from '@classytic/arc/docs';
+*
+* await fastify.register(scalarPlugin, {
+*   routePrefix: '/docs',
+*   specUrl: '/_docs/openapi.json',
+* });
+*
+* // UI available at /docs
+*/
+const scalarPlugin = async (fastify, opts = {}) => {
+	const { routePrefix = "/docs", specUrl = "/_docs/openapi.json", title = "API Documentation", theme = "default", showSidebar = true, darkMode = false, authRoles = [], customCss = "", favicon } = opts;
+	const scalarConfig = JSON.stringify({
+		spec: { url: specUrl },
+		theme,
+		showSidebar,
+		darkMode,
+		...favicon && { favicon }
+	});
+	const html = `<!DOCTYPE html>
+<html>
+<head>
+  <meta charset="utf-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1">
+  <title>${title}</title>
+  ${favicon ? `<link rel="icon" href="${favicon}">` : ""}
+  <style>
+    body { margin: 0; padding: 0; }
+    ${customCss}
+  </style>
+</head>
+<body>
+  <script id="api-reference" data-url="${specUrl}"><\/script>
+  <script>
+    var configuration = ${scalarConfig};
+    document.getElementById('api-reference').dataset.configuration = JSON.stringify(configuration);
+  <\/script>
+  <script src="https://cdn.jsdelivr.net/npm/@scalar/api-reference"><\/script>
+</body>
+</html>`;
+	fastify.get(routePrefix, async (request, reply) => {
+		if (authRoles.length > 0) {
+			const user = request.user;
+			const roles = getUserRoles(user);
+			if (!authRoles.some((r) => roles.includes(r)) && !roles.includes("superadmin")) {
+				reply.code(403).send({ error: "Access denied" });
+				return;
+			}
+		}
+		reply.type("text/html").send(html);
+	});
+	if (!routePrefix.endsWith("/")) fastify.get(`${routePrefix}/`, async (_, reply) => {
+		reply.redirect(routePrefix);
+	});
+	fastify.log?.debug?.(`Scalar API docs available at ${routePrefix}`);
+};
+var scalar_default = fp(scalarPlugin, {
+	name: "arc-scalar",
+	fastify: "5.x"
+});
+
+//#endregion
+export { buildOpenApiSpec, openapi_default as openApiPlugin, openApiPlugin as openApiPluginFn, scalar_default as scalarPlugin, scalarPlugin as scalarPluginFn };

package/dist/elevation-DGo5shaX.d.mts

@@ -0,0 +1,87 @@
+import { FastifyPluginAsync, FastifyRequest } from "fastify";
+
+//#region src/scope/types.d.ts
+/**
+ * Request Scope — The One Standard
+ *
+ * Discriminated union representing the access context of every request.
+ * Replaces scattered orgScope/orgRoles/organizationId/bypassRoles.
+ *
+ * Set once by auth adapters, read everywhere by permissions/presets/guards.
+ *
+ * @example
+ * ```typescript
+ * // In a permission check
+ * const scope = request.scope;
+ * if (isElevated(scope)) return true;
+ * if (isMember(scope) && scope.orgRoles.includes('admin')) return true;
+ * ```
+ */
+/**
+ * Request scope — 4 kinds, 4 states, no ambiguity.
+ *
+ * | Kind          | Meaning                           |
+ * |---------------|-----------------------------------|
+ * | public        | No authentication                 |
+ * | authenticated | Logged in, no org context          |
+ * | member        | In an org with specific roles      |
+ * | elevated      | Platform admin, explicit elevation |
+ */
+type RequestScope = {
+  kind: 'public';
+} | {
+  kind: 'authenticated';
+} | {
+  kind: 'member';
+  organizationId: string;
+  orgRoles: string[];
+  teamId?: string;
+} | {
+  kind: 'elevated';
+  organizationId?: string;
+  elevatedBy: string;
+};
+/** Check if scope is `member` kind */
+declare function isMember(scope: RequestScope): scope is Extract<RequestScope, {
+  kind: 'member';
+}>;
+/** Check if scope is `elevated` kind */
+declare function isElevated(scope: RequestScope): scope is Extract<RequestScope, {
+  kind: 'elevated';
+}>;
+/** Check if scope has org access (member OR elevated) */
+declare function hasOrgAccess(scope: RequestScope): boolean;
+/** Check if request is authenticated (any kind except public) */
+declare function isAuthenticated(scope: RequestScope): boolean;
+/** Get organizationId from scope (if present) */
+declare function getOrgId(scope: RequestScope): string | undefined;
+/** Get org roles from scope (empty array if not a member) */
+declare function getOrgRoles(scope: RequestScope): string[];
+/** Get team ID from scope (only available on member kind) */
+declare function getTeamId(scope: RequestScope): string | undefined;
+/** Default public scope — used as initial decoration value */
+declare const PUBLIC_SCOPE: Readonly<RequestScope>;
+/** Default authenticated scope — used when user is logged in but no org */
+declare const AUTHENTICATED_SCOPE: Readonly<RequestScope>;
+//#endregion
+//#region src/scope/elevation.d.ts
+interface ElevationOptions {
+  /** Roles that can use elevation (default: ['superadmin']) */
+  platformRoles?: string[];
+  /** Header name for scope declaration (default: 'x-arc-scope') */
+  scopeHeader?: string;
+  /** Header name for target organization (default: 'x-organization-id') */
+  orgHeader?: string;
+  /** Called when elevation happens — use for audit logging */
+  onElevation?: (event: ElevationEvent) => void | Promise<void>;
+}
+interface ElevationEvent {
+  userId: string;
+  organizationId?: string;
+  request: FastifyRequest;
+  timestamp: Date;
+}
+declare const elevationPlugin: FastifyPluginAsync<ElevationOptions>;
+declare const _default: FastifyPluginAsync<ElevationOptions>;
+//#endregion
+export { AUTHENTICATED_SCOPE as a, getOrgId as c, hasOrgAccess as d, isAuthenticated as f, elevationPlugin as i, getOrgRoles as l, isMember as m, ElevationOptions as n, PUBLIC_SCOPE as o, isElevated as p, _default as r, RequestScope as s, ElevationEvent as t, getTeamId as u };

package/dist/elevation-DSTbVvYj.mjs

@@ -0,0 +1,113 @@
+import { t as __exportAll } from "./chunk-C7Uep-_p.mjs";
+import { t as getUserRoles } from "./types-DelU6kln.mjs";
+import { t as arcLog } from "./logger-ByrvQWZO.mjs";
+import fp from "fastify-plugin";
+
+//#region src/scope/elevation.ts
+/**
+* Elevation Plugin — Explicit Platform Admin Access
+*
+* Opt-in Fastify plugin that allows platform admins to explicitly
+* elevate their scope via the `x-arc-scope: platform` header.
+*
+* Without this header, a superadmin is treated as a normal user.
+* This prevents implicit bypass and enables audit logging.
+*
+* ## Lifecycle
+*
+* Elevation wraps `fastify.authenticate` so it always runs AFTER
+* authentication has set `request.user`. This avoids the `onRequest`
+* timing issue where `request.user` doesn't exist yet.
+*
+* Flow: `authenticate()` → user is set → `elevation check` → scope is set
+*
+* Inspired by Stripe Connect's `Stripe-Account` header.
+*
+* @example
+* ```typescript
+* const app = await createApp({
+*   auth: { type: 'betterAuth', betterAuth: adapter },
+*   elevation: {
+*     platformRoles: ['superadmin'],
+*     onElevation: (event) => auditLog.write(event),
+*   },
+* });
+* ```
+*/
+var elevation_exports = /* @__PURE__ */ __exportAll({
+	default: () => elevation_default,
+	elevationPlugin: () => elevationPlugin
+});
+const log = arcLog("elevation");
+const elevationPlugin = async (fastify, opts = {}) => {
+	const { platformRoles = ["superadmin"], scopeHeader = "x-arc-scope", orgHeader = "x-organization-id", onElevation } = opts;
+	if (!fastify.hasDecorator("authenticate")) {
+		log.warn("authenticate decorator not found. Register auth before elevation. Elevation will not function.");
+		return;
+	}
+	const originalAuthenticate = fastify.authenticate;
+	const authenticateWithElevation = async (request, reply) => {
+		await originalAuthenticate.call(fastify, request, reply);
+		if (reply.sent) return;
+		if (request.headers[scopeHeader] !== "platform") return;
+		const user = request.user;
+		if (!user) {
+			log.debug("Elevation requested but no user after auth");
+			reply.code(401).send({
+				success: false,
+				error: "Unauthorized",
+				message: "Authentication required for platform elevation",
+				code: "ELEVATION_AUTH_REQUIRED"
+			});
+			return;
+		}
+		const userRoles = getUserRoles(user);
+		if (!platformRoles.some((r) => userRoles.includes(r))) {
+			log.debug("Elevation rejected — insufficient roles", {
+				userId: user.id ?? user._id,
+				userRoles,
+				required: platformRoles
+			});
+			reply.code(403).send({
+				success: false,
+				error: "Forbidden",
+				message: "Insufficient privileges for platform elevation",
+				code: "ELEVATION_FORBIDDEN"
+			});
+			return;
+		}
+		const orgId = request.headers[orgHeader];
+		const userId = String(user.id ?? user._id ?? "unknown");
+		request.scope = {
+			kind: "elevated",
+			organizationId: orgId || void 0,
+			elevatedBy: userId
+		};
+		log.debug("Scope elevated", {
+			userId,
+			organizationId: orgId
+		});
+		if (onElevation) try {
+			await onElevation({
+				userId,
+				organizationId: orgId || void 0,
+				request,
+				timestamp: /* @__PURE__ */ new Date()
+			});
+		} catch {
+			log.warn("onElevation callback threw — continuing request");
+		}
+	};
+	fastify.authenticate = authenticateWithElevation;
+	log.debug("Plugin registered", {
+		platformRoles,
+		scopeHeader
+	});
+};
+var elevation_default = fp(elevationPlugin, {
+	name: "arc-elevation",
+	fastify: "5.x"
+});
+
+//#endregion
+export { elevation_default as n, elevation_exports as r, elevationPlugin as t };