@classytic/arc 2.41.0 → 2.43.0

package/dist/registerRoute-DRsSHPSM.mjs

@@ -1,364 +0,0 @@
-/*! @classytic/arc v2.41.0 | MIT | https://classytic.com */
-import { n as evaluateAndApplyPermission } from "./authorizationDecision-2YY_Kaj1.mjs";
-import { f as createError } from "./errors-C_YhELhe.mjs";
-import { u as getRequestScope } from "./types-CDy3-zw1.mjs";
-import { r as deriveHiddenFieldPermissions } from "./fields-BTyPLHK0.mjs";
-import { n as requestContext } from "./requestContext-cSVKnYPk.mjs";
-//#region src/core/middlewares/arcDecorator.ts
-/**
-* Build the `arcDecorator` preHandler for a resource.
-*
-* The decorator is a closure over frozen metadata — allocated once per
-* resource and shared across every request. Stamps `req.arc` with the
-* resource's field permissions, hooks, events bus, and schema options
-* so `sendControllerResponse`, `BaseController.run*`, and custom
-* middleware can read a consistent view.
-*
-* Also populates `requestContext.resourceName` for async-context access
-* in code paths that can't reach `req.arc` directly (e.g. detached logger
-* formatters).
-*/
-function buildArcDecorator(meta) {
-	const frozen = Object.freeze({
-		...meta,
-		fields: deriveHiddenFieldPermissions(meta.schemaOptions, meta.fields)
-	});
-	return async (req, _reply) => {
-		req.arc = frozen;
-		const store = requestContext.get();
-		if (store) store.resourceName = frozen.resourceName;
-	};
-}
-//#endregion
-//#region src/core/middlewares/auth.ts
-/**
-* A permission requires authentication unless it carries the `_isPublic`
-* marker set by `allowPublic()`. Absence of a permission is treated as
-* public (no auth) — matches historical CRUD behaviour.
-*/
-function requiresAuthentication(permission) {
-	if (!permission) return false;
-	return !permission._isPublic;
-}
-/**
-* Pick the right Fastify auth decorator for a single-permission route:
-*   - protected route → `fastify.authenticate` (401 on missing token)
-*   - public route    → `fastify.optionalAuthenticate` (parses token if present)
-*
-* Public routes still get optional auth so downstream multi-tenant filters
-* can narrow queries when a Bearer token IS supplied.
-*/
-function buildAuthMiddleware(fastify, permission) {
-	if (requiresAuthentication(permission)) return fastify.authenticate ?? null;
-	return fastify.optionalAuthenticate ?? null;
-}
-/**
-* Pick the right auth decorator for a multi-permission route (Action router).
-*
-* The input is the array of resolved per-action permissions — one slot per
-* action, in registration order, already flattened against `globalAuth`
-* fallback by the caller (`actionPermissions[name] ?? globalAuth`). A slot
-* may be `undefined` when the action has no per-action check AND no
-* `globalAuth` fallback — that is "public by omission" and must be honored
-* here the same way `buildActionPermissionMw` honors it (by skipping the
-* permission evaluation entirely). If we filtered undefineds out at this
-* layer, a mixed endpoint like `{ ping: undefined, promote: requireRoles(...) }`
-* would collapse to "all protected" and 401 the public `ping` action at the
-* auth layer before the permission prehandler could let it through.
-*
-* Rules:
-*   - ALL public (explicit allowPublic OR omission) → `optionalAuthenticate`
-*   - ALL protected                                 → `authenticate` (fail-fast)
-*   - MIXED                                         → `optionalAuthenticate`
-*     (parse token if present; per-action check fails-closed when user=null)
-*
-* The mixed case was previously handled by an in-handler
-* `fastify.authenticate()` call that bypassed the preHandler chain; this
-* helper moves that logic back into the preHandler stack so the request
-* lifecycle is consistent across router types.
-*/
-function buildAuthMiddlewareForPermissions(fastify, permissions) {
-	if (permissions.length === 0) return fastify.optionalAuthenticate ?? null;
-	const hasProtected = permissions.some((p) => requiresAuthentication(p));
-	const hasPublic = permissions.some((p) => p && p._isPublic === true) || permissions.some((p) => !p);
-	if (hasProtected && !hasPublic) return fastify.authenticate ?? null;
-	return fastify.optionalAuthenticate ?? null;
-}
-//#endregion
-//#region src/core/middlewares/chain.ts
-/**
-* Compose the route-level `onRequest` + `preHandler` arrays in the canonical
-* order. Every null/undefined entry is dropped. Keeps the three routers from
-* accidentally ordering the same ingredients differently (regression risk:
-* cache before auth → user-scoped cache keys leak across users; auth after
-* body parse → anonymous schema probing).
-*
-* onRequest constraints (Fastify lifecycle): `request.body` is undefined —
-* everything placed there must be header/cookie/param/query-driven. arc's
-* `authenticate` / `optionalAuthenticate` qualify by contract (Bearer
-* header, session cookie, api-key header); `preAuth` handlers exist
-* precisely to promote query tokens into headers (SSE `?token=`); the arc
-* decorator stamps static route metadata.
-*/
-function buildRouteHooks(parts) {
-	return {
-		onRequest: [
-			...parts.preAuth ?? [],
-			parts.arcDecorator,
-			parts.authMw ?? null
-		].filter(Boolean),
-		preHandler: [
-			parts.permissionMw ?? null,
-			parts.pluginMw ?? null,
-			...parts.routeGuards ?? [],
-			...parts.customMws ?? []
-		].filter(Boolean)
-	};
-}
-/**
-* Spread helper — turns `RouteHookChains` into the two Fastify route-option
-* fields, omitting empty arrays so routes without middleware stay
-* option-free (Fastify skips absent hooks faster than empty arrays).
-*/
-function routeHookOptions(hooks) {
-	return {
-		...hooks.onRequest.length > 0 ? { onRequest: hooks.onRequest } : {},
-		...hooks.preHandler.length > 0 ? { preHandler: hooks.preHandler } : {}
-	};
-}
-/**
-* `RouteDefinition.preHandler` accepts two shapes:
-*
-*   1. **Array form** — `RouteHandlerMethod[]`. Used directly.
-*   2. **Factory form** — `(fastify) => RouteHandlerMethod[]`. Called once at
-*      route-registration time with the Fastify instance, so handlers can
-*      capture decorators (`fastify.authenticate`, `fastify.events`, etc.)
-*      that aren't on the request.
-*
-* The two forms are equally idiomatic, but the discrimination is by
-* `typeof preHandler === "function"`. Single-function shapes such as
-* `multipartBody({...})` (a `RouteHandlerMethod`) **structurally satisfy
-* the factory branch** at the call site, then fail with a cryptic
-* `Cannot read properties of undefined (reading 'content-type')` once the
-* handler runs with `fastify` in the request slot.
-*
-* This resolver:
-*   1. Distinguishes the two valid shapes.
-*   2. Validates the factory's RETURN — must be an array of functions.
-*   3. Throws an actionable error pointing at the route + the fix when
-*      a single `RouteHandlerMethod` was passed instead of an array, OR
-*      when a factory returned the wrong shape.
-*
-* The error message names the route (`{method} {path}`) and the
-* canonical fix (`preHandler: [yourHandler]`) so the failure mode is
-* obvious instead of debug-archaeology.
-*
-* @param preHandler  The `route.preHandler` value (any of the valid shapes
-*                    plus the common bare-handler mistake).
-* @param fastify     Passed to factory-form preHandlers.
-* @param routeId     `"GET /todos/:id/attach"` (or similar) — used in the
-*                    error message so a multi-route file points at the
-*                    actual offender.
-*/
-function resolveRoutePreHandlers(preHandler, fastify, routeId) {
-	if (preHandler === void 0 || preHandler === null) return [];
-	if (Array.isArray(preHandler)) return preHandler.filter((h) => typeof h === "function");
-	if (typeof preHandler === "function") {
-		let result;
-		try {
-			result = preHandler(fastify);
-		} catch (err) {
-			const msg = err instanceof Error ? err.message : String(err);
-			throw new TypeError(`Route ${routeId}: preHandler factory threw during route registration: ${msg}.\nIf you intended to pass a single handler (e.g. \`multipartBody({...})\`), wrap it in an array: \`preHandler: [yourHandler]\`. The factory form is \`(fastify) => RouteHandlerMethod[]\` — it must return an array.`, { cause: err instanceof Error ? err : void 0 });
-		}
-		if (result && typeof result.then === "function") result.catch(() => void 0);
-		if (!Array.isArray(result)) throw new TypeError(`Route ${routeId}: preHandler factory must return an array of handlers, got ${describeValue(result)}.\nCommon cause: passing a single \`RouteHandlerMethod\` (e.g. \`multipartBody({...})\`) where an array was expected. Wrap it: \`preHandler: [yourHandler]\`. The factory form \`(fastify) => RouteHandlerMethod[]\` is for cases that need the Fastify instance — e.g. \`(fastify) => [fastify.authenticate, myHandler]\`.`);
-		return result.filter((h) => typeof h === "function");
-	}
-	throw new TypeError(`Route ${routeId}: preHandler must be an array of handlers OR a factory \`(fastify) => RouteHandlerMethod[]\`. Got ${describeValue(preHandler)}.`);
-}
-function describeValue(v) {
-	if (v === null) return "null";
-	if (v === void 0) return "undefined";
-	if (typeof v === "function") return "a function (single handler — wrap in array)";
-	if (Array.isArray(v)) return `an array of length ${v.length}`;
-	return `${typeof v} (${JSON.stringify(v).slice(0, 80)})`;
-}
-//#endregion
-//#region src/core/middlewares/permissions.ts
-/**
-* Build a PermissionContext from a Fastify request. Extracted so the CRUD
-* permission middleware and the dynamic action-permission check use the same
-* field layout — divergence here silently broke policy filters for actions.
-*/
-function buildPermissionContext(req, opts) {
-	const reqWithExtras = req;
-	const params = req.params;
-	return {
-		user: reqWithExtras.user ?? null,
-		scope: getRequestScope(req),
-		request: req,
-		resource: opts.resource,
-		action: opts.action,
-		resourceId: opts.resourceId ?? params?.id,
-		params,
-		data: opts.data ?? req.body
-	};
-}
-/**
-* Static per-route CRUD permission gate. The permission and action are known
-* at route-registration time, so the gate is a plain preHandler.
-*
-* Actions use the dynamic counterpart `buildActionPermissionMw` — their
-* permission is resolved from `body.action` at request time.
-*/
-function buildCrudPermissionMw(permissionCheck, resourceName, action) {
-	if (!permissionCheck) return null;
-	return async (req, reply) => {
-		const context = buildPermissionContext(req, {
-			resource: resourceName,
-			action
-		});
-		await evaluateAndApplyPermission(permissionCheck, context, req, reply);
-	};
-}
-/**
-* Dynamic per-action permission gate for the action router.
-*
-* Resolves the permission from `body.action` at request time and runs
-* `evaluateAndApplyPermission` from the canonical `permissionMw` slot — so
-* `_policyFilters` and `request.scope` are installed BEFORE `pluginMw`
-* (idempotency) and `routeGuards` run. Previously this check lived inside
-* the main action handler, which meant idempotency recorded unauthorized
-* requests and route guards saw unfiltered scope — the very divergence
-* routerShared exists to prevent.
-*
-* Also acts as a defensive fallback for invalid action names — the
-* `oneOf` body schema normally rejects these at AJV validation, but
-* hosts that disable schema validation still get a 400 here.
-*/
-function buildActionPermissionMw(actionEnum, actionPermissions, globalAuth, resourceName) {
-	const enumSet = new Set(actionEnum);
-	const validActions = [...actionEnum];
-	return async (req, reply) => {
-		const body = req.body ?? {};
-		const action = body.action;
-		if (!action || !enumSet.has(action)) throw createError(400, `Invalid action '${action ?? ""}'. Valid actions: ${validActions.join(", ")}`, { validActions });
-		const permissionCheck = actionPermissions[action] ?? globalAuth;
-		if (!permissionCheck) return;
-		const { action: _discard, ...data } = body;
-		const params = req.params;
-		const context = buildPermissionContext(req, {
-			resource: resourceName,
-			action,
-			resourceId: params?.id,
-			data
-		});
-		await evaluateAndApplyPermission(permissionCheck, context, req, reply, { defaultDenialMessage: (user) => user ? `Permission denied for '${action}'` : "Authentication required" });
-	};
-}
-//#endregion
-//#region src/core/middlewares/pluginMw.ts
-/**
-* Pick the request-lifecycle plugin middleware for an HTTP method:
-*   - GET / HEAD        → response cache (if present)
-*   - POST / PUT / PATCH → idempotency (if present)
-*   - DELETE            → none
-*
-* Either field may be `null` if the corresponding plugin wasn't registered.
-*/
-function selectPluginMw(method, mws) {
-	const upper = method.toUpperCase();
-	if (upper === "GET" || upper === "HEAD") return mws.cacheMw;
-	if (upper === "POST" || upper === "PUT" || upper === "PATCH") return mws.idempotencyMw;
-	return null;
-}
-/**
-* Resolve the default cache/idempotency middlewares for a resource.
-*
-* Skips response-cache when the resource has QueryCache active — QueryCache
-* handles caching at the controller level with SWR, so the HTTP-level
-* response-cache would double-cache.
-*/
-function resolveRouterPluginMw(fastify, resourceHasQueryCache) {
-	return {
-		cacheMw: !resourceHasQueryCache && fastify.hasDecorator("responseCache") ? fastify.responseCache.middleware : null,
-		idempotencyMw: fastify.hasDecorator("idempotency") ? fastify.idempotency.middleware : null
-	};
-}
-//#endregion
-//#region src/core/middlewares/rateLimit.ts
-/**
-* Build the per-route Fastify `config` object shared by the CRUD, custom, and
-* action routers. Two independent concerns ride on `routeOptions.config`:
-*   - `config.rateLimit`     — read by `@fastify/rate-limit`.
-*   - `config.cors`          — read by `@fastify/cors` as a per-route override.
-*   - `config.arcExtensions` — read by arc plugins (encryption, …) at request
-*     time, sourced from `defineResource({ extensions })`.
-*
-* Returns `{}` (no `config` key) when neither is present, so routes without
-* either stay config-free and the spread is a genuine no-op. Both fields are
-* optional in the return type, so no cast is needed when only one is set.
-*/
-function buildRouteConfig(rateLimitConfig, extensions, cors) {
-	const hasCors = cors !== void 0;
-	if (!rateLimitConfig && !extensions && !hasCors) return {};
-	return { config: {
-		...rateLimitConfig ?? {},
-		...hasCors ? { cors } : {},
-		...extensions ? { arcExtensions: extensions } : {}
-	} };
-}
-/**
-* Build the `config` object for Fastify route options so
-* @fastify/rate-limit picks up per-route overrides.
-*
-*   - `undefined`                 → no override (inherits instance config)
-*   - `false`                     → explicitly disable rate limiting
-*   - `{ max, timeWindow }`       → apply that limit
-*/
-function buildRateLimitConfig(rateLimit) {
-	if (rateLimit === void 0) return void 0;
-	if (rateLimit === false) return { rateLimit: false };
-	return { rateLimit: {
-		max: rateLimit.max,
-		timeWindow: rateLimit.timeWindow
-	} };
-}
-//#endregion
-//#region src/core/middlewares/registerRoute.ts
-/**
-* Register a route with friendly handling of `FST_ERR_DUPLICATED_ROUTE`.
-*
-* Boot-time `validateRouteCrudCollisions()` catches custom-route → auto-CRUD
-* overlaps before Fastify ever runs, but a few cases still slip through to
-* Fastify itself: two presets contributing the same `routes` entry, hosts
-* mounting two resources at the same prefix, custom routes that share a
-* URL with another plugin. Fastify's default message ("Method 'GET'
-* already declared for route '/'") gives no hint at the resource-shaped
-* fix — `disabledRoutes: ['list']` — so wrap it with one.
-*/
-function tryRegisterRoute(fastify, opts, context) {
-	try {
-		fastify.route(opts);
-	} catch (err) {
-		const fastifyErr = err;
-		if (fastifyErr?.code !== "FST_ERR_DUPLICATED_ROUTE") throw err;
-		const method = opts.method;
-		const url = opts.url;
-		const opHint = context.op ? ` (op: ${context.op})` : "";
-		const fixHint = context.op && [
-			"list",
-			"get",
-			"create",
-			"update",
-			"delete"
-		].includes(context.op) ? ` Suppress the auto-CRUD route with \`disabledRoutes: ['${context.op}']\`.` : " If a custom route in `routes:` collides with auto-CRUD, add `disabledRoutes: ['list' | 'get' | 'create' | 'update' | 'delete']` to `defineResource()` to suppress the matching auto-CRUD route.";
-		const enhanced = /* @__PURE__ */ new Error(`[arc] Duplicate route ${method} ${url} on resource "${context.resourceName}"${opHint}.${fixHint} Original: ${fastifyErr.message ?? "FST_ERR_DUPLICATED_ROUTE"}`);
-		enhanced.code = "FST_ERR_DUPLICATED_ROUTE";
-		enhanced.cause = err;
-		throw enhanced;
-	}
-}
-//#endregion
-export { selectPluginMw as a, buildRouteHooks as c, buildAuthMiddleware as d, buildAuthMiddlewareForPermissions as f, resolveRouterPluginMw as i, resolveRoutePreHandlers as l, buildRateLimitConfig as n, buildActionPermissionMw as o, buildArcDecorator as p, buildRouteConfig as r, buildCrudPermissionMw as s, tryRegisterRoute as t, routeHookOptions as u };

package/dist/sync/changelog.d.mts

@@ -1,3 +0,0 @@
-
-import { ChangeEntry, ChangeLogAppendOptions, ChangeLogStore, ChangeOp, ChangesPage, ChangesSinceOptions, CursorExpiredError, MemoryChangeLogStore, PushMutation, PushVerdict, PushVerdictStatus } from "@classytic/repo-core/sync";
-export { type ChangeEntry, type ChangeLogAppendOptions, type ChangeLogStore, type ChangeOp, type ChangesPage, type ChangesSinceOptions, CursorExpiredError, MemoryChangeLogStore, type PushMutation, type PushVerdict, type PushVerdictStatus };

package/dist/sync/changelog.mjs

@@ -1,3 +0,0 @@
-/*! @classytic/arc v2.41.0 | MIT | https://classytic.com */
-import { CursorExpiredError, MemoryChangeLogStore } from "@classytic/repo-core/sync";
-export { CursorExpiredError, MemoryChangeLogStore };