@squidcloud/cli 1.0.445 → 1.0.447

package/dist/resources/claude/skills/squid-development/reference/security.md

@@ -0,0 +1,356 @@
+# Security Rules
+
+Squid provides a comprehensive security model using backend decorators. Every operation can be secured using security rules - backend functions that contain business logic to determine whether an operation is allowed.
+
+## Contents
+- Overview
+- Auth Methods
+- Database Security
+- Queue Security
+- Storage Security
+- API Security
+- Native Query Security
+- AI Security
+- Distributed Lock Security
+- GraphQL Security
+- Authentication Patterns
+- Best Practices
+
+## Overview
+
+Security decorators are backend-only decorators that define who can access your data and resources. They:
+- Return a boolean (or `Promise<boolean>`) indicating whether the operation is allowed
+- Give developers full control to implement any business logic needed for authorization
+- Are required when clients don't use an API key
+
+**Important:** Clients initialized with an API key **bypass all security rules**. Security rules only apply to clients using authentication providers.
+
+## Auth Methods
+
+These methods are available in all security rule functions via `this`:
+
+```typescript
+// Get user authentication (JWT token)
+this.getUserAuth() // AuthWithBearer | undefined
+  // Returns: { type: 'Bearer', userId: string, expiration: number, attributes: Record<string, any> }
+
+// Get API key authentication
+this.getApiKeyAuth() // AuthWithApiKey | undefined
+  // Returns: { type: 'ApiKey', apiKey: string }
+
+this.isAuthenticated()       // boolean - true if user token OR API key
+this.assertIsAuthenticated() // throws if not authenticated
+this.assertApiKeyCall()      // throws if not API key auth
+```
+
+## Database Security
+
+### @secureDatabase
+
+Secures operations across an entire database integration.
+
+```typescript
+import { SquidService, secureDatabase, QueryContext, MutationContext } from '@squidcloud/backend';
+
+export class MyService extends SquidService {
+  @secureDatabase('read')
+  allowRead(context: QueryContext<User>): boolean {
+    const userId = this.getUserAuth()?.userId;
+    if (!userId) return false;
+    return context.isSubqueryOf('userId', '==', userId);
+  }
+
+  @secureDatabase('write')
+  allowWrite(context: MutationContext<User>): boolean {
+    return this.isAuthenticated();
+  }
+
+  @secureDatabase('all')
+  allowAll(): boolean {
+    return this.isAuthenticated();
+  }
+
+  // Secure specific integration
+  @secureDatabase('insert', 'my-integration-id')
+  allowInsertInIntegration(context: MutationContext): boolean {
+    return context.after?.createdBy === 'admin';
+  }
+}
+```
+
+**Operation Types:** `'read'`, `'write'`, `'update'`, `'insert'`, `'delete'`, `'all'`
+
+### @secureCollection
+
+Secures operations on a specific collection.
+
+```typescript
+// QueryContext for 'read' operations
+@secureCollection('users', 'read')
+allowUserRead(context: QueryContext): boolean {
+  const userId = this.getUserAuth()?.userId;
+  if (!userId) return false;
+  // Check if query filters on a specific field
+  return context.isSubqueryOf('id', '==', userId);
+}
+
+// MutationContext for 'insert', 'update', 'delete' operations
+@secureCollection('users', 'update')
+allowUserUpdate(context: MutationContext<User>): boolean {
+  const userId = this.getUserAuth()?.userId;
+  if (!userId) return false;
+
+  // context.before: document state before mutation
+  // context.after: document state after mutation
+
+  // Check if specific paths were affected
+  if (context.affectsPath('email')) {
+    return false; // Don't allow email changes
+  }
+
+  // Check ownership
+  return context.after?.id === userId;
+}
+```
+
+### Context Types
+
+**QueryContext<T>** - Used for 'read' and 'all' operations:
+```typescript
+context.collectionName   // Name of the collection being queried
+context.integrationId    // Integration ID
+context.limit            // Query limit
+context.isSubqueryOf(field, operator, value) // Check if query filters on field
+```
+
+**MutationContext<T>** - Used for 'insert', 'update', 'delete' operations:
+```typescript
+context.before           // Document before mutation (undefined for insert)
+context.after            // Document after mutation (undefined for delete)
+context.affectsPath(path) // Check if specific field path was modified
+```
+
+Both types are exported from `@squidcloud/backend`.
+
+## Queue Security
+
+### @secureTopic
+
+Secures queue topics.
+
+```typescript
+import { SquidService, secureTopic, TopicReadContext, TopicWriteContext } from '@squidcloud/backend';
+
+// Read security
+@secureTopic('notifications', 'read')
+allowRead(context: TopicReadContext): boolean {
+  return this.isAuthenticated();
+}
+
+// Write security with message validation
+@secureTopic('notifications', 'write')
+allowWrite(context: TopicWriteContext<Message>): boolean {
+  return context.messages.length <= 100;
+}
+
+// For Kafka/Confluent integrations, specify integrationId as third parameter
+@secureTopic('events', 'read', 'kafka-integration')
+allowKafkaRead(context: TopicReadContext): boolean {
+  return this.isAuthenticated();
+}
+```
+
+**Types:** `'read'`, `'write'`, `'all'`
+
+**Context Types:**
+- `TopicReadContext` - contains `integrationId`, `topicName`
+- `TopicWriteContext<T>` - contains `integrationId`, `topicName`, `messages` array
+
+## Storage Security
+
+### @secureStorage
+
+Secures storage operations.
+
+```typescript
+import { SquidService, secureStorage, StorageContext } from '@squidcloud/backend';
+
+@secureStorage('write')
+allowWrite(context: StorageContext): boolean {
+  return !context.pathsInBucket.some(p => p.startsWith('/admin'));
+}
+
+@secureStorage('read', 'my-s3-integration')
+allowRead(context: StorageContext): boolean {
+  return this.isAuthenticated();
+}
+```
+
+**Types:** `'read'`, `'write'`, `'update'`, `'insert'`, `'delete'`, `'all'`
+
+## API Security
+
+### @secureApi
+
+Secures API integration calls.
+
+```typescript
+import { SquidService, secureApi, ApiCallContext } from '@squidcloud/backend';
+
+// Secure specific endpoint
+@secureApi('stripe-api', 'create-charge')
+allowCharge(context: ApiCallContext): boolean {
+  const amount = (context.body as any)?.amount;
+  return amount < 10000;
+}
+
+// Secure entire API integration
+@secureApi('external-api')
+allowApi(): boolean {
+  return this.isAuthenticated();
+}
+```
+
+## Native Query Security
+
+### @secureNativeQuery
+
+Secures native database queries (SQL, MongoDB aggregation, etc.).
+
+```typescript
+import { SquidService, secureNativeQuery, NativeQueryContext } from '@squidcloud/backend';
+
+@secureNativeQuery('postgres-db')
+allowQuery(context: NativeQueryContext): boolean {
+  if (context.type === 'relational') {
+    // Prevent destructive queries
+    return !context.query.toUpperCase().includes('DROP');
+  }
+  return true;
+}
+```
+
+## AI Security
+
+### @secureAiQuery
+
+Secures AI query execution.
+
+```typescript
+import { SquidService, secureAiQuery, AiQueryContext } from '@squidcloud/backend';
+
+@secureAiQuery()
+allowAiQuery(context: AiQueryContext): boolean {
+  return this.isAuthenticated() && context.prompt.length < 1000;
+}
+
+@secureAiQuery('specific-integration')
+allowSpecificAiQuery(context: AiQueryContext): boolean {
+  return this.getUserAuth()?.attributes?.role === 'admin';
+}
+```
+
+### @secureAiAgent
+
+Secures AI agent access.
+
+```typescript
+import { SquidService, secureAiAgent, SecureAiAgentContext } from '@squidcloud/backend';
+
+// Secure specific agent
+@secureAiAgent('customer-bot')
+allowAgent(context: SecureAiAgentContext): boolean {
+  return !context.prompt?.includes('admin');
+}
+
+// Secure all agents
+@secureAiAgent()
+allowAllAgents(): boolean {
+  return this.isAuthenticated();
+}
+```
+
+## Distributed Lock Security
+
+### @secureDistributedLock
+
+Secures distributed lock access.
+
+```typescript
+import { SquidService, secureDistributedLock, DistributedLockContext } from '@squidcloud/backend';
+
+// Secure specific mutex
+@secureDistributedLock('payment-processing')
+allowPaymentLock(context: DistributedLockContext): boolean {
+  return this.isAuthenticated() && context.mutex === 'payment-processing';
+}
+
+// Secure all mutexes
+@secureDistributedLock()
+allowAllLocks(context: DistributedLockContext): boolean {
+  return this.isAuthenticated();
+}
+```
+
+**Important:** Without API key, you must define `@secureDistributedLock` decorators to allow lock acquisition.
+
+## GraphQL Security
+
+### @secureGraphQL
+
+Secures GraphQL operations.
+
+```typescript
+import { SquidService, secureGraphQL, GraphqlContext } from '@squidcloud/backend';
+
+@secureGraphQL('my-graphql-api')
+allowGraphQL(context: GraphqlContext): boolean {
+  return this.isAuthenticated();
+}
+```
+
+**Context:** `GraphqlContext` provides the full context including `query`, `variables`, `operationName`, and `isGraphiQL` (boolean indicating if request is from GraphiQL IDE).
+
+## Authentication Patterns
+
+### Row-Level Security Example
+
+```typescript
+@secureCollection('documents', 'read')
+allowDocumentRead(context: QueryContext<Document>): boolean {
+  const userId = this.getUserAuth()?.userId;
+  if (!userId) return false;
+
+  // Users can only read documents they own or that are public
+  return context.isSubqueryOf('ownerId', '==', userId) ||
+         context.isSubqueryOf('isPublic', '==', true);
+}
+
+@secureCollection('documents', 'update')
+allowDocumentUpdate(context: MutationContext<Document>): boolean {
+  const userId = this.getUserAuth()?.userId;
+  if (!userId) return false;
+
+  // Only owner can update
+  return context.before?.ownerId === userId;
+}
+```
+
+### Role-Based Access Example
+
+```typescript
+@secureCollection('admin-data', 'read')
+allowAdminRead(): boolean {
+  const role = this.getUserAuth()?.attributes?.role;
+  return role === 'admin' || role === 'superadmin';
+}
+```
+
+## Best Practices
+
+1. **Always secure collections/topics/storage** - Default to deny
+2. **Validate input in executables** - Check auth and params
+3. **Use `isSubqueryOf()` for read rules** - Ensures queries are properly filtered
+4. **Use `affectsPath()` for write rules** - Control which fields can be modified
+5. **Never trust client data** - Always validate in security rules
+6. **Test security rules thoroughly** - Use different user contexts

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@squidcloud/cli",
-  "version": "1.0.445",
+  "version": "1.0.447",
   "description": "The Squid CLI",
   "main": "dist/index.js",
   "scripts": {
@@ -28,7 +28,7 @@
     "node": ">=18.0.0"
   },
   "dependencies": {
-    "@squidcloud/local-backend": "^1.0.445",
+    "@squidcloud/local-backend": "^1.0.447",
     "adm-zip": "^0.5.16",
     "copy-webpack-plugin": "^12.0.2",
     "decompress": "^4.2.1",