@classytic/arc 1.1.0 → 2.1.3

package/dist/permissions/index.d.mts

@@ -0,0 +1,278 @@
+import { a as applyFieldWritePermissions, i as applyFieldReadPermissions, n as FieldPermissionMap, o as fields, r as FieldPermissionType, s as resolveEffectiveRoles, t as FieldPermission } from "../fields-Bi_AVKSo.mjs";
+import { a as getUserRoles, i as UserBase, n as PermissionContext, o as normalizeRoles, r as PermissionResult, t as PermissionCheck } from "../types-RLkFVgaw.mjs";
+import { i as CacheStore, t as CacheLogger } from "../interface-DTbsvIWe.mjs";
+import { a as presets_d_exports, c as readOnly, i as ownerWithAdminBypass, n as authenticated, o as publicRead, r as fullPublic, s as publicReadAdminWrite, t as adminOnly } from "../presets-BTeYbw7h.mjs";
+
+//#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) | void>;
+}
+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[];
+}): 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 = any>(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 = any>(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 = any>(): 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 = any>(...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 = any>(): PermissionCheck<TDoc>;
+//#endregion
+export { ConnectEventsOptions, DynamicPermissionMatrix, DynamicPermissionMatrixConfig, type FieldPermission, type FieldPermissionMap, type FieldPermissionType, type PermissionCheck, type PermissionContext, PermissionEventBus, type PermissionResult, type UserBase, adminOnly, allOf, allowPublic, anyOf, applyFieldReadPermissions, applyFieldWritePermissions, authenticated, createDynamicPermissionMatrix, createOrgPermissions, denyAll, fields, fullPublic, getUserRoles, normalizeRoles, ownerWithAdminBypass, presets_d_exports as permissions, publicRead, publicReadAdminWrite, readOnly, requireAuth, requireOrgMembership, requireOrgRole, requireOwnership, requireRoles, requireTeamMembership, resolveEffectiveRoles, when };