@stonecrop/casl-middleware 0.7.0

package/README.md

@@ -0,0 +1,149 @@
+# CASL GraphQL Middleware
+
+A middleware solution for integrating CASL authorization with GraphQL servers, with specific support for Postgraphile and Nuxt GraphQL Server.
+
+## Features
+
+- CASL integration with GraphQL resolvers
+- Framework-specific helpers for Postgraphile and Nuxt
+- Type-safe ability definitions
+- Support for field-level permissions
+- Ability to combine multiple authorization rules
+
+## Installation
+
+```bash
+pnpm add @stonecrop/casl-middleware
+```
+
+## Basic Usage
+
+### Core Middleware
+
+```typescript
+import { createCaslMiddleware } from '@stonecrop/casl-middleware'
+
+const middleware = createCaslMiddleware({
+  subjectMap: {
+    User: 'User',
+    Item: 'Item'
+  },
+  fieldPermissions: {
+    'Item.price': [{ action: 'read', subject: 'item' }]
+  }
+})
+```
+
+### Postgraphile Integration
+
+```typescript
+// graphile.config.js
+import { pglCaslPlugin } from '@stonecrop/casl-middleware'
+import { postgraphile } from 'postgraphile'
+
+export default {
+  pgServices: [
+    makePgService({
+      connectionString: 'postgres://testuser:testpass@postgres:5432/testdb',
+      schemas: ['public'],
+    }),
+  ],
+  plugins: [pglCaslPlugin],
+}
+```
+
+### Testing Abilities in GraphiQL
+
+Create an ability:
+```graphql
+mutation CreateAbility {
+  createAbility(input: {
+    userId: "123",
+    roles: ["admin"]
+  }) {
+    success
+    ability
+    message
+  }
+}
+```
+
+Test protected queries:
+```graphql
+query GetSecretData {
+  getSecretData {
+    id
+    content
+  }
+}
+```
+
+## Development
+
+### Prerequisites
+
+- Node.js >= 20
+- pnpm
+- Docker and Docker Compose
+
+### Local Development
+
+1. Clone the repository:
+```bash
+git clone <repository-url>
+cd casl-middleware
+```
+
+2. Install dependencies:
+```bash
+pnpm install
+```
+
+3. Run the Postgraphile example:
+```bash
+pnpm dev:postgraphile
+```
+
+### Project Structure
+
+```
+.
+├── examples/
+│   └── postgraphile/        # Postgraphile example implementation
+├── src/
+│   ├── middleware/         # Core CASL middleware
+│   ├── types/             # TypeScript types
+│   └── index.ts           # Main exports
+```
+
+## Framework Support
+
+### Postgraphile
+- Implements CASL as a Postgraphile plugin
+- Supports ability creation and management
+- Integrates with Postgraphile's schema extension system
+
+### Nuxt GraphQL Server
+- Provides middleware for Nuxt's GraphQL module
+- Handles ability creation on request
+- Integrates with Nuxt's context system
+
+## Contributing
+
+1. Fork the repository
+2. Create your feature branch
+3. Commit your changes
+4. Push to the branch
+5. Create a new Pull Request
+
+## License
+
+MIT License
+
+## TODOs
+
+- [ ] Add comprehensive test suite
+- [ ] Add more framework integrations
+- [ ] Implement ability persistence
+- [ ] Add more examples for different use cases
+- [ ] Add documentation for advanced usage scenarios

package/dist/casl-middleware.d.ts

@@ -0,0 +1,158 @@
+import { GraphileConfig as GraphileConfig_2 } from 'postgraphile/graphile-build';
+import { GraphQLResolveInfo } from 'graphql';
+import { PureAbility } from '@casl/ability';
+
+/**
+ * Function type for building user abilities
+ * @public
+ */
+declare type AbilityBuilderFunction = (user?: Context['user']) => Promise<AppAbility> | AppAbility;
+
+/**
+ * Response type for ability creation mutations
+ * @public
+ */
+export declare interface AbilityResponse {
+    /** Whether the ability was created successfully */
+    success: boolean;
+    /** The created ability rules */
+    ability: any;
+    /** Success or error message */
+    message: string;
+}
+
+/**
+ * CASL ability type for authorization with flexible subject types
+ * @public
+ */
+export declare type AppAbility = PureAbility<[string, any], any>;
+
+/**
+ * GraphQL context with CASL ability and user information
+ * @public
+ */
+export declare interface Context {
+    /** CASL ability instance for authorization checks */
+    ability?: AppAbility;
+    /** Current authenticated user */
+    user?: User;
+    /** Additional context properties */
+    [key: string]: any;
+}
+
+/**
+ * Create ability using a provided builder function
+ * @param user - User information for building the ability
+ * @param builderFn - Function to build the ability
+ * @returns Promise resolving to the created ability
+ * @public
+ */
+export declare const createAbility: (user?: Context["user"], builderFn?: AbilityBuilderFunction) => Promise<AppAbility>;
+
+/**
+ * Input type for creating a new ability
+ * @public
+ */
+export declare interface CreateAbilityInput {
+    /** User ID to create ability for */
+    userId: string;
+    /** Array of role names to assign */
+    roles: string[];
+}
+
+/**
+ * Creates CASL authorization middleware for GraphQL resolvers
+ * @param options - Configuration options for the middleware
+ * @returns Middleware function that wraps resolvers with authorization checks
+ * @public
+ */
+export declare const createCaslMiddleware: (options?: MiddlewareOptions) => (resolve: ResolverFn, root: any, args: any, context: Context, info: GraphQLResolveInfo) => Promise<any>;
+
+/**
+ * Detects the subject type from an object for CASL authorization
+ * @param object - The object to detect the subject type from
+ * @returns The subject type string
+ * @public
+ */
+export declare const detectSubjectType: (object: any) => string;
+
+/**
+ * Field-level permission definition for fine-grained access control
+ * @public
+ */
+export declare interface FieldPermission {
+    /** CASL action (e.g., 'read', 'write') */
+    action: string;
+    /** Subject/resource type to apply permission to */
+    subject: string;
+    /** Specific field name (optional) */
+    field?: string;
+    /** Conditional rules for permission */
+    conditions?: any;
+}
+
+/**
+ * Middleware function that wraps a GraphQL resolver with authorization logic
+ * @public
+ */
+export declare type MiddlewareFn = (resolve: ResolverFn, root: any, args: any, context: Context, info: GraphQLResolveInfo) => Promise<any> | any;
+
+/**
+ * Configuration options for CASL middleware
+ * @public
+ */
+export declare interface MiddlewareOptions {
+    /** Mapping of GraphQL types to authorization subjects */
+    subjectMap?: Record<string, string>;
+    /** Mapping of GraphQL operations to CASL actions */
+    actionMap?: Record<string, string>;
+    /** Field-level permission rules */
+    fieldPermissions?: Record<string, FieldPermission[]>;
+    /** Custom function to build user abilities */
+    abilityBuilder?: AbilityBuilderFunction;
+    /** Enable debug logging */
+    debug?: boolean;
+}
+
+/**
+ * PostGraphile plugin for CASL authorization
+ * @public
+ */
+export declare const pglCaslPlugin: GraphileConfig_2.Plugin;
+
+/**
+ * Plugin configuration options for framework integrations
+ * @public
+ */
+export declare interface PluginOptions extends MiddlewareOptions {
+    /** Custom function to build user abilities */
+    abilityBuilder?: AbilityBuilderFunction;
+    /** Ability caching configuration */
+    cacheOptions?: {
+        /** Time-to-live in milliseconds */
+        ttl?: number;
+        /** Function to generate cache key from user */
+        key?: (user?: User) => string;
+    };
+}
+
+/**
+ * GraphQL resolver function type
+ * @public
+ */
+export declare type ResolverFn = (root: any, args: any, context: Context, info: GraphQLResolveInfo) => Promise<any> | any;
+
+/**
+ * User information for authorization
+ * @public
+ */
+export declare interface User {
+    /** Unique identifier for the user */
+    id: string;
+    /** Array of role names assigned to the user */
+    roles?: string[];
+    /** Additional user properties */
+    [key: string]: any;
+}
+
+export { }