@classytic/arc 1.0.0

package/dist/org/index.js

@@ -0,0 +1,220 @@
+import fp from 'fastify-plugin';
+
+// src/org/orgScopePlugin.ts
+function createOrgContext(orgId, options = {}) {
+  return {
+    organizationId: orgId,
+    orgScope: options.orgScope ?? "explicit",
+    orgRoles: options.orgRoles ?? [],
+    ...options
+  };
+}
+var orgScopePlugin = async (fastify, opts = {}) => {
+  const {
+    header = "x-organization-id",
+    bypassRoles = ["superadmin"],
+    userOrgsPath = "organizations",
+    validateMembership
+  } = opts;
+  if (!fastify.hasRequestDecorator("context")) {
+    fastify.decorateRequest("context", void 0);
+  }
+  if (!fastify.hasRequestDecorator("organizationId")) {
+    fastify.decorateRequest("organizationId", void 0);
+  }
+  fastify.decorate("organizationScoped", function organizationScoped(options = {}) {
+    const { required = true } = options;
+    return async function organizationScopePreHandler(request, reply) {
+      const user = request.user;
+      const userWithRoles = user;
+      const roles = Array.isArray(userWithRoles?.roles) ? userWithRoles.roles : userWithRoles?.roles ? [String(userWithRoles.roles)] : [];
+      const orgIdFromHeader = request.headers[header]?.toString().trim();
+      const isAuthenticated = !!user;
+      const isSuperadmin = bypassRoles.some((role) => roles.includes(role));
+      const req = request;
+      req.context = req.context ?? {};
+      if (!orgIdFromHeader) {
+        if (isSuperadmin) {
+          request.log?.debug?.({ msg: "Superadmin - no org filter required" });
+          req.context.orgScope = "global";
+          return;
+        }
+        if (required) {
+          reply.code(403).send({
+            success: false,
+            error: "Organization context required",
+            code: "ORG_HEADER_REQUIRED",
+            message: "x-organization-id header required"
+          });
+          return;
+        }
+        request.log?.debug?.({ msg: "No org filter - showing all public data" });
+        req.context.orgScope = "public";
+        return;
+      }
+      if (!isAuthenticated) {
+        request.log?.warn?.({
+          msg: "Organization filtering requires authentication",
+          headerOrgId: orgIdFromHeader
+        });
+        reply.code(401).send({
+          success: false,
+          error: "Authentication required to filter by organization",
+          code: "AUTH_REQUIRED_FOR_ORG"
+        });
+        return;
+      }
+      if (isSuperadmin) {
+        request.log?.debug?.({
+          msg: "Superadmin accessing organization",
+          orgId: orgIdFromHeader
+        });
+        req.organizationId = orgIdFromHeader;
+        req.context.organizationId = orgIdFromHeader;
+        req.context.orgScope = "bypass";
+        req.context.bypassReason = "superadmin";
+        return;
+      }
+      const userOrgs = user?.[userOrgsPath] ?? [];
+      let hasAccess = false;
+      if (validateMembership) {
+        hasAccess = await validateMembership(user, orgIdFromHeader);
+      } else {
+        hasAccess = userOrgs.some((org) => {
+          const memberOrgId = org.organizationId?.toString() ?? String(org);
+          return memberOrgId === orgIdFromHeader;
+        });
+      }
+      if (!hasAccess) {
+        request.log?.warn?.({
+          msg: "Access denied - user not member of organization",
+          userId: user._id ?? user.id,
+          requestedOrgId: orgIdFromHeader,
+          userOrgIds: userOrgs.map((o) => o.organizationId?.toString() ?? String(o))
+        });
+        reply.code(403).send({
+          success: false,
+          error: "No access to this organization",
+          code: "ORG_ACCESS_DENIED"
+        });
+        return;
+      }
+      req.organizationId = orgIdFromHeader;
+      req.context.organizationId = orgIdFromHeader;
+      req.context.orgScope = "member";
+      const orgMembership = userOrgs.find((o) => {
+        const memberOrgId = o.organizationId?.toString() ?? String(o);
+        return memberOrgId === orgIdFromHeader;
+      });
+      req.context.orgRoles = orgMembership?.roles ?? [];
+      request.log?.debug?.({
+        msg: "Organization context set",
+        orgId: orgIdFromHeader,
+        userId: user._id ?? user.id,
+        orgRoles: req.context.orgRoles
+      });
+    };
+  });
+  fastify.decorate("createOrgContext", createOrgContext);
+  fastify.log?.info?.("Organization scope plugin registered");
+};
+var orgScopePlugin_default = fp(orgScopePlugin, {
+  name: "arc-org-scope",
+  fastify: "5.x"
+});
+
+// src/org/orgGuard.ts
+function orgGuard(options = {}) {
+  const {
+    requireOrgContext = true,
+    roles = [],
+    allowGlobal = false
+  } = options;
+  return async function orgGuardMiddleware(request, reply) {
+    const context = request.context ?? {};
+    const user = request.user;
+    const userWithRoles = user;
+    if (allowGlobal && userWithRoles?.roles?.includes("superadmin")) {
+      return;
+    }
+    if (requireOrgContext && !context.organizationId) {
+      reply.code(403).send({
+        success: false,
+        error: "Organization context required",
+        code: "ORG_CONTEXT_REQUIRED",
+        message: "This endpoint requires an organization context. Please specify organization via x-organization-id header."
+      });
+      return;
+    }
+    if (roles.length > 0 && context.organizationId) {
+      const contextWithRoles = context;
+      const userOrgRoles = contextWithRoles.orgRoles ?? [];
+      const hasRequiredRole = roles.some((role) => userOrgRoles.includes(role));
+      if (!hasRequiredRole && !userWithRoles?.roles?.includes("superadmin")) {
+        reply.code(403).send({
+          success: false,
+          error: "Insufficient organization permissions",
+          code: "ORG_ROLE_REQUIRED",
+          message: `This action requires one of these organization roles: ${roles.join(", ")}`,
+          required: roles,
+          current: userOrgRoles
+        });
+        return;
+      }
+    }
+  };
+}
+function requireOrg() {
+  return orgGuard({ requireOrgContext: true });
+}
+function requireOrgRole(...roles) {
+  return orgGuard({ requireOrgContext: true, roles });
+}
+
+// src/org/orgMembership.ts
+async function orgMembershipCheck(user, orgId, options = {}) {
+  const {
+    userOrgsPath = "organizations",
+    bypassRoles = ["superadmin"],
+    validateFromDb
+  } = options;
+  if (!user || !orgId) return false;
+  const userWithRoles = user;
+  const userRoles = userWithRoles.roles ?? [];
+  if (bypassRoles.some((role) => userRoles.includes(role))) {
+    return true;
+  }
+  const userOrgs = user[userOrgsPath] ?? [];
+  const isMemberFromUser = userOrgs.some((o) => {
+    const memberOrgId = o.organizationId?.toString() ?? String(o);
+    return memberOrgId === orgId.toString();
+  });
+  if (isMemberFromUser) return true;
+  if (validateFromDb) {
+    const userId = (user._id ?? user.id)?.toString();
+    if (userId) {
+      return validateFromDb(userId, orgId);
+    }
+  }
+  return false;
+}
+function getOrgRoles(user, orgId, options = {}) {
+  const { userOrgsPath = "organizations" } = options;
+  if (!user || !orgId) return [];
+  const userOrgs = user[userOrgsPath] ?? [];
+  const membership = userOrgs.find((o) => {
+    const memberOrgId = o.organizationId?.toString() ?? String(o);
+    return memberOrgId === orgId.toString();
+  });
+  const membershipRoles = membership;
+  return membershipRoles?.roles ?? [];
+}
+function hasOrgRole(user, orgId, roles, options = {}) {
+  const userOrgRoles = getOrgRoles(user, orgId, options);
+  const requiredRoles = Array.isArray(roles) ? roles : [roles];
+  const userWithRoles = user;
+  if (userWithRoles?.roles?.includes("superadmin")) return true;
+  return requiredRoles.some((role) => userOrgRoles.includes(role));
+}
+
+export { createOrgContext, getOrgRoles, hasOrgRole, orgGuard, orgMembershipCheck, orgScopePlugin_default as orgScopePlugin, orgScopePlugin as orgScopePluginFn, requireOrg, requireOrgRole };

package/dist/permissions/index.d.ts

@@ -0,0 +1,144 @@
+import { P as PermissionCheck, a as PermissionContext } from '../types-B99TBmFV.js';
+export { b as PermissionResult, U as UserBase } from '../types-B99TBmFV.js';
+import 'fastify';
+
+/**
+ * Permission System
+ *
+ * Clean, function-based permission system.
+ * PermissionCheck is THE ONLY way to define permissions.
+ *
+ * @example
+ * ```typescript
+ * import { allowPublic, requireAuth, requireRoles } from '@classytic/arc/permissions';
+ *
+ * defineResource({
+ *   permissions: {
+ *     list: allowPublic(),
+ *     get: allowPublic(),
+ *     create: requireAuth(),
+ *     update: requireRoles(['admin', 'editor']),
+ *     delete: requireRoles(['admin']),
+ *   }
+ * });
+ * ```
+ */
+
+/**
+ * Allow public access (no authentication required)
+ *
+ * @example
+ * ```typescript
+ * permissions: {
+ *   list: allowPublic(),
+ *   get: allowPublic(),
+ * }
+ * ```
+ */
+declare function allowPublic(): PermissionCheck;
+/**
+ * Require authentication (any authenticated user)
+ *
+ * @example
+ * ```typescript
+ * permissions: {
+ *   create: requireAuth(),
+ *   update: requireAuth(),
+ * }
+ * ```
+ */
+declare function requireAuth(): PermissionCheck;
+/**
+ * Require specific roles
+ *
+ * @param roles - Required roles (user needs at least one)
+ * @param options - Optional bypass roles
+ *
+ * @example
+ * ```typescript
+ * permissions: {
+ *   create: requireRoles(['admin', 'editor']),
+ *   delete: requireRoles(['admin']),
+ * }
+ *
+ * // With bypass roles
+ * permissions: {
+ *   update: requireRoles(['owner'], { bypassRoles: ['admin', 'superadmin'] }),
+ * }
+ * ```
+ */
+declare function requireRoles(roles: readonly string[], options?: {
+    bypassRoles?: readonly string[];
+}): PermissionCheck;
+/**
+ * Require resource ownership
+ *
+ * Returns filters to scope queries to user's owned resources.
+ *
+ * @param ownerField - Field containing owner ID (default: 'userId')
+ * @param options - Optional bypass roles
+ *
+ * @example
+ * ```typescript
+ * permissions: {
+ *   update: requireOwnership('userId'),
+ *   delete: requireOwnership('createdBy', { bypassRoles: ['admin'] }),
+ * }
+ * ```
+ */
+declare function requireOwnership(ownerField?: string, options?: {
+    bypassRoles?: readonly string[];
+}): PermissionCheck;
+/**
+ * Combine multiple checks - ALL must pass (AND logic)
+ *
+ * @example
+ * ```typescript
+ * permissions: {
+ *   update: allOf(
+ *     requireAuth(),
+ *     requireRoles(['editor']),
+ *     requireOwnership('createdBy')
+ *   ),
+ * }
+ * ```
+ */
+declare function allOf(...checks: PermissionCheck[]): PermissionCheck;
+/**
+ * Combine multiple checks - ANY must pass (OR logic)
+ *
+ * @example
+ * ```typescript
+ * permissions: {
+ *   update: anyOf(
+ *     requireRoles(['admin']),
+ *     requireOwnership('createdBy')
+ *   ),
+ * }
+ * ```
+ */
+declare function anyOf(...checks: PermissionCheck[]): PermissionCheck;
+/**
+ * Deny all access
+ *
+ * @example
+ * ```typescript
+ * permissions: {
+ *   delete: denyAll('Deletion not allowed'),
+ * }
+ * ```
+ */
+declare function denyAll(reason?: string): PermissionCheck;
+/**
+ * Dynamic permission based on context
+ *
+ * @example
+ * ```typescript
+ * permissions: {
+ *   update: when((ctx) => ctx.data?.status === 'draft'),
+ * }
+ * ```
+ */
+declare function when(condition: (ctx: PermissionContext) => boolean | Promise<boolean>): PermissionCheck;
+
+export { PermissionCheck, PermissionContext, allOf, allowPublic, anyOf, denyAll, requireAuth, requireOwnership, requireRoles, when };

package/dist/permissions/index.js

@@ -0,0 +1,100 @@
+// src/permissions/index.ts
+function allowPublic() {
+  const check = () => true;
+  check._isPublic = true;
+  return check;
+}
+function requireAuth() {
+  return (ctx) => {
+    if (!ctx.user) {
+      return { granted: false, reason: "Authentication required" };
+    }
+    return true;
+  };
+}
+function requireRoles(roles, options) {
+  return (ctx) => {
+    if (!ctx.user) {
+      return { granted: false, reason: "Authentication required" };
+    }
+    const userRoles = ctx.user.roles ?? [];
+    if (options?.bypassRoles?.some((r) => userRoles.includes(r))) {
+      return true;
+    }
+    if (roles.some((r) => userRoles.includes(r))) {
+      return true;
+    }
+    return {
+      granted: false,
+      reason: `Required roles: ${roles.join(", ")}`
+    };
+  };
+}
+function requireOwnership(ownerField = "userId", options) {
+  return (ctx) => {
+    if (!ctx.user) {
+      return { granted: false, reason: "Authentication required" };
+    }
+    const userRoles = ctx.user.roles ?? [];
+    if (options?.bypassRoles?.some((r) => userRoles.includes(r))) {
+      return true;
+    }
+    const userId = ctx.user.id ?? ctx.user._id;
+    return {
+      granted: true,
+      filters: { [ownerField]: userId }
+    };
+  };
+}
+function allOf(...checks) {
+  return async (ctx) => {
+    let mergedFilters = {};
+    for (const check of checks) {
+      const result = await check(ctx);
+      const normalized = typeof result === "boolean" ? { granted: result } : result;
+      if (!normalized.granted) {
+        return normalized;
+      }
+      if (normalized.filters) {
+        mergedFilters = { ...mergedFilters, ...normalized.filters };
+      }
+    }
+    return {
+      granted: true,
+      filters: Object.keys(mergedFilters).length > 0 ? mergedFilters : void 0
+    };
+  };
+}
+function anyOf(...checks) {
+  return async (ctx) => {
+    const reasons = [];
+    for (const check of checks) {
+      const result = await check(ctx);
+      const normalized = typeof result === "boolean" ? { granted: result } : result;
+      if (normalized.granted) {
+        return normalized;
+      }
+      if (normalized.reason) {
+        reasons.push(normalized.reason);
+      }
+    }
+    return {
+      granted: false,
+      reason: reasons.join("; ")
+    };
+  };
+}
+function denyAll(reason = "Access denied") {
+  return () => ({ granted: false, reason });
+}
+function when(condition) {
+  return async (ctx) => {
+    const result = await condition(ctx);
+    return {
+      granted: result,
+      reason: result ? void 0 : "Condition not met"
+    };
+  };
+}
+
+export { allOf, allowPublic, anyOf, denyAll, requireAuth, requireOwnership, requireRoles, when };

package/dist/plugins/index.d.ts

@@ -0,0 +1,46 @@
+export { k as ArcCore, A as ArcCorePluginOptions, G as GracefulShutdownOptions, b as HealthCheck, H as HealthOptions, R as RequestIdOptions, T as TracingOptions, f as arcCorePlugin, j as arcCorePluginFn, d as createSpan, e as gracefulShutdownPlugin, g as gracefulShutdownPluginFn, a as healthPlugin, h as healthPluginFn, i as isTracingAvailable, _ as requestIdPlugin, r as requestIdPluginFn, t as traced, c as tracingPlugin } from '../arcCorePlugin-DTPWXcZN.js';
+import { FastifyInstance, FastifyRequest } from 'fastify';
+import '../index-DkAW8BXh.js';
+import 'mongoose';
+import '../types-B99TBmFV.js';
+
+/**
+ * Error Handler Plugin
+ *
+ * Global error handling for Arc applications.
+ * Catches all errors and returns a consistent JSON response.
+ *
+ * @example
+ * import { errorHandlerPlugin } from '@classytic/arc/plugins';
+ *
+ * await fastify.register(errorHandlerPlugin, {
+ *   includeStack: process.env.NODE_ENV !== 'production',
+ *   onError: (error, request) => {
+ *     // Log to external service (Sentry, etc.)
+ *     Sentry.captureException(error);
+ *   }
+ * });
+ */
+
+interface ErrorHandlerOptions {
+    /**
+     * Include stack trace in error responses (default: false in production)
+     */
+    includeStack?: boolean;
+    /**
+     * Custom error callback for logging to external services
+     */
+    onError?: (error: Error, request: FastifyRequest) => void | Promise<void>;
+    /**
+     * Map specific error types to custom responses
+     */
+    errorMap?: Record<string, {
+        statusCode: number;
+        code: string;
+        message?: string;
+    }>;
+}
+declare function errorHandlerPluginFn(fastify: FastifyInstance, options?: ErrorHandlerOptions): Promise<void>;
+declare const errorHandlerPlugin: typeof errorHandlerPluginFn;
+
+export { type ErrorHandlerOptions, errorHandlerPlugin, errorHandlerPlugin as errorHandlerPluginFn };