@classytic/arc 2.6.3 → 2.7.3

package/dist/index-NGZksqM5.d.mts

@@ -1,398 +0,0 @@
-import { n as PermissionContext, t as PermissionCheck } from "./types-BNUccdcf.mjs";
-import { i as CacheStore, t as CacheLogger } from "./interface-D_BWALyZ.mjs";
-
-//#region src/permissions/roleHierarchy.d.ts
-/**
- * Role Hierarchy — Composable RBAC Inheritance
- *
- * Expands roles based on an inheritance map. Apply at scope-building time
- * so that requireRoles() works with the already-expanded list.
- *
- * @example
- * ```typescript
- * import { createRoleHierarchy } from '@classytic/arc/permissions';
- *
- * const hierarchy = createRoleHierarchy({
- *   superadmin: ['admin'],
- *   admin: ['branch_manager'],
- *   branch_manager: ['member'],
- * });
- *
- * // When building scope:
- * const expandedRoles = hierarchy.expand(user.roles);
- * // ['superadmin'] → ['superadmin', 'admin', 'branch_manager', 'member']
- *
- * // Check inclusion:
- * hierarchy.includes(['admin'], 'branch_manager'); // true (admin inherits branch_manager)
- * hierarchy.includes(['member'], 'admin');          // false (child doesn't inherit parent)
- * ```
- */
-interface RoleHierarchy {
-  /** Expand roles to include all inherited (child) roles. Deduplicated. */
-  expand(roles: readonly string[]): string[];
-  /** Check if any of the user's roles (expanded) include the required role. */
-  includes(userRoles: readonly string[], requiredRole: string): boolean;
-}
-/**
- * Create a role hierarchy from a parent → children map.
- *
- * Each key is a parent role, each value is the array of roles it inherits.
- * Inheritance is transitive: if A → B and B → C, then A expands to [A, B, C].
- * Circular references are handled safely (visited set).
- */
-declare function createRoleHierarchy(map: Record<string, readonly string[]>): RoleHierarchy;
-declare namespace presets_d_exports {
-  export { adminOnly, authenticated, fullPublic, ownerWithAdminBypass, publicRead, publicReadAdminWrite, readOnly };
-}
-/**
- * ResourcePermissions shape — matches the type in types/index.ts
- */
-interface ResourcePermissions<TDoc = any> {
-  list?: PermissionCheck<TDoc>;
-  get?: PermissionCheck<TDoc>;
-  create?: PermissionCheck<TDoc>;
-  update?: PermissionCheck<TDoc>;
-  delete?: PermissionCheck<TDoc>;
-}
-type PermissionOverrides<TDoc = any> = Partial<ResourcePermissions<TDoc>>;
-/**
- * Public read, authenticated write.
- * list + get = allowPublic(), create + update + delete = requireAuth()
- */
-declare function publicRead<TDoc = any>(overrides?: PermissionOverrides<TDoc>): ResourcePermissions<TDoc>;
-/**
- * Public read, admin write.
- * list + get = allowPublic(), create + update + delete = requireRoles(['admin'])
- */
-declare function publicReadAdminWrite<TDoc = any>(roles?: readonly string[], overrides?: PermissionOverrides<TDoc>): ResourcePermissions<TDoc>;
-/**
- * All operations require authentication.
- */
-declare function authenticated<TDoc = any>(overrides?: PermissionOverrides<TDoc>): ResourcePermissions<TDoc>;
-/**
- * All operations require specific roles.
- * @param roles - Required roles (user needs at least one). Default: ['admin']
- */
-declare function adminOnly<TDoc = any>(roles?: readonly string[], overrides?: PermissionOverrides<TDoc>): ResourcePermissions<TDoc>;
-/**
- * Owner-scoped with admin bypass.
- * list = auth (scoped to owner), get = auth, create = auth,
- * update + delete = ownership check with admin bypass.
- *
- * @param ownerField - Field containing owner ID (default: 'userId')
- * @param bypassRoles - Roles that bypass ownership check (default: ['admin'])
- */
-declare function ownerWithAdminBypass<TDoc = any>(ownerField?: Extract<keyof TDoc, string> | string, bypassRoles?: readonly string[], overrides?: PermissionOverrides<TDoc>): ResourcePermissions<TDoc>;
-/**
- * Full public access — no auth required for any operation.
- * Use sparingly (dev/testing, truly public APIs).
- */
-declare function fullPublic<TDoc = any>(overrides?: PermissionOverrides<TDoc>): ResourcePermissions<TDoc>;
-/**
- * Read-only: list + get authenticated, write operations denied.
- * Useful for computed/derived resources.
- */
-declare function readOnly<TDoc = any>(overrides?: PermissionOverrides<TDoc>): ResourcePermissions<TDoc>;
-//#endregion
-//#region src/permissions/index.d.ts
-interface DynamicPermissionMatrixConfig {
-  /**
-   * Resolve role → resource → actions map dynamically (DB/API/config service).
-   * Called at permission-check time (or cache miss if cache enabled).
-   */
-  resolveRolePermissions: (ctx: PermissionContext) => Record<string, Record<string, readonly string[]>> | Promise<Record<string, Record<string, readonly string[]>>>;
-  /**
-   * Optional cache store adapter.
-   * Use MemoryCacheStore for single-instance apps or RedisCacheStore for distributed setups.
-   */
-  cacheStore?: CacheStore<Record<string, Record<string, readonly string[]>>>;
-  /** Optional logger for cache/runtime failures (default: console) */
-  logger?: CacheLogger;
-  /**
-   * Legacy convenience in-memory cache config.
-   * If `cacheStore` is not provided and ttlMs > 0, Arc creates an internal MemoryCacheStore.
-   */
-  cache?: {
-    /** Cache TTL in milliseconds */ttlMs: number; /** Optional custom cache key builder */
-    key?: (ctx: PermissionContext) => string | null | undefined; /** Hard entry cap for internal memory store (default: 1000) */
-    maxEntries?: number;
-  };
-}
-/** Minimal publish/subscribe interface for cross-node cache invalidation. */
-interface PermissionEventBus {
-  publish: <T>(type: string, payload: T) => Promise<void>;
-  subscribe: (pattern: string, handler: (event: {
-    payload: unknown;
-  }) => void | Promise<void>) => Promise<(() => void) | undefined>;
-}
-interface ConnectEventsOptions {
-  /** Called on remote invalidation for app-specific cleanup (e.g., resolver cache) */
-  onRemoteInvalidation?: (orgId: string) => void | Promise<void>;
-  /** Custom event type (default: 'arc.permissions.invalidated') */
-  eventType?: string;
-}
-interface DynamicPermissionMatrix {
-  can: (permissions: Record<string, readonly string[]>) => PermissionCheck;
-  canAction: (resource: string, action: string) => PermissionCheck;
-  requireRole: (...roles: string[]) => PermissionCheck;
-  requireMembership: () => PermissionCheck;
-  requireTeamMembership: () => PermissionCheck;
-  /** Invalidate cached permissions for a specific organization */
-  invalidateByOrg: (orgId: string) => Promise<void>;
-  clearCache: () => Promise<void>;
-  /**
-   * Connect to an event system for cross-node cache invalidation.
-   *
-   * Late-binding: call after the event plugin is registered (e.g., in onReady hook).
-   * Once connected, `invalidateByOrg()` auto-publishes an event, and incoming
-   * events from other nodes trigger local cache invalidation.
-   * Echo is suppressed via per-process nodeId matching.
-   */
-  connectEvents(events: PermissionEventBus, options?: ConnectEventsOptions): Promise<void>;
-  /** Disconnect from the event system. Safe to call even if never connected. */
-  disconnectEvents(): Promise<void>;
-  /** Whether events are currently connected. */
-  readonly eventsConnected: boolean;
-}
-/**
- * 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[];
-  /**
-   * Also check org membership roles (`scope.orgRoles`) when in org context.
-   * Default: `false` — only checks platform roles (`user.role`).
-   *
-   * Set to `true` when using Better Auth organization plugin where roles like
-   * 'admin' are assigned at the org level, not the user level.
-   *
-   * For org-only role checks, prefer `requireOrgRole('admin')` instead.
-   */
-  includeOrgRoles?: boolean;
-}): PermissionCheck;
-/**
- * Unified role check — checks both platform roles AND org roles.
- *
- * This is the recommended helper for Better Auth organization plugin users.
- * It checks `user.role` (platform) first, then `scope.orgRoles` (org membership).
- * Elevated scope always passes.
- *
- * For platform-only checks: use `requireRoles(['admin'])`
- * For org-only checks: use `requireOrgRole('admin')`
- *
- * @example
- * ```typescript
- * permissions: {
- *   create: roles('admin', 'editor'),  // passes if user has role at either level
- *   delete: roles('admin'),
- * }
- * ```
- */
-declare function roles(...args: string[] | [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<TDoc = Record<string, unknown>>(ownerField?: Extract<keyof TDoc, string> | string, options?: {
-  bypassRoles?: readonly string[];
-}): PermissionCheck<TDoc>;
-/**
- * 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<TDoc = Record<string, unknown>>(condition: (ctx: PermissionContext<TDoc>) => boolean | Promise<boolean>): PermissionCheck<TDoc>;
-/**
- * Require membership in the active organization.
- * User must be authenticated AND have an active org (member or elevated scope).
- *
- * Reads `request.scope` set by auth adapters.
- *
- * @example
- * ```typescript
- * permissions: {
- *   list: requireOrgMembership(),
- *   get: requireOrgMembership(),
- * }
- * ```
- */
-declare function requireOrgMembership<TDoc = Record<string, unknown>>(): PermissionCheck<TDoc>;
-/**
- * Require specific org-level roles.
- * Reads `request.scope.orgRoles` (set by auth adapters).
- * Elevated scope always passes (platform admin bypass).
- *
- * @param roles - Required org roles (user needs at least one)
- *
- * @example
- * ```typescript
- * permissions: {
- *   create: requireOrgRole('admin', 'owner'),
- *   delete: requireOrgRole('owner'),
- * }
- * ```
- */
-declare function requireOrgRole<TDoc = Record<string, unknown>>(...args: string[] | [readonly string[]]): PermissionCheck<TDoc>;
-/**
- * Create a scoped permission system for resource-action patterns.
- * Maps org roles to fine-grained permissions without external API calls.
- *
- * @example
- * ```typescript
- * const perms = createOrgPermissions({
- *   statements: {
- *     product: ['create', 'update', 'delete'],
- *     order: ['create', 'approve'],
- *   },
- *   roles: {
- *     owner: { product: ['create', 'update', 'delete'], order: ['create', 'approve'] },
- *     admin: { product: ['create', 'update'], order: ['create'] },
- *     member: { product: [], order: [] },
- *   },
- * });
- *
- * defineResource({
- *   permissions: {
- *     create: perms.can({ product: ['create'] }),
- *     delete: perms.can({ product: ['delete'] }),
- *   }
- * });
- * ```
- */
-declare function createOrgPermissions(config: {
-  statements: Record<string, readonly string[]>;
-  roles: Record<string, Record<string, readonly string[]>>;
-}): {
-  can: (permissions: Record<string, string[]>) => PermissionCheck;
-  requireRole: (...roles: string[]) => PermissionCheck;
-  requireMembership: () => PermissionCheck;
-  requireTeamMembership: () => PermissionCheck;
-};
-/**
- * Create a dynamic role-based permission matrix.
- *
- * Use this when role/action mappings are managed outside code
- * (e.g., admin UI matrix, DB-stored ACLs, remote policy service).
- *
- * Supports:
- * - org role union (any assigned org role can grant)
- * - global bypass roles
- * - wildcard resource/action (`*`)
- * - optional in-memory cache
- */
-declare function createDynamicPermissionMatrix(config: DynamicPermissionMatrixConfig): DynamicPermissionMatrix;
-/**
- * Require membership in the active team.
- * User must be authenticated, a member of the active org, AND have an active team.
- *
- * Better Auth teams are flat member groups (no team-level roles).
- * Reads `request.scope.teamId` set by the Better Auth adapter.
- *
- * @example
- * ```typescript
- * permissions: {
- *   list: requireTeamMembership(),
- *   create: requireTeamMembership(),
- * }
- * ```
- */
-declare function requireTeamMembership<TDoc = Record<string, unknown>>(): PermissionCheck<TDoc>;
-//#endregion
-export { presets_d_exports as C, RoleHierarchy as D, readOnly as E, createRoleHierarchy as O, ownerWithAdminBypass as S, publicReadAdminWrite as T, roles as _, allOf as a, authenticated as b, createDynamicPermissionMatrix as c, requireAuth as d, requireOrgMembership as f, requireTeamMembership as g, requireRoles as h, PermissionEventBus as i, createOrgPermissions as l, requireOwnership as m, DynamicPermissionMatrix as n, allowPublic as o, requireOrgRole as p, DynamicPermissionMatrixConfig as r, anyOf as s, ConnectEventsOptions as t, denyAll as u, when as v, publicRead as w, fullPublic as x, adminOnly as y };

package/dist/types-BNUccdcf.d.mts

@@ -1,101 +0,0 @@
-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 permission check
- */
-interface PermissionResult {
-  /** Whether access is granted */
-  granted: boolean;
-  /** Reason for denial (for error messages) */
-  reason?: string;
-  /** Query filters to apply (for ownership patterns) */
-  filters?: Record<string, unknown>;
-}
-/**
- * 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.
- */
-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;
-}
-//#endregion
-export { getUserRoles as a, UserBase as i, PermissionContext as n, normalizeRoles as o, PermissionResult as r, PermissionCheck as t };

package/dist/types-BhtYdxZU.mjs

@@ -1,91 +0,0 @@
-//#region src/scope/types.ts
-/** Check if scope is `member` kind */
-function isMember(scope) {
-	return scope.kind === "member";
-}
-/** Check if scope is `elevated` kind */
-function isElevated(scope) {
-	return scope.kind === "elevated";
-}
-/** Check if scope has org access (member OR elevated) */
-function hasOrgAccess(scope) {
-	return scope.kind === "member" || scope.kind === "elevated";
-}
-/** Check if request is authenticated (any kind except public) */
-function isAuthenticated(scope) {
-	return scope.kind !== "public";
-}
-/** Get organizationId from scope (if present) */
-function getOrgId(scope) {
-	if (scope.kind === "member") return scope.organizationId;
-	if (scope.kind === "elevated") return scope.organizationId;
-}
-/** Get org roles from scope (empty array if not a member) */
-function getOrgRoles(scope) {
-	if (scope.kind === "member") return scope.orgRoles;
-	return [];
-}
-/** Get team ID from scope (only available on member kind) */
-function getTeamId(scope) {
-	if (scope.kind === "member") return scope.teamId;
-}
-/**
-* Get userId from scope (available on authenticated, member, elevated).
-*
-* @example
-* ```typescript
-* import { getUserId } from '@classytic/arc/scope';
-* const userId = getUserId(request.scope);
-* ```
-*/
-function getUserId(scope) {
-	if (scope.kind === "public") return void 0;
-	return scope.userId;
-}
-/**
-* Get global user roles from scope (available on authenticated and member).
-* These are user-level roles (e.g. superadmin, finance-admin) distinct from
-* org-level roles (scope.orgRoles).
-*
-* @example
-* ```typescript
-* import { getUserRoles } from '@classytic/arc/scope';
-* const globalRoles = getUserRoles(request.scope);
-* ```
-*/
-function getUserRoles(scope) {
-	if (scope.kind === "authenticated") return scope.userRoles ?? [];
-	if (scope.kind === "member") return scope.userRoles;
-	return [];
-}
-/**
-* Org context — canonical extraction from a Fastify request.
-*
-* Works regardless of auth type (JWT, Better Auth, custom) by reading
-* `request.scope` and `request.user`. Eliminates the need for each resource
-* to re-invent org extraction from headers/user/scope.
-*
-* @example
-* ```typescript
-* import { getOrgContext } from '@classytic/arc/scope';
-*
-* handler: async (request, reply) => {
-*   const { userId, organizationId, roles, orgRoles } = getOrgContext(request);
-* }
-* ```
-*/
-function getOrgContext(request) {
-	const scope = request.scope ?? { kind: "public" };
-	return {
-		userId: getUserId(scope) ?? request.user?.id ?? request.user?._id,
-		organizationId: getOrgId(scope) ?? request.user?.organizationId ?? request.headers?.["x-organization-id"],
-		roles: getUserRoles(scope),
-		orgRoles: getOrgRoles(scope)
-	};
-}
-/** Default public scope — used as initial decoration value */
-const PUBLIC_SCOPE = Object.freeze({ kind: "public" });
-/** Default authenticated scope — used when user is logged in but no org */
-const AUTHENTICATED_SCOPE = Object.freeze({ kind: "authenticated" });
-//#endregion
-export { getOrgRoles as a, getUserRoles as c, isElevated as d, isMember as f, getOrgId as i, hasOrgAccess as l, PUBLIC_SCOPE as n, getTeamId as o, getOrgContext as r, getUserId as s, AUTHENTICATED_SCOPE as t, isAuthenticated as u };