feat: add global abilities with type-safe enforcement

Global abilities act as gatekeepers that are checked before any specific
abilities. All global abilities must return true for permission checks to
proceed.

Features:
- New GlobalAbility symbol to mark abilities as global
- Type-safe overloads prevent mixing global and specific matchers
- Global abilities checked first, fail-fast on denial

Use cases:
- Read-only mode enforcement
- Maintenance mode restrictions
- Feature flag checks
- Multi-tenant isolation

Author: topaxi

README.md

@@ -274,6 +274,81 @@ This is especially useful when:
 - You want to prevent mistakes like checking `ability.can(User, 'edit')` when `User` only supports `'view'`
 - You're passing class constructors instead of string matchers
 
+### 6. Global abilities (optional)
+
+Global abilities are special abilities that act as gatekeepers for your permission
+system. They are checked **before** any specific abilities, and **all** global
+abilities must return `true` for the permission check to proceed.
+
+**When to use global abilities:**
+
+- Enforce read-only mode across your entire application
+- Implement maintenance mode restrictions
+- Check license or feature flags
+- Verify user status (banned, suspended, etc.)
+- Multi-tenant isolation checks
+
+**Example:**
+
+```typescript
+import { AbilityFor, Ability, GlobalAbility } from 'ng-ability';
+
+// Global ability to enforce read-only mode
+@AbilityFor(GlobalAbility)
+export class ReadOnlyModeAbility implements Ability<User> {
+  can(currentUser: User | null, action: string): boolean {
+    // Block all write operations when user is in read-only mode
+    if (currentUser?.readOnly && action !== 'read') {
+      return false;
+    }
+    // Allow the check to continue to specific abilities
+    return true;
+  }
+}
+
+// Regular ability
+@AbilityFor('Article')
+export class ArticleAbility implements Ability<User> {
+  can(currentUser: User | null, action: string): boolean {
+    // This will only be checked if all global abilities return true
+    return currentUser != null;
+  }
+}
+```
+
+Register global abilities like any other ability:
+
+```typescript
+bootstrapApplication(AppComponent, {
+  providers: [
+    provideAbilities(AbilityUserContext, [
+      ReadOnlyModeAbility,  // Global ability
+      ArticleAbility,       // Regular abilities
+      // ... other abilities
+    ]),
+  ],
+});
+```
+
+**Type safety:**
+
+The type system enforces that abilities are either global OR specific:
+
+```typescript
+// ✓ Valid
+@AbilityFor(GlobalAbility)
+export class GlobalCheck implements Ability<User> { ... }
+
+// ✗ Invalid: Cannot mix GlobalAbility with matchers
+@AbilityFor(GlobalAbility, 'Article')  // TypeScript error!
+```
+
+**How it works:**
+
+1. When you call `can('Article', 'write')`, all global abilities are checked first
+2. If any global ability returns `false`, the check fails immediately
+3. Only if all global abilities return `true` does the check proceed to `ArticleAbility`
+
 ## Development
 
 ### Build

docs/GLOBAL_ABILITIES.md

@@ -0,0 +1,223 @@
+# Global Abilities
+
+Global abilities are special abilities that act as gatekeepers for your permission system. They are checked **before** any specific abilities, and **all** global abilities must return `true` for the permission check to proceed.
+
+## Use Cases
+
+Global abilities are perfect for implementing cross-cutting authorization concerns that apply to all or most of your abilities, such as:
+
+- Read-only mode enforcement
+- Maintenance mode restrictions
+- License/feature flag checks
+- Global user status checks (banned, suspended, etc.)
+- Tenant-level permissions in multi-tenant applications
+
+## Usage
+
+### 1. Import the GlobalAbility Symbol
+
+```typescript
+import { AbilityFor, Ability, GlobalAbility } from 'ng-ability';
+```
+
+### 2. Create a Global Ability
+
+Mark any ability class with `@AbilityFor(GlobalAbility)` to make it a global ability:
+
+```typescript
+@AbilityFor(GlobalAbility)
+export class ReadOnlyModeAbility implements Ability<User> {
+  can(currentUser: User | null, action: string): boolean {
+    // Block all write operations when user is in read-only mode
+    if (currentUser?.readOnly && action !== 'read') {
+      return false;
+    }
+    // Allow the check to continue to specific abilities
+    return true;
+  }
+}
+```
+
+### 3. Register the Global Ability
+
+Register it like any other ability using `provideAbilities()`:
+
+```typescript
+import { provideAbilities } from 'ng-ability';
+import { ReadOnlyModeAbility } from './abilities/read-only-mode.ability';
+import { PostAbility } from './abilities/post.ability';
+import { CommentAbility } from './abilities/comment.ability';
+
+export const appConfig: ApplicationConfig = {
+  providers: [
+    provideAbilities([
+      ReadOnlyModeAbility,  // Global ability
+      PostAbility,          // Specific abilities
+      CommentAbility,
+      // ... other abilities
+    ])
+  ]
+};
+```
+
+## How It Works
+
+When you call `can()`, the permission check follows this flow:
+
+1. **Global Abilities Check**: All global abilities are invoked first
+   - If **any** global ability returns `false`, the entire check fails immediately
+   - Specific abilities are **not** checked if a global ability fails
+
+2. **Specific Ability Check**: If all global abilities return `true`
+   - The matching specific ability is found and invoked
+   - That ability's result is returned
+
+## Examples
+
+### Example 1: Read-Only Mode
+
+```typescript
+interface User {
+  id: string;
+  readOnly: boolean;
+}
+
+@AbilityFor(GlobalAbility)
+export class ReadOnlyModeAbility implements Ability<User> {
+  can(currentUser: User | null, action: string): boolean {
+    if (currentUser?.readOnly && action !== 'read') {
+      return false;
+    }
+    return true;
+  }
+}
+
+@AbilityFor('Post')
+export class PostAbility implements Ability<User> {
+  can(currentUser: User | null, action: string): boolean {
+    if (action === 'delete') {
+      return currentUser?.role === 'admin';
+    }
+    return true;
+  }
+}
+
+// Usage in a component:
+export class PostComponent {
+  private abilityService = inject(NgAbilityService);
+
+  // When user is in read-only mode:
+  // - can('Post', 'read') → true (allowed by global ability)
+  // - can('Post', 'write') → false (blocked by global ability, PostAbility never checked)
+  // - can('Post', 'delete') → false (blocked by global ability, PostAbility never checked)
+
+  // When user is NOT in read-only mode:
+  // - can('Post', 'read') → true (global passes, PostAbility allows)
+  // - can('Post', 'write') → true (global passes, PostAbility allows)
+  // - can('Post', 'delete') → depends on role (global passes, PostAbility checks role)
+}
+```
+
+### Example 2: Multiple Global Abilities
+
+You can have multiple global abilities - all must return `true`:
+
+```typescript
+@AbilityFor(GlobalAbility)
+export class MaintenanceModeAbility implements Ability<User> {
+  private maintenance = inject(MaintenanceService);
+
+  can(currentUser: User | null, action: string): boolean {
+    // Only admins can do anything during maintenance
+    if (this.maintenance.isActive() && currentUser?.role !== 'admin') {
+      return false;
+    }
+    return true;
+  }
+}
+
+@AbilityFor(GlobalAbility)
+export class FeatureFlagAbility implements Ability<User> {
+  private features = inject(FeatureService);
+
+  can(currentUser: User | null, action: string): boolean {
+    // Check if the action requires a feature flag
+    const requiredFeature = this.getRequiredFeature(action);
+    if (requiredFeature && !this.features.isEnabled(requiredFeature)) {
+      return false;
+    }
+    return true;
+  }
+
+  private getRequiredFeature(action: string): string | null {
+    // Map actions to feature flags
+    if (action === 'export') return 'export-feature';
+    if (action === 'share') return 'sharing-feature';
+    return null;
+  }
+}
+```
+
+### Example 3: Tenant-Level Permissions
+
+```typescript
+interface TenantUser {
+  id: string;
+  tenantId: string;
+  role: string;
+}
+
+@AbilityFor(GlobalAbility)
+export class TenantAccessAbility implements Ability<TenantUser> {
+  private tenantService = inject(TenantService);
+
+  can(currentUser: TenantUser | null, action: string, thing?: any): boolean {
+    if (!currentUser) return false;
+
+    // Check if user's tenant has access to the resource
+    const resourceTenantId = thing?.tenantId;
+    if (resourceTenantId && resourceTenantId !== currentUser.tenantId) {
+      return false; // User can't access resources from other tenants
+    }
+
+    return true;
+  }
+}
+```
+
+## Type Safety
+
+The type system enforces that abilities are either global OR specific, not both:
+
+```typescript
+// ✓ Valid: Global ability
+@AbilityFor(GlobalAbility)
+export class ReadOnlyAbility implements Ability<User> { ... }
+
+// ✓ Valid: Specific ability
+@AbilityFor('Document')
+export class DocumentAbility implements Ability<User> { ... }
+
+// ✗ Invalid: Cannot mix GlobalAbility with other matchers
+@AbilityFor(GlobalAbility, 'Document')  // TypeScript error!
+export class InvalidAbility implements Ability<User> { ... }
+```
+
+This prevents confusion and ensures clear separation between global and specific authorization logic. If you need both global checks and specific resource checks, create two separate abilities.
+
+## Best Practices
+
+1. **Keep Global Abilities Simple**: They run on every permission check, so keep them fast and focused.
+
+2. **Return `true` to Continue**: Global abilities should return `true` to allow the check to proceed to specific abilities. Only return `false` when you want to block the action entirely.
+
+3. **Order Doesn't Matter**: All global abilities are checked, and the order doesn't matter (they all must return `true`).
+
+4. **Use for Cross-Cutting Concerns**: Global abilities are for concerns that span across multiple resources/actions. Use specific abilities for resource-specific logic.
+
+## Performance Considerations
+
+- Global abilities are called on **every** permission check
+- Keep global ability logic fast and efficient
+- Consider caching expensive operations (like feature flag checks)
+- Minimize the number of global abilities (2-3 is typical)

projects/ng-ability/src/lib/ability.ts

@@ -1,18 +1,38 @@
-import { AbilityMatcher } from './interfaces';
+import { AbilityMatcher, GlobalAbility } from './interfaces';
 
 const abilityMatchersMap = new WeakMap<Function, AbilityMatcher<unknown>[]>();
+const globalAbilitiesSet = new WeakSet<Function>();
 
 export function getAbilityMatchers(
   klass: Function,
 ): AbilityMatcher<unknown>[] | undefined {
   return abilityMatchersMap.get(klass);
 }
 
+export function isGlobalAbility(klass: Function): boolean {
+  return globalAbilitiesSet.has(klass);
+}
+
+export function AbilityFor<T>(global: typeof GlobalAbility): ClassDecorator;
 export function AbilityFor<T>(
   ...abilityMatchers: AbilityMatcher<T>[]
+): ClassDecorator;
+export function AbilityFor<T>(
+  ...abilityMatchers: (AbilityMatcher<T> | typeof GlobalAbility)[]
 ): ClassDecorator {
   return <TFunction extends Function>(klass: TFunction) => {
-    abilityMatchersMap.set(klass, abilityMatchers as AbilityMatcher<unknown>[]);
+    // Check if this is a global ability
+    if (abilityMatchers[0] === GlobalAbility) {
+      globalAbilitiesSet.add(klass);
+      // Don't store GlobalAbility symbol in matchers map
+      abilityMatchersMap.set(klass, []);
+    } else {
+      abilityMatchersMap.set(
+        klass,
+        abilityMatchers as AbilityMatcher<unknown>[],
+      );
+    }
+
     return klass;
   };
 }

projects/ng-ability/src/lib/interfaces.ts

@@ -1,5 +1,25 @@
 import type { Signal } from '@angular/core';
 
+/**
+ * Special symbol to mark an ability as global.
+ * Global abilities are checked first before any specific abilities,
+ * and all global abilities must return true for permission checks to proceed.
+ *
+ * @example
+ * ```typescript
+ * @AbilityFor(GlobalAbility)
+ * export class ReadOnlyAbility implements Ability<User> {
+ *   can(currentUser: User | null, action: string) {
+ *     if (currentUser?.readOnly && action !== 'read') {
+ *       return false;
+ *     }
+ *     return true;
+ *   }
+ * }
+ * ```
+ */
+export const GlobalAbility = Symbol('GlobalAbility');
+
 export type AbilityMatcher<T> = { new (): T } | ((t: T) => boolean) | string;
 
 // eslint-disable-next-line @typescript-eslint/no-empty-object-type