@classytic/arc 2.6.2 → 2.7.1

package/dist/types-DPsC0taJ.d.mts

@@ -0,0 +1,178 @@
+import { r as RequestScope } from "./types-CNEbix8T.mjs";
+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 = Record<string, unknown>> {
+  /** 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 a permission check.
+ *
+ * Permission checks can do three things:
+ * 1. **Grant or deny** access (`granted`, `reason`)
+ * 2. **Attach row-level filters** (`filters`) — these merge into `_policyFilters`
+ *    and narrow subsequent queries (e.g. `{ userId: ctx.user.id }` for ownership)
+ * 3. **Install the request scope** (`scope`) — when a custom authenticator wants
+ *    to set tenant/identity context directly from the permission layer, without
+ *    relying on a separate auth plugin
+ *
+ * The `scope` field is the clean integration point for custom auth strategies
+ * (API keys, service accounts, gateway headers). When present, Arc writes it to
+ * `request.scope` which then flows through the normal tenant-filtering pipeline
+ * (QueryResolver + AccessControl). This is the idiomatic way to wire non-Better-Auth
+ * identity providers into Arc's multi-tenancy without touching the auth plugin layer.
+ *
+ * @example
+ * ```typescript
+ * // Custom API-key auth — grant access AND install a service scope in one step
+ * export function requireApiKey(): PermissionCheck {
+ *   return async ({ request }) => {
+ *     const apiKey = request.headers['x-api-key'] as string | undefined;
+ *     if (!apiKey) return { granted: false, reason: 'Missing API key' };
+ *
+ *     const client = await ClientModel.findOne({ apiKey });
+ *     if (!client) return { granted: false, reason: 'Invalid API key' };
+ *
+ *     return {
+ *       granted: true,
+ *       // Install service scope — Arc writes this to request.scope automatically,
+ *       // and tenantField filtering picks it up via metadata._scope
+ *       scope: {
+ *         kind: 'service',
+ *         clientId: String(client._id),
+ *         organizationId: String(client.companyId),
+ *         scopes: client.allowedScopes,
+ *       },
+ *       // Optional row-level narrowing (e.g. per-project API keys)
+ *       filters: client.projectId ? { projectId: client.projectId } : undefined,
+ *     };
+ *   };
+ * }
+ * ```
+ */
+interface PermissionResult {
+  /** Whether access is granted */
+  granted: boolean;
+  /** Reason for denial (for error messages) */
+  reason?: string;
+  /** Query filters to apply (for ownership / row-level security patterns) */
+  filters?: Record<string, unknown>;
+  /**
+   * Install this scope on `request.scope` when granted. Flows through to
+   * `metadata._scope` and is read by QueryResolver / AccessControl for
+   * tenant-field filtering. Use this to wire custom auth (API keys, service
+   * accounts, gateway headers) into Arc's multi-tenancy without a separate
+   * auth plugin.
+   */
+  scope?: RequestScope;
+}
+/**
+ * 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 = Record<string, unknown>> = ((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.
+ *
+ * Each helper from `permissions/index.ts` writes its own discriminating tag
+ * so downstream tooling (OpenAPI generator, MCP resource builder, route
+ * audit utilities) can read off the requirement without re-parsing the
+ * function body. All fields are optional — only the helpers that emit them
+ * set them.
+ */
+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;
+  /**
+   * Set by requireServiceScope() — the OAuth-style scope strings the
+   * caller's `service` identity must hold (any-match logic, parallels
+   * `_orgRoles`).
+   */
+  _serviceScopes?: readonly string[];
+  /**
+   * Set by requireScopeContext() — the app-defined scope dimensions the
+   * caller must satisfy. Map keys are dimension names (`branchId`,
+   * `projectId`, etc.); values are the required string OR `undefined`
+   * for "must be present, any value".
+   */
+  _scopeContext?: Record<string, string | undefined>;
+  /**
+   * Set by requireOrgInScope() — the target organization that must appear
+   * in the caller's org chain (current org or `ancestorOrgIds`). Either
+   * a static org id or a function extracting it from the request context
+   * (e.g. from route params).
+   */
+  _orgInScopeTarget?: string | ((ctx: PermissionContext) => string | undefined);
+}
+//#endregion
+export { getUserRoles as a, UserBase as i, PermissionContext as n, normalizeRoles as o, PermissionResult as r, PermissionCheck as t };

package/dist/utils/index.d.mts

@@ -1,6 +1,6 @@
-import { K as ParsedQuery, W as OpenApiSchemas, Z as QueryParserInterface, l as AnyRecord } from "../interface-CrN45qz1.mjs";
-import { a as NotFoundError, c as RateLimitError, d as ValidationError, i as ForbiddenError, l as ServiceUnavailableError, m as isArcError, n as ConflictError, o as OrgAccessDeniedError, p as createError, r as ErrorDetails, s as OrgRequiredError, t as ArcError, u as UnauthorizedError } from "../errors-CcVbl1-T.mjs";
-import { a as CircuitBreakerStats, c as createCircuitBreakerRegistry, i as CircuitBreakerRegistry, n as CircuitBreakerError, o as CircuitState, r as CircuitBreakerOptions, s as createCircuitBreaker, t as CircuitBreaker } from "../circuitBreaker-JP2GdJ4b.mjs";
+import { G as OpenApiSchemas, Q as QueryParserInterface, q as ParsedQuery, u as AnyRecord } from "../interface-Dwzqt4mn.mjs";
+import { a as NotFoundError, c as RateLimitError, d as ValidationError, i as ForbiddenError, l as ServiceUnavailableError, m as isArcError, n as ConflictError, o as OrgAccessDeniedError, p as createError, r as ErrorDetails, s as OrgRequiredError, t as ArcError, u as UnauthorizedError } from "../errors-CCSsMpXE.mjs";
+import { a as CircuitBreakerStats, c as createCircuitBreakerRegistry, i as CircuitBreakerRegistry, n as CircuitBreakerError, o as CircuitState, r as CircuitBreakerOptions, s as createCircuitBreaker, t as CircuitBreaker } from "../circuitBreaker-DwxrljLB.mjs";
 import { FastifyInstance } from "fastify";
 
 //#region src/utils/compensation.d.ts

package/dist/utils/index.mjs

@@ -1,7 +1,7 @@
 import { n as createQueryParser, t as ArcQueryParser } from "../queryParser-CgCtsjti.mjs";
-import { a as createCircuitBreaker, i as CircuitState, n as CircuitBreakerError, o as createCircuitBreakerRegistry, r as CircuitBreakerRegistry, t as CircuitBreaker } from "../circuitBreaker-BOBOpN2w.mjs";
-import { _ as defineCompensation, a as getListQueryParams, c as listResponse, d as paginateWrapper, f as paginationSchema, g as wrapResponse, h as successResponseSchema, i as getDefaultCrudSchemas, l as messageWrapper, m as responses, n as deleteResponse, o as itemResponse, p as queryParams, r as errorResponseSchema, s as itemWrapper, t as createStateMachine, u as mutationResponse, v as withCompensation } from "../utils-Dc0WhlIl.mjs";
-import { a as OrgAccessDeniedError, c as ServiceUnavailableError, f as createError, i as NotFoundError, l as UnauthorizedError, n as ConflictError, o as OrgRequiredError, p as isArcError, r as ForbiddenError, s as RateLimitError, t as ArcError, u as ValidationError } from "../errors-NoQKsbAT.mjs";
-import { a as toJsonSchema, i as isZodSchema, n as convertRouteSchema, r as isJsonSchema, t as convertOpenApiSchemas } from "../schemaConverter-DjzHpFam.mjs";
-import { t as hasEvents } from "../typeGuards-Cj5Rgvlg.mjs";
+import { a as createCircuitBreaker, i as CircuitState, n as CircuitBreakerError, o as createCircuitBreakerRegistry, r as CircuitBreakerRegistry, t as CircuitBreaker } from "../circuitBreaker-l18oRgL5.mjs";
+import { _ as defineCompensation, a as getListQueryParams, c as listResponse, d as paginateWrapper, f as paginationSchema, g as wrapResponse, h as successResponseSchema, i as getDefaultCrudSchemas, l as messageWrapper, m as responses, n as deleteResponse, o as itemResponse, p as queryParams, r as errorResponseSchema, s as itemWrapper, t as createStateMachine, u as mutationResponse, v as withCompensation } from "../utils-B-l6410F.mjs";
+import { a as OrgAccessDeniedError, c as ServiceUnavailableError, f as createError, i as NotFoundError, l as UnauthorizedError, n as ConflictError, o as OrgRequiredError, p as isArcError, r as ForbiddenError, s as RateLimitError, t as ArcError, u as ValidationError } from "../errors-Cg58SLNi.mjs";
+import { a as toJsonSchema, i as isZodSchema, n as convertRouteSchema, r as isJsonSchema, t as convertOpenApiSchemas } from "../schemaConverter-0TyONAwM.mjs";
+import { t as hasEvents } from "../typeGuards-CcFZXgU7.mjs";
 export { ArcError, ArcQueryParser, CircuitBreaker, CircuitBreakerError, CircuitBreakerRegistry, CircuitState, ConflictError, ForbiddenError, NotFoundError, OrgAccessDeniedError, OrgRequiredError, RateLimitError, ServiceUnavailableError, UnauthorizedError, ValidationError, convertOpenApiSchemas, convertRouteSchema, createCircuitBreaker, createCircuitBreakerRegistry, createError, createQueryParser, createStateMachine, defineCompensation, deleteResponse, errorResponseSchema, getDefaultCrudSchemas, getListQueryParams, hasEvents, isArcError, isJsonSchema, isZodSchema, itemResponse, itemWrapper, listResponse, messageWrapper, mutationResponse, paginateWrapper, paginationSchema, queryParams, responses, successResponseSchema, toJsonSchema, withCompensation, wrapResponse };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@classytic/arc",
-  "version": "2.6.2",
+  "version": "2.7.1",
   "description": "Resource-oriented backend framework for Fastify — clean, minimal, powerful, tree-shakable",
   "type": "module",
   "exports": {
@@ -168,6 +168,10 @@
       "types": "./dist/auth/redis-session.d.mts",
       "default": "./dist/auth/redis-session.mjs"
     },
+    "./auth/mongoose": {
+      "types": "./dist/auth/mongoose.d.mts",
+      "default": "./dist/auth/mongoose.mjs"
+    },
     "./plugins/response-cache": {
       "types": "./dist/plugins/response-cache.d.mts",
       "default": "./dist/plugins/response-cache.mjs"
@@ -220,33 +224,33 @@
     "node": ">=22"
   },
   "peerDependencies": {
-    "@classytic/mongokit": ">=3.5.0",
+    "@classytic/mongokit": ">=3.5.5",
     "@classytic/streamline": ">=2.0.0",
-    "@fastify/cors": "^11.0.0",
-    "@fastify/helmet": "^13.0.0",
-    "@fastify/jwt": "^10.0.0",
-    "@fastify/multipart": "^9.0.0",
-    "@fastify/rate-limit": "^10.0.0",
-    "@fastify/sensible": "^6.0.0",
-    "@fastify/type-provider-typebox": "^6.0.0",
-    "@fastify/under-pressure": "^9.0.0",
-    "@fastify/websocket": "^11.0.0",
+    "@fastify/cors": ">=11.0.0",
+    "@fastify/helmet": ">=13.0.0",
+    "@fastify/jwt": ">=10.0.0",
+    "@fastify/multipart": ">=9.0.0",
+    "@fastify/rate-limit": ">=10.0.0",
+    "@fastify/sensible": ">=6.0.0",
+    "@fastify/type-provider-typebox": ">=6.0.0",
+    "@fastify/under-pressure": ">=9.0.0",
+    "@fastify/websocket": ">=11.0.0",
     "@modelcontextprotocol/sdk": ">=1.28.0",
     "@opentelemetry/auto-instrumentations-node": ">=0.40.0",
     "@opentelemetry/exporter-trace-otlp-http": ">=0.50.0",
     "@opentelemetry/instrumentation-http": ">=0.50.0",
     "@opentelemetry/instrumentation-mongodb": ">=0.40.0",
     "@opentelemetry/sdk-node": ">=0.50.0",
-    "@sinclair/typebox": "^0.34.0",
-    "better-auth": ">=1.5.5",
-    "bullmq": "^5.0.0",
-    "fastify": "^5.7.4",
-    "fastify-raw-body": "^5.0.0",
-    "ioredis": "^5.0.0",
-    "mongodb": "^6.0.0 || ^7.0.0",
-    "mongoose": ">=9.0.0",
-    "pino-pretty": "^13.0.0",
-    "zod": "^4.0.0"
+    "@sinclair/typebox": ">=0.34.0",
+    "better-auth": ">=1.6.0",
+    "bullmq": ">=5.0.0",
+    "fastify": ">=5.0.0",
+    "fastify-raw-body": ">=5.0.0",
+    "ioredis": ">=5.0.0",
+    "mongodb": ">=6.0.0",
+    "mongoose": ">=9.4.1",
+    "pino-pretty": ">=13.0.0",
+    "zod": ">=4.0.0"
   },
   "peerDependenciesMeta": {
     "@classytic/mongokit": {
@@ -337,22 +341,30 @@
     "secure-json-parse": "^4.1.0"
   },
   "devDependencies": {
+    "@better-auth/mongo-adapter": "^1.6.0",
     "@biomejs/biome": "^2.4.10",
-    "@classytic/mongokit": "^3.5.2",
+    "@classytic/mongokit": "^3.5.5",
+    "@fastify/cors": "^11.2.0",
+    "@fastify/helmet": "^13.0.2",
     "@fastify/jwt": "^10.0.0",
     "@fastify/multipart": "^9.0.0",
+    "@fastify/rate-limit": "^10.3.0",
+    "@fastify/sensible": "^6.0.4",
     "@fastify/type-provider-typebox": "^6.0.0",
+    "@fastify/under-pressure": "^9.0.3",
     "@fastify/websocket": "^11.0.0",
     "@modelcontextprotocol/sdk": "^1.29.0",
     "@sinclair/typebox": "^0.34.0",
     "@types/node": "^22.10.0",
     "@types/qs": "^6.14.0",
     "@vitest/coverage-v8": "^3.2.4",
+    "better-auth": "^1.6.0",
     "fastify-raw-body": "^5.0.0",
     "jsonwebtoken": "^9.0.0",
     "knip": "^6.3.0",
     "mongodb": "^7.1.0",
     "mongodb-memory-server": "^11.0.1",
+    "mongoose": "^9.4.1",
     "tsdown": "^0.21.7",
     "typescript": "^6.0.2",
     "vitest": "^3.0.0",