@svadmin/core 0.4.1 → 0.5.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@svadmin/core",
-  "version": "0.4.1",
+  "version": "0.5.0",
   "description": "Core SDK — hooks, types, context, i18n, permissions, router",
   "type": "module",
   "sideEffects": false,
@@ -51,7 +51,8 @@
   "author": "zuohuadong",
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/zuohuadong/svadmin.git"
+    "url": "https://github.com/zuohuadong/svadmin.git",
+    "directory": "packages/core"
   },
   "homepage": "https://github.com/zuohuadong/svadmin#readme",
   "bugs": {

package/src/adapters/casbin.ts

@@ -0,0 +1,61 @@
+/**
+ * Casbin adapter for svadmin AccessControlProvider.
+ *
+ * Converts a Casbin `Enforcer` instance into an `AccessControlProvider`.
+ *
+ * @example
+ * ```ts
+ * import { newEnforcer } from 'casbin';
+ * import { createCasbinAccessControl } from '@svadmin/core/adapters/casbin';
+ * import { setAccessControlProvider } from '@svadmin/core';
+ *
+ * const enforcer = await newEnforcer('model.conf', 'policy.csv');
+ * const currentUser = 'alice';
+ *
+ * setAccessControlProvider(
+ *   createCasbinAccessControl(enforcer, { getUser: () => currentUser })
+ * );
+ * ```
+ */
+
+import type { AccessControlProvider, CanParams, CanResult } from '../permissions';
+
+/** Casbin Enforcer interface (minimal, to avoid hard dependency on casbin) */
+interface CasbinEnforcer {
+  enforce: (...args: string[]) => Promise<boolean>;
+}
+
+export interface CasbinAdapterOptions {
+  /** Function to get the current user/subject for enforcement. */
+  getUser: () => string;
+  /** Provider-level options */
+  providerOptions?: AccessControlProvider['options'];
+}
+
+/**
+ * Create an AccessControlProvider from a Casbin Enforcer.
+ *
+ * Uses the standard (sub, obj, act) enforcement model:
+ * - sub = current user (from `getUser()`)
+ * - obj = resource name
+ * - act = action
+ *
+ * @param enforcer - A Casbin Enforcer instance
+ * @param options - Configuration with user getter
+ */
+export function createCasbinAccessControl(
+  enforcer: CasbinEnforcer,
+  options: CasbinAdapterOptions,
+): AccessControlProvider {
+  return {
+    can: async ({ resource, action }: CanParams): Promise<CanResult> => {
+      const user = options.getUser();
+      const allowed = await enforcer.enforce(user, resource, action);
+      return {
+        can: allowed,
+        reason: allowed ? undefined : `User "${user}" cannot "${action}" on "${resource}"`,
+      };
+    },
+    options: options.providerOptions,
+  };
+}

package/src/adapters/casl.ts

@@ -0,0 +1,51 @@
+/**
+ * CASL adapter for svadmin AccessControlProvider.
+ *
+ * Converts a CASL `Ability` instance into an `AccessControlProvider`.
+ *
+ * @example
+ * ```ts
+ * import { AbilityBuilder, createMongoAbility } from '@casl/ability';
+ * import { createCaslAccessControl } from '@svadmin/core/adapters/casl';
+ * import { setAccessControlProvider } from '@svadmin/core';
+ *
+ * const { can, build } = new AbilityBuilder(createMongoAbility);
+ * can('read', 'Post');
+ * can('create', 'Post');
+ * can('manage', 'User');
+ * const ability = build();
+ *
+ * setAccessControlProvider(createCaslAccessControl(ability));
+ * ```
+ */
+
+import type { AccessControlProvider, CanParams, CanResult } from '../permissions';
+
+/** CASL Ability interface (minimal, to avoid hard dependency on @casl/ability) */
+interface CaslAbility {
+  can: (action: string, subject: string, field?: string) => boolean;
+  cannot: (action: string, subject: string, field?: string) => boolean;
+}
+
+/**
+ * Create an AccessControlProvider from a CASL Ability.
+ *
+ * @param ability - A CASL Ability instance
+ * @param options - Optional configuration
+ */
+export function createCaslAccessControl(
+  ability: CaslAbility,
+  options?: AccessControlProvider['options'],
+): AccessControlProvider {
+  return {
+    can: async ({ resource, action, params }: CanParams): Promise<CanResult> => {
+      const field = params?.field as string | undefined;
+      const allowed = ability.can(action, resource, field);
+      return {
+        can: allowed,
+        reason: allowed ? undefined : `Cannot "${action}" on "${resource}"${field ? ` (field: ${field})` : ''}`,
+      };
+    },
+    options,
+  };
+}

package/src/index.ts

@@ -28,7 +28,7 @@ export {
 } from './hooks.svelte';
 export { matchRoute, navigate, currentPath, setActiveRouterProvider } from './router';
 export { readURLState, writeURLState } from './url-sync';
-export { setAccessControl, canAccess, canAccessAsync } from './permissions';
+export { setAccessControl, setAccessControlProvider, getAccessControlProvider, getAccessControlOptions, canAccess, canAccessAsync } from './permissions';
 export { useLive, useSubscription, usePublish } from './live';
 export { toast } from './toast.svelte';
 export { notify, closeNotification, setNotificationProvider, getNotificationProvider } from './notification.svelte';
@@ -64,9 +64,13 @@ export type {
 } from './types';
 export type { InvalidateScope } from './options';
 export type { LiveProvider, LiveEvent, LiveMode } from './live';
-export type { Action, AccessControlResult, AccessControlFn } from './permissions';
+export type { Action, CanParams, CanResult, AccessControlProvider, AccessControlResult, AccessControlFn } from './permissions';
 export type { AuditEntry, AuditHandler } from './audit';
 export { useCan } from './useCan';
+export type { UseCanOptions, UseCanResult } from './useCan';
+export { createCaslAccessControl } from './adapters/casl';
+export { createCasbinAccessControl } from './adapters/casbin';
+export type { CasbinAdapterOptions } from './adapters/casbin';
 export { useExport, useImport } from './data-transfer';
 export type { UseExportOptions, UseImportOptions } from './data-transfer';
 export {

package/src/permissions.test.ts

@@ -1,7 +1,7 @@
 // Unit tests for permissions module
 import { describe, test, expect, beforeEach } from 'bun:test';
-import { setAccessControl, canAccess, canAccessAsync } from './permissions';
-import type { Action } from './permissions';
+import { setAccessControl, setAccessControlProvider, getAccessControlProvider, getAccessControlOptions, canAccess, canAccessAsync } from './permissions';
+import type { Action, AccessControlProvider } from './permissions';
 
 describe('permissions', () => {
   beforeEach(() => {
@@ -53,3 +53,122 @@ describe('permissions', () => {
     expect(canAccess('posts', 'delete').can).toBe(true);
   });
 });
+
+describe('AccessControlProvider', () => {
+  beforeEach(() => {
+    setAccessControlProvider({
+      can: async () => ({ can: true }),
+    });
+  });
+
+  test('setAccessControlProvider registers a provider', () => {
+    const provider = getAccessControlProvider();
+    expect(provider).not.toBeNull();
+  });
+
+  test('provider can() is called via canAccessAsync', async () => {
+    setAccessControlProvider({
+      can: async ({ resource, action }) => {
+        if (resource === 'posts' && action === 'delete') {
+          return { can: false, reason: 'Cannot delete posts' };
+        }
+        return { can: true };
+      },
+    });
+    const denied = await canAccessAsync('posts', 'delete');
+    expect(denied.can).toBe(false);
+    expect(denied.reason).toBe('Cannot delete posts');
+
+    const allowed = await canAccessAsync('posts', 'list');
+    expect(allowed.can).toBe(true);
+  });
+
+  test('params.id is passed through', async () => {
+    setAccessControlProvider({
+      can: async ({ params }) => {
+        if (params?.id === 42) return { can: false, reason: 'Record locked' };
+        return { can: true };
+      },
+    });
+    const result = await canAccessAsync('posts', 'edit', { id: 42 });
+    expect(result.can).toBe(false);
+    expect(result.reason).toBe('Record locked');
+  });
+
+  test('extended action types work', async () => {
+    setAccessControlProvider({
+      can: async ({ action }) => {
+        if (action === 'show') return { can: false, reason: 'No show' };
+        if (action === 'field') return { can: false, reason: 'No field' };
+        return { can: true };
+      },
+    });
+    expect((await canAccessAsync('posts', 'show')).can).toBe(false);
+    expect((await canAccessAsync('posts', 'field')).can).toBe(false);
+    expect((await canAccessAsync('posts', 'list')).can).toBe(true);
+  });
+
+  test('getAccessControlOptions returns provider options', () => {
+    setAccessControlProvider({
+      can: async () => ({ can: true }),
+      options: {
+        buttons: { enableAccessControl: true, hideIfUnauthorized: true },
+      },
+    });
+    const options = getAccessControlOptions();
+    expect(options.buttons?.enableAccessControl).toBe(true);
+    expect(options.buttons?.hideIfUnauthorized).toBe(true);
+  });
+
+  test('getAccessControlOptions returns {} when no options', () => {
+    setAccessControlProvider({
+      can: async () => ({ can: true }),
+    });
+    expect(getAccessControlOptions()).toEqual({});
+  });
+});
+
+describe('CASL adapter', () => {
+  test('createCaslAccessControl works', async () => {
+    // Import dynamically to test the adapter
+    const { createCaslAccessControl } = await import('./adapters/casl');
+
+    // Mock CASL Ability
+    const ability = {
+      can: (action: string, subject: string) => !(action === 'delete' && subject === 'users'),
+      cannot: (action: string, subject: string) => action === 'delete' && subject === 'users',
+    };
+
+    const provider = createCaslAccessControl(ability);
+
+    const allowed = await provider.can({ resource: 'posts', action: 'edit' });
+    expect(allowed.can).toBe(true);
+
+    const denied = await provider.can({ resource: 'users', action: 'delete' });
+    expect(denied.can).toBe(false);
+    expect(denied.reason).toContain('Cannot "delete" on "users"');
+  });
+});
+
+describe('Casbin adapter', () => {
+  test('createCasbinAccessControl works', async () => {
+    const { createCasbinAccessControl } = await import('./adapters/casbin');
+
+    // Mock Casbin Enforcer
+    const enforcer = {
+      enforce: async (sub: string, obj: string, act: string) =>
+        !(sub === 'alice' && obj === 'users' && act === 'delete'),
+    };
+
+    const provider = createCasbinAccessControl(enforcer, {
+      getUser: () => 'alice',
+    });
+
+    const allowed = await provider.can({ resource: 'posts', action: 'edit' });
+    expect(allowed.can).toBe(true);
+
+    const denied = await provider.can({ resource: 'users', action: 'delete' });
+    expect(denied.can).toBe(false);
+    expect(denied.reason).toContain('alice');
+  });
+});

package/src/permissions.ts

@@ -1,42 +1,129 @@
 // Permission / Access Control
 
+// ─── Types ────────────────────────────────────────────────────
 
-export type Action = 'list' | 'create' | 'edit' | 'delete' | 'export';
+/** Actions that can be checked for access control. Extensible via string literal union. */
+export type Action = 'list' | 'show' | 'create' | 'edit' | 'delete' | 'export' | 'field' | (string & {});
 
-export interface AccessControlResult {
+export interface CanParams {
+  resource: string;
+  action: Action;
+  params?: { id?: string | number; [key: string]: unknown };
+}
+
+export interface CanResult {
   can: boolean;
   reason?: string;
 }
 
+/** @deprecated Use `CanResult` instead */
+export type AccessControlResult = CanResult;
+
+/**
+ * Formal Access Control Provider interface.
+ * Implement this to define your authorization logic.
+ *
+ * @example
+ * ```ts
+ * const accessControlProvider: AccessControlProvider = {
+ *   can: async ({ resource, action, params }) => {
+ *     if (resource === 'users' && action === 'delete') {
+ *       return { can: false, reason: 'Cannot delete users' };
+ *     }
+ *     return { can: true };
+ *   },
+ *   options: {
+ *     buttons: { enableAccessControl: true, hideIfUnauthorized: false },
+ *   },
+ * };
+ * ```
+ */
+export interface AccessControlProvider {
+  can: (params: CanParams) => Promise<CanResult>;
+  options?: {
+    buttons?: {
+      /** Enable access control checks on CRUD buttons globally. Default: false */
+      enableAccessControl?: boolean;
+      /** Hide buttons when unauthorized instead of disabling. Default: false */
+      hideIfUnauthorized?: boolean;
+    };
+  };
+}
+
+/** @deprecated Use `AccessControlProvider['can']` instead */
 export type AccessControlFn = (
   resource: string,
   action: Action,
   params?: Record<string, unknown>,
-) => AccessControlResult | Promise<AccessControlResult>;
+) => CanResult | Promise<CanResult>;
+
+// ─── State ────────────────────────────────────────────────────
 
-let accessControlFn: AccessControlFn | null = null;
+let provider: AccessControlProvider | null = null;
+let legacyFn: AccessControlFn | null = null;
 
+// ─── API ──────────────────────────────────────────────────────
+
+/**
+ * Register an AccessControlProvider.
+ */
+export function setAccessControlProvider(p: AccessControlProvider): void {
+  provider = p;
+  legacyFn = null;
+}
+
+/**
+ * @deprecated Use `setAccessControlProvider()` with full `AccessControlProvider` interface.
+ * Legacy API preserved for backward compatibility.
+ */
 export function setAccessControl(fn: AccessControlFn): void {
-  accessControlFn = fn;
+  legacyFn = fn;
+  provider = {
+    can: async ({ resource, action, params }) => {
+      const result = fn(resource, action, params);
+      return result instanceof Promise ? result : Promise.resolve(result);
+    },
+  };
 }
 
-export function canAccess(resource: string, action: Action, params?: Record<string, unknown>): AccessControlResult {
-  if (!accessControlFn) return { can: true };
-  const result = accessControlFn(resource, action, params);
-  if (result instanceof Promise) {
-    console.warn('[permissions] canAccess called synchronously but accessControlFn returned a Promise. Defaulting to { can: true }. Use canAccessAsync() instead.');
-    return { can: true };
-  }
-  return result;
+/** Get the current AccessControlProvider (or null) */
+export function getAccessControlProvider(): AccessControlProvider | null {
+  return provider;
 }
 
-export async function canAccessAsync(resource: string, action: Action, params?: Record<string, unknown>): Promise<AccessControlResult> {
-  if (!accessControlFn) return { can: true };
-  return accessControlFn(resource, action, params);
+/** Get global button options from the AccessControlProvider */
+export function getAccessControlOptions() {
+  return provider?.options ?? {};
 }
 
-// Example usage:
-// setAccessControl((resource, action) => {
-//   if (resource === 'users' && action === 'delete') return { can: false, reason: '无权删除用户' };
-//   return { can: true };
-// });
+/**
+ * Synchronous access check. Returns `{ can: true }` if no provider/fn is set.
+ * When a legacy sync fn is registered via `setAccessControl()`, this calls it synchronously.
+ * When only a provider is registered, this warns if provider.can() returns a Promise.
+ */
+export function canAccess(resource: string, action: Action, params?: Record<string, unknown>): CanResult {
+  // Fast path: use legacy sync fn if available
+  if (legacyFn) {
+    const result = legacyFn(resource, action, params);
+    if (result instanceof Promise) {
+      console.warn('[permissions] canAccess called synchronously but accessControlFn returned a Promise. Defaulting to { can: true }. Use canAccessAsync() instead.');
+      return { can: true };
+    }
+    return result;
+  }
+  if (!provider) return { can: true };
+  // Provider path (always async) — warn
+  console.warn('[permissions] canAccess called synchronously but provider.can() returned a Promise. Defaulting to { can: true }. Use canAccessAsync() instead.');
+  return { can: true };
+}
+
+/**
+ * Async access check. Preferred over `canAccess()`.
+ */
+export async function canAccessAsync(resource: string, action: Action, params?: Record<string, unknown>): Promise<CanResult> {
+  if (legacyFn) {
+    return legacyFn(resource, action, params);
+  }
+  if (!provider) return { can: true };
+  return provider.can({ resource, action, params });
+}

package/src/useCan.ts

@@ -1,37 +1,54 @@
-// useCan — reactive permission check hook
+// useCan — reactive permission check hook with TanStack Query integration
 
+import { createQuery } from '@tanstack/svelte-query';
 import { canAccessAsync } from './permissions';
-import type { Action, AccessControlResult } from './permissions';
+import type { Action, CanResult } from './permissions';
 
-interface UseCanResult {
-  allowed: boolean;
-  reason?: string;
-  isLoading: boolean;
+export interface UseCanOptions {
+  resource: string;
+  action: Action;
+  params?: Record<string, unknown>;
+  queryOptions?: {
+    enabled?: boolean;
+    staleTime?: number;
+  };
+}
+
+export interface UseCanResult {
+  readonly allowed: boolean;
+  readonly reason: string | undefined;
+  readonly isLoading: boolean;
 }
 
 /**
- * Reactive permission check. Calls canAccessAsync() and returns reactive state.
- * Usage: const can = useCan('posts', 'delete');
- *        if (can.allowed) { ... }
+ * Reactive permission check backed by TanStack Query for caching and deduplication.
+ *
+ * @example
+ * ```ts
+ * // Simple usage (backward compatible)
+ * const can = useCan('posts', 'delete');
+ * if (can.allowed) { ... }
+ *
+ * // With options object
+ * const can = useCan({ resource: 'posts', action: 'delete', params: { id: 1 } });
+ * ```
  */
-export function useCan(resource: string, action: Action, params?: Record<string, unknown>): UseCanResult {
-  let allowed = $state(true);
-  let reason = $state<string | undefined>(undefined);
-  let isLoading = $state(true);
+export function useCan(resourceOrOptions: string | UseCanOptions, action?: Action, params?: Record<string, unknown>): UseCanResult {
+  // Normalize arguments: support both (resource, action, params) and (options) signatures
+  const options: UseCanOptions = typeof resourceOrOptions === 'string'
+    ? { resource: resourceOrOptions, action: action ?? 'list', params }
+    : resourceOrOptions;
 
-  // Run the async check
-  canAccessAsync(resource, action, params).then((result: AccessControlResult) => {
-    allowed = result.can;
-    reason = result.reason;
-    isLoading = false;
-  }).catch(() => {
-    allowed = true; // default to allowed on error
-    isLoading = false;
-  });
+  const query = createQuery<CanResult>(() => ({
+    queryKey: ['useCan', options.resource, options.action, options.params],
+    queryFn: () => canAccessAsync(options.resource, options.action, options.params),
+    enabled: options.queryOptions?.enabled ?? true,
+    staleTime: options.queryOptions?.staleTime ?? 5 * 60 * 1000, // 5 min default cache
+  }));
 
   return {
-    get allowed() { return allowed; },
-    get reason() { return reason; },
-    get isLoading() { return isLoading; },
+    get allowed() { return query.data?.can ?? true; },
+    get reason() { return query.data?.reason; },
+    get isLoading() { return query.isLoading; },
   };
 }