@classytic/arc 2.10.3 → 2.11.0

package/dist/middleware/index.d.mts

@@ -0,0 +1,109 @@
+import { I as MiddlewareHandler, L as RequestWithExtras, Q as MiddlewareConfig } from "../index-Cm0vUrr_.mjs";
+import { RouteHandlerMethod } from "fastify";
+
+//#region src/middleware/middleware.d.ts
+interface NamedMiddleware {
+  /** Unique name for debugging/introspection */
+  readonly name: string;
+  /** Operations this middleware applies to (default: all) */
+  readonly operations?: Array<"list" | "get" | "create" | "update" | "delete" | string>;
+  /** Priority — lower numbers run first (default: 10) */
+  readonly priority: number;
+  /** Conditional execution — return true to run, false to skip */
+  readonly when?: (request: RequestWithExtras) => boolean | Promise<boolean>;
+  /** The middleware handler */
+  readonly handler: MiddlewareHandler;
+}
+interface MiddlewareOptions {
+  operations?: NamedMiddleware["operations"];
+  priority?: number;
+  when?: NamedMiddleware["when"];
+  handler: MiddlewareHandler;
+}
+/**
+ * Create a named middleware with priority and conditions.
+ */
+declare function middleware(name: string, options: MiddlewareOptions): NamedMiddleware;
+/**
+ * Sort named middlewares by priority (ascending — lower runs first).
+ * Returns a MiddlewareConfig map keyed by operation, ready to pass to `defineResource()`.
+ */
+declare function sortMiddlewares(middlewares: NamedMiddleware[]): MiddlewareConfig;
+//#endregion
+//#region src/middleware/multipartBody.d.ts
+/** Parsed file from multipart form-data */
+interface ParsedFile {
+  /** Original filename */
+  filename: string;
+  /** MIME type */
+  mimetype: string;
+  /** File contents as Buffer */
+  buffer: Buffer;
+  /** File size in bytes */
+  size: number;
+  /** Form field name */
+  fieldname: string;
+}
+interface MultipartBodyOptions {
+  /**
+   * Maximum file size in bytes (default: 10MB).
+   * Files exceeding this are rejected with 413.
+   */
+  maxFileSize?: number;
+  /**
+   * Maximum number of files (default: 5).
+   * Extra files are silently ignored.
+   */
+  maxFiles?: number;
+  /**
+   * Allowed MIME types (default: all).
+   * Files with disallowed types are rejected with 415.
+   *
+   * Supports three forms in a single list:
+   *   - Exact: `image/png`
+   *   - Subtype wildcard: `image/\*` — any `image/…`
+   *   - Any:   `\*` or `\*\/\*` — equivalent to omitting the option
+   *
+   * @example ['image/jpeg', 'image/png', 'application/pdf']
+   * @example ['image/*', 'application/pdf']
+   * @example ['*']   // accept any type explicitly
+   */
+  allowedMimeTypes?: string[];
+  /**
+   * Key on `req.body` where parsed files are attached (default: '_files').
+   * Set to a custom key if '_files' conflicts with your schema.
+   *
+   * Note: this is the **destination** key — it controls where parsed files
+   * land on `req.body`, not which form fields are required. To enforce that
+   * a specific file field must be present in the request, use `requiredFields`.
+   */
+  filesKey?: string;
+  /**
+   * Multipart form field names that MUST be present in the request.
+   * Returns 400 with `{ success: false, error, code: 'MISSING_FILE_FIELDS' }`
+   * when any listed field is absent from the uploaded files.
+   *
+   * Only enforced when the request IS multipart — JSON requests still pass
+   * through as no-ops so the same middleware stays safe to add to shared
+   * create/update routes that accept both content types.
+   *
+   * @example ['file']                  // single-field upload (OCR, classify)
+   * @example ['avatar', 'cover']       // multi-field upload (profile editor)
+   */
+  requiredFields?: string[];
+}
+/**
+ * Create a multipart body parsing middleware.
+ *
+ * When a request has `content-type: multipart/form-data`, this middleware:
+ * 1. Reads all parts (fields + files)
+ * 2. Sets text fields on `req.body` as a plain object
+ * 3. Attaches file buffers to `req.body[filesKey]` (default: `req.body._files`)
+ *
+ * For non-multipart requests (regular JSON), this is a no-op — the request
+ * passes through unchanged. This makes it safe to add to create/update
+ * middlewares without breaking JSON clients.
+ */
+declare function multipartBody(options?: MultipartBodyOptions): RouteHandlerMethod;
+//#endregion
+export { type MultipartBodyOptions, type NamedMiddleware, type ParsedFile, middleware, multipartBody, sortMiddlewares };

package/dist/middleware/index.mjs

@@ -0,0 +1,70 @@
+import { t as CRUD_OPERATIONS } from "../constants-BhY1OHoH.mjs";
+import { t as multipartBody } from "../multipartBody-CvTR1Un6.mjs";
+//#region src/middleware/middleware.ts
+/**
+* Named Middleware — Priority-based, conditional middleware execution.
+*
+* Named middleware replaces flat arrays with structured, inspectable middleware
+* that runs in priority order and supports conditional execution.
+*
+* @example
+* ```typescript
+* import { middleware } from '@classytic/arc/middleware';
+*
+* const verifyEmail = middleware('verifyEmail', {
+*   operations: ['create', 'update'],
+*   priority: 5,
+*   when: (req) => !req.user?.emailVerified,
+*   handler: async (req, reply) => {
+*     reply.code(403).send({ error: 'Email verification required' });
+*   },
+* });
+*
+* const rateLimit = middleware('rateLimit', {
+*   priority: 1,
+*   handler: async (req, reply) => {
+*     // rate limit logic
+*   },
+* });
+*
+* const productResource = defineResource({
+*   name: 'product',
+*   adapter,
+*   middlewares: sortMiddlewares([verifyEmail, rateLimit]),
+* });
+* ```
+*/
+/**
+* Create a named middleware with priority and conditions.
+*/
+function middleware(name, options) {
+	return {
+		name,
+		operations: options.operations,
+		priority: options.priority ?? 10,
+		when: options.when,
+		handler: options.handler
+	};
+}
+/**
+* Sort named middlewares by priority (ascending — lower runs first).
+* Returns a MiddlewareConfig map keyed by operation, ready to pass to `defineResource()`.
+*/
+function sortMiddlewares(middlewares) {
+	const sorted = [...middlewares].sort((a, b) => a.priority - b.priority);
+	const operations = CRUD_OPERATIONS;
+	const result = {};
+	for (const op of operations) {
+		const applicable = sorted.filter((m) => !m.operations || m.operations.length === 0 || m.operations.includes(op));
+		if (applicable.length > 0) result[op] = applicable.map((m) => {
+			if (!m.when) return m.handler;
+			const wrapped = async (request, reply) => {
+				if (await m.when?.(request)) return m.handler(request, reply);
+			};
+			return wrapped;
+		});
+	}
+	return result;
+}
+//#endregion
+export { middleware, multipartBody, sortMiddlewares };

package/dist/multipartBody-CvTR1Un6.mjs

@@ -0,0 +1,123 @@
+//#region src/middleware/multipartBody.ts
+const DEFAULT_MAX_FILE_SIZE = 10 * 1024 * 1024;
+const DEFAULT_MAX_FILES = 5;
+const DEFAULT_FILES_KEY = "_files";
+/**
+* Build a matcher for MIME allow-lists that supports exact (e.g. `image/png`),
+* subtype wildcards (e.g. `image/\*`), and total wildcards (`\*` or `\*\/\*`).
+*
+* Returns `undefined` when no filter is needed — either because the option
+* was omitted or because a total wildcard was present.
+*/
+function buildMimeMatcher(allowed) {
+	if (!allowed || allowed.length === 0) return void 0;
+	const exact = /* @__PURE__ */ new Set();
+	const prefixes = [];
+	for (const entry of allowed) {
+		const value = entry.trim().toLowerCase();
+		if (!value) continue;
+		if (value === "*" || value === "*/*") return void 0;
+		if (value.endsWith("/*")) prefixes.push(value.slice(0, -1));
+		else exact.add(value);
+	}
+	if (exact.size === 0 && prefixes.length === 0) return void 0;
+	return {
+		matches(mime) {
+			const m = mime.toLowerCase();
+			if (exact.has(m)) return true;
+			for (const p of prefixes) if (m.startsWith(p)) return true;
+			return false;
+		},
+		describe() {
+			return [...exact, ...prefixes.map((p) => `${p}*`)].join(", ");
+		}
+	};
+}
+/**
+* Create a multipart body parsing middleware.
+*
+* When a request has `content-type: multipart/form-data`, this middleware:
+* 1. Reads all parts (fields + files)
+* 2. Sets text fields on `req.body` as a plain object
+* 3. Attaches file buffers to `req.body[filesKey]` (default: `req.body._files`)
+*
+* For non-multipart requests (regular JSON), this is a no-op — the request
+* passes through unchanged. This makes it safe to add to create/update
+* middlewares without breaking JSON clients.
+*/
+function multipartBody(options = {}) {
+	const maxFileSize = options.maxFileSize ?? DEFAULT_MAX_FILE_SIZE;
+	const maxFiles = options.maxFiles ?? DEFAULT_MAX_FILES;
+	const mimeMatcher = buildMimeMatcher(options.allowedMimeTypes);
+	const filesKey = options.filesKey ?? DEFAULT_FILES_KEY;
+	const requiredFields = options.requiredFields && options.requiredFields.length > 0 ? options.requiredFields : void 0;
+	return async function parseMultipartBody(request, reply) {
+		if (!(request.headers["content-type"] ?? "").includes("multipart/form-data")) return;
+		if (typeof request.parts !== "function") {
+			request.log.warn("multipartBody middleware: @fastify/multipart not registered. Ensure createApp() has multipart enabled (default) or install @fastify/multipart.");
+			return;
+		}
+		const body = {};
+		const files = {};
+		let fileCount = 0;
+		try {
+			const parts = request.parts();
+			for await (const part of parts) if (part.type === "file") {
+				if (fileCount >= maxFiles) continue;
+				if (mimeMatcher && !mimeMatcher.matches(part.mimetype)) return reply.code(415).send({
+					success: false,
+					error: `File type '${part.mimetype}' not allowed. Accepted: ${mimeMatcher.describe()}`
+				});
+				const buffer = await part.toBuffer();
+				if (buffer.length > maxFileSize) return reply.code(413).send({
+					success: false,
+					error: `File '${part.filename}' exceeds maximum size of ${Math.round(maxFileSize / 1024 / 1024)}MB`
+				});
+				files[part.fieldname] = {
+					filename: part.filename,
+					mimetype: part.mimetype,
+					buffer,
+					size: buffer.length,
+					fieldname: part.fieldname
+				};
+				fileCount++;
+			} else body[part.fieldname] = tryParseValue(part.value);
+		} catch (err) {
+			request.log.error({ err }, "multipartBody: failed to parse multipart form");
+			return reply.code(400).send({
+				success: false,
+				error: "Failed to parse multipart form data"
+			});
+		}
+		if (requiredFields) {
+			const missing = requiredFields.filter((name) => !(name in files));
+			if (missing.length > 0) return reply.code(400).send({
+				success: false,
+				error: `Missing required file field${missing.length > 1 ? "s" : ""}: ${missing.join(", ")}`,
+				code: "MISSING_FILE_FIELDS",
+				details: { missing }
+			});
+		}
+		if (fileCount > 0) body[filesKey] = files;
+		request.body = body;
+	};
+}
+/**
+* Try to parse a form field value as JSON, number, or boolean.
+* Falls back to the raw string if parsing fails.
+*/
+function tryParseValue(value) {
+	if (value === "true") return true;
+	if (value === "false") return false;
+	if (value === "null") return null;
+	if (/^-?\d+(\.\d+)?$/.test(value) && value.length < 16) {
+		const num = Number(value);
+		if (Number.isFinite(num)) return num;
+	}
+	if (value.startsWith("{") && value.endsWith("}") || value.startsWith("[") && value.endsWith("]")) try {
+		return JSON.parse(value);
+	} catch {}
+	return value;
+}
+//#endregion
+export { multipartBody as t };

package/dist/{openapi-B5F8AddX.mjs → openapi-C0L9ar7m.mjs}

@@ -1,6 +1,7 @@
 import { t as getUserRoles } from "./types-DV9WDfeg.mjs";
-import { n as convertRouteSchema } from "./schemaConverter-BxFDdtXu.mjs";
-import { t as buildActionBodySchema } from "./createActionRouter-Bp_5c_2b.mjs";
+import { n as convertRouteSchema } from "./schemaConverter-B0oKLuqI.mjs";
+import { t as resolveActionPermission } from "./actionPermissions-C8YYU92K.mjs";
+import { t as buildActionBodySchema } from "./createActionRouter-BwaSM0No.mjs";
 import fp from "fastify-plugin";
 //#region src/docs/openapi.ts
 const openApiPlugin = async (fastify, opts = {}) => {
@@ -327,12 +328,13 @@ function generateResourcePaths(resource, apiPrefix = "", additionalSecurity = []
 			const descStr = a.description ? ` — ${a.description}` : "";
 			descLines.push(`- \`${a.name}\`${roleStr}${descStr}`);
 		}
-		const fallbackPerm = resource.actionPermissions;
-		const fallbackRequiresAuth = typeof fallbackPerm === "function" && !fallbackPerm._isPublic;
 		const anyAuthRequired = resource.actions.some((a) => {
-			const p = a.permissions;
-			if (typeof p === "function") return !p._isPublic;
-			return fallbackRequiresAuth;
+			const effective = resolveActionPermission({
+				action: { permissions: a.permissions },
+				resourcePermissions: resource.permissions,
+				resourceActionPermissions: resource.actionPermissions
+			});
+			return typeof effective === "function" && !effective._isPublic;
 		});
 		if (!paths[actionPath]) paths[actionPath] = {};
 		paths[actionPath].post = createOperation(resource, "action", `Perform action (${actionEnum.join(" / ")})`, {

package/dist/org/index.d.mts

@@ -1,5 +1,5 @@
-import { d as UserBase } from "../fields-Lo1VUDpt.mjs";
-import { Ct as RouteHandler } from "../index-Cl0uoKd5.mjs";
+import { yt as RouteHandler } from "../index-Cm0vUrr_.mjs";
+import { d as UserBase } from "../fields-C8Y0XLAu.mjs";
 import { InvitationAdapter, InvitationDoc, MemberDoc, OrgAdapter, OrgDoc, OrgPermissionStatement, OrgRole, OrganizationPluginOptions } from "./types.mjs";
 import { FastifyPluginAsync, RouteHandlerMethod } from "fastify";
 

package/dist/permissions/index.d.mts

@@ -1,3 +1,3 @@
-import { a as applyFieldWritePermissions, c as PermissionCheck, d as UserBase, f as getUserRoles, i as applyFieldReadPermissions, l as PermissionContext, n as FieldPermissionMap, o as fields, p as normalizeRoles, r as FieldPermissionType, s as resolveEffectiveRoles, t as FieldPermission, u as PermissionResult } from "../fields-Lo1VUDpt.mjs";
-import { A as requireRoles, C as allOf, D as not, E as denyAll, M as when, N as applyPermissionResult, O as requireAuth, P as normalizePermissionResult, S as createOrgPermissions, T as anyOf, _ as ConnectEventsOptions, a as presets_d_exports, b as PermissionEventBus, c as readOnly, d as requireOrgRole, f as requireScopeContext, g as createRoleHierarchy, h as RoleHierarchy, i as ownerWithAdminBypass, j as roles, k as requireOwnership, l as requireOrgInScope, m as requireTeamMembership, n as authenticated, o as publicRead, p as requireServiceScope, r as fullPublic, s as publicReadAdminWrite, t as adminOnly, u as requireOrgMembership, v as DynamicPermissionMatrix, w as allowPublic, x as createDynamicPermissionMatrix, y as DynamicPermissionMatrixConfig } from "../index-ChIw3776.mjs";
+import { a as applyFieldWritePermissions, c as PermissionCheck, d as UserBase, f as getUserRoles, i as applyFieldReadPermissions, l as PermissionContext, n as FieldPermissionMap, o as fields, p as normalizeRoles, r as FieldPermissionType, s as resolveEffectiveRoles, t as FieldPermission, u as PermissionResult } from "../fields-C8Y0XLAu.mjs";
+import { A as requireRoles, C as allOf, D as not, E as denyAll, M as when, N as applyPermissionResult, O as requireAuth, P as normalizePermissionResult, S as createOrgPermissions, T as anyOf, _ as ConnectEventsOptions, a as presets_d_exports, b as PermissionEventBus, c as readOnly, d as requireOrgRole, f as requireScopeContext, g as createRoleHierarchy, h as RoleHierarchy, i as ownerWithAdminBypass, j as roles, k as requireOwnership, l as requireOrgInScope, m as requireTeamMembership, n as authenticated, o as publicRead, p as requireServiceScope, r as fullPublic, s as publicReadAdminWrite, t as adminOnly, u as requireOrgMembership, v as DynamicPermissionMatrix, w as allowPublic, x as createDynamicPermissionMatrix, y as DynamicPermissionMatrixConfig } from "../index-BYCqHCVu.mjs";
 export { ConnectEventsOptions, DynamicPermissionMatrix, DynamicPermissionMatrixConfig, FieldPermission, FieldPermissionMap, FieldPermissionType, PermissionCheck, PermissionContext, PermissionEventBus, PermissionResult, RoleHierarchy, UserBase, adminOnly, allOf, allowPublic, anyOf, applyFieldReadPermissions, applyFieldWritePermissions, applyPermissionResult, authenticated, createDynamicPermissionMatrix, createOrgPermissions, createRoleHierarchy, denyAll, fields, fullPublic, getUserRoles, normalizePermissionResult, normalizeRoles, not, ownerWithAdminBypass, presets_d_exports as permissions, publicRead, publicReadAdminWrite, readOnly, requireAuth, requireOrgInScope, requireOrgMembership, requireOrgRole, requireOwnership, requireRoles, requireScopeContext, requireServiceScope, requireTeamMembership, resolveEffectiveRoles, roles, when };

package/dist/permissions/index.mjs

@@ -1,5 +1,3 @@
-import { i as resolveEffectiveRoles, n as applyFieldWritePermissions, r as fields, t as applyFieldReadPermissions } from "../fields-bxkeltzz.mjs";
+import { A as normalizePermissionResult, C as requireAuth, D as when, E as roles, M as applyFieldWritePermissions, N as fields, O as applyPermissionResult, P as resolveEffectiveRoles, S as not, T as requireRoles, _ as requireTeamMembership, a as presets_exports, b as anyOf, c as readOnly, d as createOrgPermissions, f as requireOrgInScope, g as requireServiceScope, h as requireScopeContext, i as ownerWithAdminBypass, j as applyFieldReadPermissions, l as createRoleHierarchy, m as requireOrgRole, n as authenticated, o as publicRead, p as requireOrgMembership, r as fullPublic, s as publicReadAdminWrite, t as adminOnly, u as createDynamicPermissionMatrix, v as allOf, w as requireOwnership, x as denyAll, y as allowPublic } from "../permissions-B4vU9L0Q.mjs";
 import { n as normalizeRoles, t as getUserRoles } from "../types-DV9WDfeg.mjs";
-import { n as normalizePermissionResult, t as applyPermissionResult } from "../applyPermissionResult-QhV1Pa-g.mjs";
-import { C as requireAuth, D as when, E as roles, S as not, T as requireRoles, _ as requireTeamMembership, a as presets_exports, b as anyOf, c as readOnly, d as createOrgPermissions, f as requireOrgInScope, g as requireServiceScope, h as requireScopeContext, i as ownerWithAdminBypass, l as createRoleHierarchy, m as requireOrgRole, n as authenticated, o as publicRead, p as requireOrgMembership, r as fullPublic, s as publicReadAdminWrite, t as adminOnly, u as createDynamicPermissionMatrix, v as allOf, w as requireOwnership, x as denyAll, y as allowPublic } from "../permissions-Dk6mshja.mjs";
 export { adminOnly, allOf, allowPublic, anyOf, applyFieldReadPermissions, applyFieldWritePermissions, applyPermissionResult, authenticated, createDynamicPermissionMatrix, createOrgPermissions, createRoleHierarchy, denyAll, fields, fullPublic, getUserRoles, normalizePermissionResult, normalizeRoles, not, ownerWithAdminBypass, presets_exports as permissions, publicRead, publicReadAdminWrite, readOnly, requireAuth, requireOrgInScope, requireOrgMembership, requireOrgRole, requireOwnership, requireRoles, requireScopeContext, requireServiceScope, requireTeamMembership, resolveEffectiveRoles, roles, when };

package/dist/{permissions-Dk6mshja.mjs → permissions-B4vU9L0Q.mjs}

@@ -1,8 +1,226 @@
 import { t as __exportAll } from "./chunk-BpYLSNr0.mjs";
 import { _ as isElevated, b as isService, c as getRequestScope, d as getServiceScopes, f as getTeamId, h as hasOrgAccess, l as getScopeContext, p as getUserId, u as getScopeContextMap, v as isMember, y as isOrgInScope } from "./types-AOD8fxIw.mjs";
 import { t as getUserRoles } from "./types-DV9WDfeg.mjs";
-import { t as MemoryCacheStore } from "./memory-B5Amv9A1.mjs";
+import { t as MemoryCacheStore } from "./memory-DikHSvWa.mjs";
 import { randomUUID } from "node:crypto";
+//#region src/permissions/fields.ts
+/**
+* Field-Level Permissions
+*
+* Control field visibility and writability per role.
+* Integrated into the response path (read) and sanitization path (write).
+*
+* @example
+* ```typescript
+* import { fields, defineResource } from '@classytic/arc';
+*
+* const userResource = defineResource({
+*   name: 'user',
+*   adapter: userAdapter,
+*   fields: {
+*     salary: fields.visibleTo(['admin', 'hr']),
+*     internalNotes: fields.writableBy(['admin']),
+*     email: fields.redactFor(['viewer']),
+*     password: fields.hidden(),
+*   },
+* });
+* ```
+*/
+/** Type guard for Mongoose-like documents with toObject() */
+function isMongooseDoc(obj) {
+	return !!obj && typeof obj === "object" && "toObject" in obj && typeof obj.toObject === "function";
+}
+const fields = {
+	hidden() {
+		return { _type: "hidden" };
+	},
+	visibleTo(roles) {
+		return {
+			_type: "visibleTo",
+			roles
+		};
+	},
+	writableBy(roles) {
+		return {
+			_type: "writableBy",
+			roles
+		};
+	},
+	redactFor(roles, redactValue = "***") {
+		return {
+			_type: "redactFor",
+			roles,
+			redactValue
+		};
+	}
+};
+/**
+* Apply field-level READ permissions to a response object.
+* Strips hidden fields, enforces visibility, and applies redaction.
+*
+* @param data - The response object (mutated in place for performance)
+* @param fieldPermissions - Field permission map from resource config
+* @param userRoles - Current user's roles (empty array for unauthenticated)
+* @returns The filtered object
+*/
+function applyFieldReadPermissions(data, fieldPermissions, userRoles) {
+	if (!data || typeof data !== "object") return data;
+	const result = { ...isMongooseDoc(data) ? data.toObject() : data };
+	for (const [field, perm] of Object.entries(fieldPermissions)) switch (perm._type) {
+		case "hidden":
+			delete result[field];
+			break;
+		case "visibleTo":
+			if (!perm.roles?.some((r) => userRoles.includes(r))) delete result[field];
+			break;
+		case "redactFor":
+			if (perm.roles?.some((r) => userRoles.includes(r))) result[field] = perm.redactValue ?? "***";
+			break;
+		case "writableBy": break;
+	}
+	return result;
+}
+/**
+* Apply field-level WRITE permissions to request body.
+*
+* Returns both the filtered body and the list of denied fields. Callers are
+* expected to reject the request when `deniedFields.length > 0` — silently
+* stripping fields hides misconfigurations and real attacks. See
+* `BodySanitizer` for the default policy.
+*
+* @param body - The request body (returns a new filtered copy)
+* @param fieldPermissions - Field permission map from resource config
+* @param userRoles - Current user's roles
+*/
+function applyFieldWritePermissions(body, fieldPermissions, userRoles) {
+	const result = { ...body };
+	const deniedFields = [];
+	for (const [field, perm] of Object.entries(fieldPermissions)) switch (perm._type) {
+		case "hidden":
+			if (field in result) {
+				deniedFields.push(field);
+				delete result[field];
+			}
+			break;
+		case "writableBy":
+			if (field in result && !perm.roles?.some((r) => userRoles.includes(r))) {
+				deniedFields.push(field);
+				delete result[field];
+			}
+			break;
+	}
+	return {
+		body: result,
+		deniedFields
+	};
+}
+/**
+* Resolve effective roles by merging global user roles with org-level roles.
+*
+* Global roles come from `req.user.role` (normalized via getUserRoles()).
+* Org roles come from `req.context.orgRoles` (set by BA adapter's org bridge).
+*
+* When no org context exists, returns global roles only — backward compatible.
+*/
+function resolveEffectiveRoles(userRoles, orgRoles) {
+	if (orgRoles.length === 0) return [...userRoles];
+	if (userRoles.length === 0) return [...orgRoles];
+	return [...new Set([...userRoles, ...orgRoles])];
+}
+//#endregion
+//#region src/permissions/applyPermissionResult.ts
+/**
+* Normalize a permission check return value (`boolean | PermissionResult`)
+* into a concrete `PermissionResult`. This is the only place in Arc that
+* promotes booleans to results — keeps the type narrowing honest everywhere.
+*/
+function normalizePermissionResult(result) {
+	if (typeof result === "boolean") return { granted: result };
+	return result;
+}
+/**
+* Apply a granted `PermissionResult` to a Fastify request — merges row-level
+* filters into `_policyFilters` and conditionally installs the scope.
+*
+* **Scope install rule:** only writes `scope` when the current request scope
+* is absent or `public`. This prevents downgrading an already-authenticated
+* request (e.g. Better Auth set `member`, then a permission check returns a
+* narrower `service` scope — the original `member` wins because it came from
+* a more authoritative source).
+*
+* Safe to call with a non-granted result — it simply no-ops. Callers should
+* still check `result.granted` and send an error response before reaching here,
+* but this function tolerates the misuse defensively.
+*/
+function applyPermissionResult(result, request) {
+	if (!result.granted) return;
+	if (result.filters) request._policyFilters = {
+		...request._policyFilters ?? {},
+		...result.filters
+	};
+	if (result.scope) {
+		const current = request.scope;
+		if (!current || current.kind === "public") request.scope = result.scope;
+	}
+}
+/**
+* Max length of a `PermissionResult.reason` string before we fall back to the
+* generic default message. Upstream checks can return arbitrary strings; we
+* clamp to prevent accidental leakage of internal diagnostics or oversized
+* payloads via the 4xx response body.
+*/
+const MAX_DENIAL_REASON_LENGTH = 100;
+/**
+* End-to-end evaluator: runs the permission check, catches throws, normalizes
+* the result, sends a 401/403 response on denial, and applies side-effects on
+* grant. Returns `true` if the caller should continue, `false` if a response
+* has been sent and the caller should return.
+*
+* This is the single source of truth for the 5-step sequence shared by the
+* CRUD router, action router, and MCP tool handlers:
+*
+*   1. `try { await check(ctx) } catch { reply 403 }`
+*   2. `normalizePermissionResult(result)`
+*   3. If denied → 401 (no user) or 403 (user) with clamped reason
+*   4. If granted → `applyPermissionResult` (filters + scope)
+*   5. Return true/false so the caller knows whether to keep going
+*
+* Context construction, pre-check auth gating, and success-path handler
+* invocation stay at the callsite — those are genuinely different per router
+* and don't belong here.
+*
+* @returns `true` if authorized (caller continues), `false` if a response was sent
+*/
+async function evaluateAndApplyPermission(check, context, request, reply, opts) {
+	let result;
+	try {
+		result = await check(context);
+	} catch (err) {
+		request.log?.warn?.({
+			err,
+			resource: context.resource,
+			action: context.action
+		}, "Permission check threw");
+		reply.code(403).send({
+			success: false,
+			error: "Permission denied"
+		});
+		return false;
+	}
+	const permResult = normalizePermissionResult(result);
+	if (!permResult.granted) {
+		const defaultMsg = opts?.defaultDenialMessage?.(context.user) ?? (context.user ? "Permission denied" : "Authentication required");
+		const reason = permResult.reason && permResult.reason.length <= MAX_DENIAL_REASON_LENGTH ? permResult.reason : defaultMsg;
+		reply.code(context.user ? 403 : 401).send({
+			success: false,
+			error: reason
+		});
+		return false;
+	}
+	applyPermissionResult(permResult, request);
+	return true;
+}
+//#endregion
 //#region src/permissions/core.ts
 /**
 * Normalize a `string | [readonly string[]]` rest-args tuple into a single
@@ -1002,4 +1220,4 @@ function readOnly(overrides) {
 	}, overrides);
 }
 //#endregion
-export { requireAuth as C, when as D, roles as E, not as S, requireRoles as T, requireTeamMembership as _, presets_exports as a, anyOf as b, readOnly as c, createOrgPermissions as d, requireOrgInScope as f, requireServiceScope as g, requireScopeContext as h, ownerWithAdminBypass as i, createRoleHierarchy as l, requireOrgRole as m, authenticated as n, publicRead as o, requireOrgMembership as p, fullPublic as r, publicReadAdminWrite as s, adminOnly as t, createDynamicPermissionMatrix as u, allOf as v, requireOwnership as w, denyAll as x, allowPublic as y };
+export { normalizePermissionResult as A, requireAuth as C, when as D, roles as E, applyFieldWritePermissions as M, fields as N, applyPermissionResult as O, resolveEffectiveRoles as P, not as S, requireRoles as T, requireTeamMembership as _, presets_exports as a, anyOf as b, readOnly as c, createOrgPermissions as d, requireOrgInScope as f, requireServiceScope as g, requireScopeContext as h, ownerWithAdminBypass as i, applyFieldReadPermissions as j, evaluateAndApplyPermission as k, createRoleHierarchy as l, requireOrgRole as m, authenticated as n, publicRead as o, requireOrgMembership as p, fullPublic as r, publicReadAdminWrite as s, adminOnly as t, createDynamicPermissionMatrix as u, allOf as v, requireOwnership as w, denyAll as x, allowPublic as y };

package/dist/pipe-DVoIheVC.mjs

@@ -0,0 +1,62 @@
+import { r as ForbiddenError } from "./errors-D5c-5BJL.mjs";
+//#region src/pipeline/pipe.ts
+/**
+* Compose pipeline steps into an ordered array.
+* Accepts guards, transforms, and interceptors in any order.
+*/
+function pipe(...steps) {
+	return steps;
+}
+/**
+* Check if a step applies to the given operation.
+*/
+function appliesTo(step, operation) {
+	if (!step.operations || step.operations.length === 0) return true;
+	return step.operations.includes(operation);
+}
+/**
+* Execute a pipeline against a request context.
+*
+* This is the core runtime that createCrudRouter uses to execute pipelines.
+* External usage is not needed — this is wired automatically when `pipe` is set.
+*
+* @param steps - Pipeline steps to execute
+* @param ctx - The pipeline context (extends IRequestContext)
+* @param handler - The actual controller method to call
+* @param operation - The CRUD operation name
+* @returns The controller response (possibly modified by interceptors)
+*/
+async function executePipeline(steps, ctx, handler, operation) {
+	const guards = [];
+	const transforms = [];
+	const interceptors = [];
+	for (const step of steps) {
+		if (!appliesTo(step, operation)) continue;
+		switch (step._type) {
+			case "guard":
+				guards.push(step);
+				break;
+			case "transform":
+				transforms.push(step);
+				break;
+			case "interceptor":
+				interceptors.push(step);
+				break;
+		}
+	}
+	for (const g of guards) if (!await g.handler(ctx)) throw new ForbiddenError(`Guard '${g.name}' denied access`);
+	let currentCtx = ctx;
+	for (const t of transforms) {
+		const result = await t.handler(currentCtx);
+		if (result) currentCtx = result;
+	}
+	let chain = () => handler(currentCtx);
+	for (let i = interceptors.length - 1; i >= 0; i--) {
+		const interceptor = interceptors[i];
+		const next = chain;
+		chain = () => interceptor.handler(currentCtx, next);
+	}
+	return chain();
+}
+//#endregion
+export { pipe as n, executePipeline as t };