@apso/cli 0.4.2 → 0.5.0

package/README.md

@@ -1,14 +1,46 @@
 # Apso CLI
 
-- [Apso CLI](#apso-cli)
-- [Prerequisites](#prerequisites)
+Generate production-ready NestJS backends from schema definitions.
+
+## Quick Start
+
+```bash
+# 1. Install CLI
+npm install -g @apso/apso-cli
+
+# 2. Create new project
+apso server new --name myapp
+
+# 3. Edit .apsorc to define your schema (see examples below)
+
+# 4. Generate code
+apso server scaffold
+
+# 5. Start database & provision schema
+npm run compose && npm run provision
+
+# 6. Run development server
+npm run start:dev
+```
+
+---
+
+## Table of Contents
+
+- [Quick Start](#quick-start)
 - [Usage](#usage)
+- [Important: Never Modify Autogen Files](#-important-never-add-custom-code-to-autogen-files)
+- [Common First-Time Mistakes](#️-common-first-time-mistakes)
 - [Local Development](#local-development)
 - [Populating an .apsorc File](#populating-an-apsorc-file)
 - [Auto-Generated Code Reference](#auto-generated-code-reference)
-- [Debugging](##debugging)
+- [Relationships](#relationships)
+- [Data Scoping (Multi-Tenant Isolation)](#data-scoping-multi-tenant-isolation)
+- [Schema Reference](#schema-reference)
+- [Debugging](#debugging)
 - [Commands](#commands)
 
+---
 
 # Usage
 
@@ -139,13 +171,47 @@ export class LambdaDeploymentController {
 
 ---
 
-**Summary:**  
-> Always put your custom code in `src/extensions/[[EntityName]]/`.  
-> Never modify files in `src/autogen/`.  
+**Summary:**
+> Always put your custom code in `src/extensions/[[EntityName]]/`.
+> Never modify files in `src/autogen/`.
 > This ensures your work is safe and your project remains maintainable as you evolve your data model with Apso CLI.
 
 ---
 
+## ⚠️ Common First-Time Mistakes
+
+### 1. Modifying `autogen/` Files
+**Problem:** Changes get overwritten on next scaffold
+**Solution:** Always use `extensions/` directory for custom code
+
+### 2. Defining Both Sides of Relationships
+**Problem:** Duplicate properties and TypeScript errors
+**Solution:** Define relationships **once** - Apso auto-generates the inverse side
+
+Example:
+```json
+// ❌ WRONG - Creates conflicts
+{ "from": "User", "to": "Workspace", "type": "OneToMany" }
+{ "from": "Workspace", "to": "User", "type": "ManyToOne" }
+
+// ✅ CORRECT - Define one side only
+{ "from": "Workspace", "to": "User", "type": "ManyToOne", "to_name": "owner" }
+```
+
+### 3. Skipping Database Provisioning
+**Problem:** Server fails to start with missing table errors
+**Solution:** Always run `npm run provision` after scaffold
+
+### 4. Wrong .apsorc Version
+**Problem:** Schema doesn't generate correctly
+**Solution:** Ensure `"version": 2` at top of .apsorc
+
+### 5. Forgetting to Start Docker
+**Problem:** Database connection refused errors
+**Solution:** Run `npm run compose` before starting server
+
+---
+
 # Local Development
 
 Clone apso-cli on your machine. Navigate to the repo in your code editor and run the below commands
@@ -680,6 +746,221 @@ Refer to the [example v2 file](#example-apsorc-v2-file) for usage.
 > - Avoid deep nesting and duplicate definitions.
 > - Always inspect generated code and test your build after scaffolding.
 
+## Data Scoping (Multi-Tenant Isolation)
+
+Apso CLI supports automatic generation of scope guards that enforce data isolation at the application layer. This is useful for multi-tenant applications where users should only access data within their assigned scope (e.g., workspace, organization, team).
+
+### What is scopeBy?
+
+The `scopeBy` property on entities defines which field(s) determine the authorization scope for that entity. When configured, Apso generates NestJS guards that:
+
+- **Auto-inject** scope values on create operations (POST requests)
+- **Auto-filter** queries by scope values on list operations (GET without ID)
+- **Verify ownership** on single-resource operations (GET/PUT/PATCH/DELETE by ID)
+
+This is Apso's answer to PostgreSQL Row-Level Security (RLS), implemented at the application layer for flexibility and visibility.
+
+### Basic Example
+
+```json
+{
+  "version": 2,
+  "entities": [
+    {
+      "name": "Project",
+      "scopeBy": "workspaceId",
+      "fields": [
+        { "name": "name", "type": "text" }
+      ]
+    }
+  ]
+}
+```
+
+This generates a guard that ensures:
+- All Project queries filter by `workspaceId` from the request context
+- New Projects automatically get the `workspaceId` injected
+- Single Project access verifies the Project belongs to the user's workspace
+
+### scopeBy Configuration Options
+
+#### Single Field Scoping
+```json
+{
+  "name": "Project",
+  "scopeBy": "workspaceId"
+}
+```
+
+#### Multiple Field Scoping
+```json
+{
+  "name": "Task",
+  "scopeBy": ["workspaceId", "projectId"]
+}
+```
+
+#### Nested Path Scoping
+For entities that don't have a direct scope field but inherit scope through a relationship:
+```json
+{
+  "name": "Comment",
+  "scopeBy": "task.workspaceId"
+}
+```
+This tells the guard to look up the Task relationship and verify the workspaceId through that path.
+
+### scopeOptions
+
+Fine-tune scoping behavior with `scopeOptions`:
+
+```json
+{
+  "name": "AuditLog",
+  "scopeBy": "workspaceId",
+  "scopeOptions": {
+    "injectOnCreate": false,
+    "enforceOn": ["find", "get"],
+    "bypassRoles": ["admin", "superadmin"]
+  }
+}
+```
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `injectOnCreate` | boolean | `true` | Auto-inject scope value on POST requests |
+| `enforceOn` | string[] | `["find", "get", "create", "update", "delete"]` | Operations where scope is enforced |
+| `bypassRoles` | string[] | `[]` | Roles that skip scope checking |
+
+### Generated Files
+
+When entities have `scopeBy` configured, `apso server scaffold` generates:
+
+```
+src/
+  guards/
+    scope.guard.ts      # Main guard implementation
+    guards.module.ts    # NestJS module with providers
+    index.ts            # Exports
+```
+
+### Enabling Guards
+
+Guards are generated but **not enabled globally by default** (for backward compatibility). To enable:
+
+#### Option 1: Global Enable (Recommended)
+Uncomment the APP_GUARD provider in `src/guards/guards.module.ts`:
+
+```typescript
+providers: [
+  ScopeGuard,
+  // Uncomment to enable globally:
+  {
+    provide: APP_GUARD,
+    useClass: ScopeGuard,
+  },
+],
+```
+
+#### Option 2: Per-Controller Enable
+Apply to specific controllers:
+
+```typescript
+import { ScopeGuard } from '../guards';
+
+@UseGuards(ScopeGuard)
+@Controller('projects')
+export class ProjectController { }
+```
+
+#### Option 3: Per-Route Enable
+Apply to specific routes:
+
+```typescript
+@UseGuards(ScopeGuard)
+@Get(':id')
+findOne(@Param('id') id: string) { }
+```
+
+### Decorators
+
+The generated guard supports these decorators:
+
+```typescript
+import { Public, SkipScopeCheck } from './guards';
+
+@Public()  // Skip ALL guards for this route
+@Get('public-endpoint')
+publicRoute() { }
+
+@SkipScopeCheck()  // Skip only scope checking (other guards still run)
+@Get('admin-dashboard')
+adminRoute() { }
+```
+
+### Request Context Integration
+
+The guard expects scope values in the request object. Set these in your authentication middleware:
+
+```typescript
+// In your auth middleware
+request.workspaceId = user.currentWorkspaceId;
+request.user = { roles: ['user'] };
+```
+
+### Complete Example
+
+```json
+{
+  "version": 2,
+  "entities": [
+    {
+      "name": "Workspace",
+      "fields": [{ "name": "name", "type": "text" }]
+    },
+    {
+      "name": "Project",
+      "scopeBy": "workspaceId",
+      "fields": [{ "name": "name", "type": "text" }]
+    },
+    {
+      "name": "Task",
+      "scopeBy": ["workspaceId", "projectId"],
+      "fields": [{ "name": "title", "type": "text" }]
+    },
+    {
+      "name": "Comment",
+      "scopeBy": "task.workspaceId",
+      "scopeOptions": {
+        "enforceOn": ["find", "get", "create", "delete"]
+      },
+      "fields": [{ "name": "text", "type": "text" }]
+    }
+  ],
+  "relationships": [
+    { "from": "Project", "to": "Workspace", "type": "ManyToOne" },
+    { "from": "Task", "to": "Project", "type": "ManyToOne" },
+    { "from": "Comment", "to": "Task", "type": "ManyToOne" }
+  ]
+}
+```
+
+### Scoping vs Authorization
+
+**Scoping** (what `scopeBy` provides):
+- Answers: "Which rows can this user see/modify?"
+- Data isolation based on tenant/workspace membership
+- Automatic filtering and injection
+
+**Authorization** (separate concern, not covered by `scopeBy`):
+- Answers: "Can this user perform this action?"
+- Role-based access control (RBAC)
+- Permission checking (create, read, update, delete)
+
+These are intentionally separate. Use `scopeBy` for data isolation, and implement authorization guards separately for permission checking.
+
+---
+
 ## Schema Reference
 
 The `.apsorc` file must conform to the [APSO Configuration Schema](./apsorc.schema.json). This schema defines all valid properties, types, and constraints for your configuration file.

package/dist/commands/server/scaffold.js

@@ -90,12 +90,14 @@ class Scaffold extends base_command_1.default {
                 console.log(`[mem] heapUsed after ${entity.name}: ${(used.heapUsed / 1024 / 1024).toFixed(2)} MB`);
             }
         }));
+        // Generate scope guards if any entities have scopeBy configured
+        await (0, lib_1.createGuards)(rootPath, entities);
         await (0, lib_1.createIndexAppModule)(autogenPath, entities, lowerCaseApiType);
         const totalBuildTime = perf_hooks_1.performance.now() - totalBuildStart;
         console.log(`[apso] Finished building all entities in ${totalBuildTime.toFixed(2)} ms`);
         const formatStart = perf_hooks_1.performance.now();
         console.log("[apso] Formatting files...");
-        await this.runNpmCommand(["run", "format", "src/autogen/**/*.ts"], true);
+        await this.runNpmCommand(["run", "format", "src/autogen/**/*.ts", "src/guards/**/*.ts"], true);
         const formatTime = perf_hooks_1.performance.now() - formatStart;
         console.log(`[apso] Finished formatting in ${formatTime.toFixed(2)} ms`);
     }

package/dist/lib/guards.d.ts

@@ -0,0 +1,46 @@
+import { Entity } from "./types";
+/**
+ * Represents a scope field configuration for template rendering
+ */
+interface ScopeFieldConfig {
+    field: string;
+    contextKey: string;
+    direct: boolean;
+    path?: string;
+}
+/**
+ * Represents a scoped entity configuration for template rendering
+ */
+interface ScopedEntityConfig {
+    name: string;
+    routeName: string;
+    repoName: string;
+    scopes: ScopeFieldConfig[];
+    injectOnCreate: boolean;
+    enforceOn: string[];
+    bypassRoles: string[];
+}
+/**
+ * Extracts scoped entity configurations from all entities.
+ *
+ * @param entities Array of all entities from the parsed .apsorc.
+ * @returns Array of scoped entity configurations for entities that have scopeBy defined.
+ */
+export declare function getScopedEntities(entities: Entity[]): ScopedEntityConfig[];
+/**
+ * Checks if any entities have scopeBy configured.
+ *
+ * @param entities Array of all entities from the parsed .apsorc.
+ * @returns True if at least one entity has scopeBy defined.
+ */
+export declare function hasScopedEntities(entities: Entity[]): boolean;
+/**
+ * Generates the guards module directory and files.
+ * Creates scope.guard.ts, guards.module.ts, and index.ts in the guards directory.
+ *
+ * @param rootPath The root path of the generated source (e.g., 'src').
+ * @param entities All entities from the parsed .apsorc.
+ * @returns {Promise<void>} A promise that resolves when the guard files are created.
+ */
+export declare const createGuards: (rootPath: string, entities: Entity[]) => Promise<void>;
+export {};

package/dist/lib/guards.js

@@ -0,0 +1,137 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createGuards = exports.hasScopedEntities = exports.getScopedEntities = void 0;
+const tslib_1 = require("tslib");
+const Eta = tslib_1.__importStar(require("eta"));
+const path = tslib_1.__importStar(require("path"));
+const fs = tslib_1.__importStar(require("fs"));
+const file_system_1 = require("./utils/file-system");
+const pluralize_1 = tslib_1.__importDefault(require("pluralize"));
+/**
+ * Default scope options when not specified
+ */
+const DEFAULT_SCOPE_OPTIONS = {
+    injectOnCreate: true,
+    enforceOn: ['find', 'get', 'create', 'update', 'delete'],
+    bypassRoles: [],
+};
+/**
+ * Parses scopeBy configuration and returns structured scope fields.
+ *
+ * @param scopeBy The scope configuration - either a single field/path string or an array of them.
+ * @returns An array of scope field configurations.
+ */
+function parseScopeBy(scopeBy) {
+    const scopes = Array.isArray(scopeBy) ? scopeBy : [scopeBy];
+    return scopes.map(scope => {
+        const isDirect = !scope.includes('.');
+        const field = isDirect ? scope : scope.split('.')[0];
+        // For direct fields, contextKey is the same as field
+        // For nested paths like 'task.workspaceId', we extract 'workspaceId' as contextKey
+        const contextKey = isDirect ? scope : scope.split('.').pop();
+        return {
+            field,
+            contextKey,
+            direct: isDirect,
+            path: isDirect ? undefined : scope,
+        };
+    });
+}
+/**
+ * Converts entity name to lowercase pluralized route name.
+ * e.g., "Project" -> "projects", "DiscoverySession" -> "discoverysessions"
+ *
+ * @param entityName The entity name in PascalCase.
+ * @returns The lowercase pluralized route name.
+ */
+function toRouteName(entityName) {
+    return (0, pluralize_1.default)(entityName).toLowerCase();
+}
+/**
+ * Converts entity name to repository variable name.
+ * e.g., "Project" -> "projectRepository", "DiscoverySession" -> "discoverySessionRepository"
+ *
+ * @param entityName The entity name in PascalCase.
+ * @returns The camelCase repository variable name.
+ */
+function toRepoName(entityName) {
+    const camelCase = entityName.charAt(0).toLowerCase() + entityName.slice(1);
+    return `${camelCase}Repository`;
+}
+/**
+ * Extracts scoped entity configurations from all entities.
+ *
+ * @param entities Array of all entities from the parsed .apsorc.
+ * @returns Array of scoped entity configurations for entities that have scopeBy defined.
+ */
+function getScopedEntities(entities) {
+    return entities
+        .filter(entity => entity.scopeBy)
+        .map(entity => {
+        const options = { ...DEFAULT_SCOPE_OPTIONS, ...entity.scopeOptions };
+        return {
+            name: entity.name,
+            routeName: toRouteName(entity.name),
+            repoName: toRepoName(entity.name),
+            scopes: parseScopeBy(entity.scopeBy),
+            injectOnCreate: options.injectOnCreate,
+            enforceOn: options.enforceOn,
+            bypassRoles: options.bypassRoles,
+        };
+    });
+}
+exports.getScopedEntities = getScopedEntities;
+/**
+ * Checks if any entities have scopeBy configured.
+ *
+ * @param entities Array of all entities from the parsed .apsorc.
+ * @returns True if at least one entity has scopeBy defined.
+ */
+function hasScopedEntities(entities) {
+    return entities.some(entity => entity.scopeBy);
+}
+exports.hasScopedEntities = hasScopedEntities;
+/**
+ * Generates the guards module directory and files.
+ * Creates scope.guard.ts, guards.module.ts, and index.ts in the guards directory.
+ *
+ * @param rootPath The root path of the generated source (e.g., 'src').
+ * @param entities All entities from the parsed .apsorc.
+ * @returns {Promise<void>} A promise that resolves when the guard files are created.
+ */
+const createGuards = async (rootPath, entities) => {
+    // Only generate guards if there are scoped entities
+    if (!hasScopedEntities(entities)) {
+        console.log('[apso] No scopeBy configurations found, skipping guards generation');
+        return;
+    }
+    const guardsDir = path.join(rootPath, 'guards');
+    // Ensure guards directory exists
+    if (!fs.existsSync(guardsDir)) {
+        fs.mkdirSync(guardsDir, { recursive: true });
+    }
+    const scopedEntities = getScopedEntities(entities);
+    // Common template data
+    const templateData = {
+        scopedEntities,
+        generatedAt: new Date().toISOString(),
+        generatedBy: 'Apso CLI',
+    };
+    // Generate scope.guard.ts
+    const scopeGuardPath = path.join(guardsDir, 'scope.guard.ts');
+    const scopeGuardContent = await Eta.renderFileAsync('./guards/scope.guard', templateData);
+    await (0, file_system_1.createFile)(scopeGuardPath, scopeGuardContent);
+    console.log(`[apso] Generated ${scopeGuardPath}`);
+    // Generate guards.module.ts
+    const guardsModulePath = path.join(guardsDir, 'guards.module.ts');
+    const guardsModuleContent = await Eta.renderFileAsync('./guards/guards.module', templateData);
+    await (0, file_system_1.createFile)(guardsModulePath, guardsModuleContent);
+    console.log(`[apso] Generated ${guardsModulePath}`);
+    // Generate index.ts
+    const indexPath = path.join(guardsDir, 'index.ts');
+    const indexContent = await Eta.renderFileAsync('./guards/index', templateData);
+    await (0, file_system_1.createFile)(indexPath, indexContent);
+    console.log(`[apso] Generated ${indexPath}`);
+    console.log(`[apso] Generated guards for ${scopedEntities.length} scoped entities`);
+};
+exports.createGuards = createGuards;

package/dist/lib/index.d.ts

@@ -8,3 +8,4 @@ export { createIndexAppModule } from "./index-module";
 export { createDto } from "./dto";
 export { createEnums } from "./enums";
 export { createGqlDTO } from "./gql-dto";
+export { createGuards, hasScopedEntities, getScopedEntities } from "./guards";

package/dist/lib/index.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.createGqlDTO = exports.createEnums = exports.createDto = exports.createIndexAppModule = exports.createModule = exports.createService = exports.createController = exports.createEntity = exports.parseApsorc = void 0;
+exports.getScopedEntities = exports.hasScopedEntities = exports.createGuards = exports.createGqlDTO = exports.createEnums = exports.createDto = exports.createIndexAppModule = exports.createModule = exports.createService = exports.createController = exports.createEntity = exports.parseApsorc = void 0;
 var apsorc_parser_1 = require("./apsorc-parser");
 Object.defineProperty(exports, "parseApsorc", { enumerable: true, get: function () { return apsorc_parser_1.parseApsorc; } });
 var entity_1 = require("./entity");
@@ -19,3 +19,7 @@ var enums_1 = require("./enums");
 Object.defineProperty(exports, "createEnums", { enumerable: true, get: function () { return enums_1.createEnums; } });
 var gql_dto_1 = require("./gql-dto");
 Object.defineProperty(exports, "createGqlDTO", { enumerable: true, get: function () { return gql_dto_1.createGqlDTO; } });
+var guards_1 = require("./guards");
+Object.defineProperty(exports, "createGuards", { enumerable: true, get: function () { return guards_1.createGuards; } });
+Object.defineProperty(exports, "hasScopedEntities", { enumerable: true, get: function () { return guards_1.hasScopedEntities; } });
+Object.defineProperty(exports, "getScopedEntities", { enumerable: true, get: function () { return guards_1.getScopedEntities; } });

package/dist/lib/templates/guards/guards.module.eta

@@ -0,0 +1,54 @@
+<%~ includeFile('../header.eta') %>
+
+import { Module, Global } from '@nestjs/common';
+import { TypeOrmModule } from '@nestjs/typeorm';
+import { APP_GUARD } from '@nestjs/core';
+
+import { ScopeGuard } from './scope.guard';
+
+<% /* Import all entities that have scopeBy defined */ %>
+<% it.scopedEntities.forEach((entity) => { %>
+import { <%= entity.name %> } from '../autogen/<%= entity.name %>/<%= entity.name %>.entity';
+<% }) %>
+
+/**
+ * GuardsModule provides scope-based data isolation guards.
+ *
+ * Auto-generated from .apsorc scopeBy definitions.
+ *
+ * Usage:
+ * 1. Import GuardsModule in your AppModule
+ * 2. Guards are NOT enabled globally by default (for backward compatibility)
+ * 3. To enable guards globally, uncomment the APP_GUARD provider below
+ * 4. Or apply guards selectively using @UseGuards(ScopeGuard) on controllers/routes
+ *
+ * When guards are enabled:
+ * - All scoped routes enforce data isolation based on scopeBy config
+ * - POST requests auto-inject scope fields from request context
+ * - GET requests auto-filter by scope fields
+ * - GET/PUT/PATCH/DELETE by ID verify resource ownership
+ *
+ * Decorators:
+ * - @Public() - Skip all guards for a route
+ * - @SkipScopeCheck() - Skip only scope checking
+ */
+@Global()
+@Module({
+  imports: [
+    TypeOrmModule.forFeature([
+<% it.scopedEntities.forEach((entity, index) => { %>
+      <%= entity.name %><%= index < it.scopedEntities.length - 1 ? ',' : '' %>
+<% }) %>
+    ]),
+  ],
+  providers: [
+    ScopeGuard,
+    // UNCOMMENT BELOW TO ENABLE GLOBAL SCOPE ENFORCEMENT
+    // {
+    //   provide: APP_GUARD,
+    //   useClass: ScopeGuard,
+    // },
+  ],
+  exports: [ScopeGuard],
+})
+export class GuardsModule {}

package/dist/lib/templates/guards/index.eta

@@ -0,0 +1,4 @@
+<%~ includeFile('../header.eta') %>
+
+export * from './scope.guard';
+export * from './guards.module';

package/dist/lib/templates/guards/scope.guard.eta

@@ -0,0 +1,319 @@
+<%~ includeFile('../header.eta') %>
+
+import {
+  Injectable,
+  CanActivate,
+  ExecutionContext,
+  ForbiddenException,
+} from '@nestjs/common';
+import { Reflector } from '@nestjs/core';
+import { InjectRepository } from '@nestjs/typeorm';
+import { Repository } from 'typeorm';
+
+<% /* Import all entities that have scoped relationships */ %>
+<% it.scopedEntities.forEach((entity) => { %>
+import { <%= entity.name %> } from '../autogen/<%= entity.name %>/<%= entity.name %>.entity';
+<% }) %>
+
+/**
+ * Decorator to skip scope check for certain routes
+ */
+export const SKIP_SCOPE_CHECK = 'skipScopeCheck';
+export const SkipScopeCheck = () =>
+  (target: any, key?: string, descriptor?: PropertyDescriptor) => {
+    Reflect.defineMetadata(
+      SKIP_SCOPE_CHECK,
+      true,
+      descriptor?.value || target,
+    );
+  };
+
+/**
+ * Decorator to mark routes as public (no auth required)
+ */
+export const IS_PUBLIC_KEY = 'isPublic';
+export const Public = () =>
+  (target: any, key?: string, descriptor?: PropertyDescriptor) => {
+    Reflect.defineMetadata(
+      IS_PUBLIC_KEY,
+      true,
+      descriptor?.value || target,
+    );
+  };
+
+/**
+ * Scope configuration for each entity
+ * Generated from .apsorc scopeBy definitions
+ */
+export interface ScopeConfig {
+  /** The scope fields or paths (e.g., 'workspaceId' or 'task.workspaceId') */
+  scopes: ScopeField[];
+  /** Whether to inject scope on create */
+  injectOnCreate: boolean;
+  /** Which operations to enforce scope on */
+  enforceOn: string[];
+  /** Roles that can bypass scope enforcement */
+  bypassRoles: string[];
+}
+
+export interface ScopeField {
+  /** The field name on the entity (e.g., 'workspaceId') or first segment of path */
+  field: string;
+  /** The context key to get the value from (defaults to field name) */
+  contextKey: string;
+  /** Whether this is a direct field (true) or nested path (false) */
+  direct: boolean;
+  /** For nested paths, the full path (e.g., 'task.workspaceId') */
+  path?: string;
+}
+
+/**
+ * Entity scope configuration map
+ * Auto-generated from .apsorc
+ */
+export const ENTITY_SCOPES: Record<string, ScopeConfig> = {
+<% it.scopedEntities.forEach((entity, index) => { %>
+  '<%= entity.routeName %>': {
+    scopes: [
+<% entity.scopes.forEach((scope, scopeIndex) => { %>
+      {
+        field: '<%= scope.field %>',
+        contextKey: '<%= scope.contextKey %>',
+        direct: <%= scope.direct %>,
+<% if (scope.path) { %>
+        path: '<%= scope.path %>',
+<% } %>
+      }<%= scopeIndex < entity.scopes.length - 1 ? ',' : '' %>
+<% }) %>
+    ],
+    injectOnCreate: <%= entity.injectOnCreate %>,
+    enforceOn: [<%= entity.enforceOn.map(op => `'${op}'`).join(', ') %>],
+    bypassRoles: [<%= entity.bypassRoles.map(role => `'${role}'`).join(', ') %>],
+  }<%= index < it.scopedEntities.length - 1 ? ',' : '' %>
+<% }) %>
+};
+
+@Injectable()
+export class ScopeGuard implements CanActivate {
+  constructor(
+    private reflector: Reflector,
+<% it.scopedEntities.forEach((entity) => { %>
+    @InjectRepository(<%= entity.name %>)
+    private <%= entity.repoName %>: Repository<<%= entity.name %>>,
+<% }) %>
+  ) {}
+
+  async canActivate(context: ExecutionContext): Promise<boolean> {
+    // Check if route should skip scope check
+    const skipCheck = this.reflector.getAllAndOverride<boolean>(
+      SKIP_SCOPE_CHECK,
+      [context.getHandler(), context.getClass()],
+    );
+
+    if (skipCheck) {
+      return true;
+    }
+
+    // Check if route is public
+    const isPublic = this.reflector.getAllAndOverride<boolean>(IS_PUBLIC_KEY, [
+      context.getHandler(),
+      context.getClass(),
+    ]);
+
+    if (isPublic) {
+      return true;
+    }
+
+    const request = context.switchToHttp().getRequest();
+
+    // Get the resource path from the request
+    const path = request.route?.path || request.path;
+    const method = request.method;
+
+    // Extract entity type from path (e.g., /Projects/:id -> projects)
+    const entityMatch = path.match(/^\/([^\/]+)/);
+    if (!entityMatch) {
+      return true;
+    }
+
+    const entityType = entityMatch[1].toLowerCase();
+
+    // Check if this is a scoped entity
+    const scopeConfig = ENTITY_SCOPES[entityType];
+    if (!scopeConfig) {
+      // Not a scoped entity, allow through
+      return true;
+    }
+
+    // Check if user has bypass role
+    const userRoles: string[] = request.user?.roles || request.roles || [];
+    if (scopeConfig.bypassRoles.some(role => userRoles.includes(role))) {
+      return true;
+    }
+
+    // Map HTTP method to operation
+    const operation = this.mapMethodToOperation(method, request.params?.id);
+
+    // Check if this operation should be enforced
+    if (!scopeConfig.enforceOn.includes(operation)) {
+      return true;
+    }
+
+    // For GET requests with an ID, verify the resource belongs to this scope
+    if ((operation === 'get' || operation === 'update' || operation === 'delete') && request.params?.id) {
+      const hasAccess = await this.verifyResourceAccess(
+        entityType,
+        request.params.id,
+        request,
+        scopeConfig,
+      );
+      if (!hasAccess) {
+        throw new ForbiddenException('You do not have access to this resource');
+      }
+    }
+
+    // For POST requests, inject scope values if configured
+    if (operation === 'create' && scopeConfig.injectOnCreate) {
+      this.injectScopeValues(request, scopeConfig);
+    }
+
+    // For GET (list) requests, add scope filter
+    if (operation === 'find') {
+      this.addScopeFilter(request, scopeConfig);
+    }
+
+    return true;
+  }
+
+  private mapMethodToOperation(method: string, hasId: boolean): string {
+    switch (method) {
+      case 'GET':
+        return hasId ? 'get' : 'find';
+      case 'POST':
+        return 'create';
+      case 'PUT':
+      case 'PATCH':
+        return 'update';
+      case 'DELETE':
+        return 'delete';
+      default:
+        return 'find';
+    }
+  }
+
+  private async verifyResourceAccess(
+    entityType: string,
+    resourceId: string,
+    request: any,
+    scopeConfig: ScopeConfig,
+  ): Promise<boolean> {
+    try {
+      const repo = this.getRepository(entityType);
+      if (!repo) {
+        return true; // Unknown entity, allow through
+      }
+
+      // Build relations array for nested scopes
+      const relations: string[] = [];
+      for (const scope of scopeConfig.scopes) {
+        if (!scope.direct && scope.path) {
+          // Extract relation name from path (e.g., 'task.workspaceId' -> 'task')
+          const relationName = scope.path.split('.')[0];
+          if (!relations.includes(relationName)) {
+            relations.push(relationName);
+          }
+        }
+      }
+
+      const entity = await repo.findOne({
+        where: { id: resourceId },
+        relations,
+      });
+
+      if (!entity) {
+        return false;
+      }
+
+      // Verify all scope conditions
+      for (const scope of scopeConfig.scopes) {
+        const expectedValue = this.getScopeValue(request, scope.contextKey);
+        if (!expectedValue) {
+          continue; // No scope value in context, skip this check
+        }
+
+        let actualValue: any;
+        if (scope.direct) {
+          actualValue = (entity as any)[scope.field];
+        } else if (scope.path) {
+          // Navigate the path (e.g., 'task.workspaceId')
+          actualValue = this.getNestedValue(entity, scope.path);
+        }
+
+        if (actualValue !== expectedValue) {
+          return false;
+        }
+      }
+
+      return true;
+    } catch (error) {
+      console.error('Scope verification error:', error);
+      return false;
+    }
+  }
+
+  private injectScopeValues(request: any, scopeConfig: ScopeConfig): void {
+    if (!request.body || typeof request.body !== 'object') {
+      return;
+    }
+
+    for (const scope of scopeConfig.scopes) {
+      if (scope.direct) {
+        const scopeValue = this.getScopeValue(request, scope.contextKey);
+        if (scopeValue && !request.body[scope.field]) {
+          request.body[scope.field] = scopeValue;
+        }
+      }
+    }
+  }
+
+  private addScopeFilter(request: any, scopeConfig: ScopeConfig): void {
+    if (!request.query) {
+      request.query = {};
+    }
+
+    for (const scope of scopeConfig.scopes) {
+      if (scope.direct) {
+        const scopeValue = this.getScopeValue(request, scope.contextKey);
+        if (scopeValue) {
+          // Add filter for @nestjsx/crud
+          request.query[`filter.${scope.field}`] = `$eq:${scopeValue}`;
+        }
+      }
+    }
+  }
+
+  private getScopeValue(request: any, contextKey: string): string | undefined {
+    // Try multiple locations for the scope value
+    return (
+      request[contextKey] ||
+      request.user?.[contextKey] ||
+      request.scope?.[contextKey] ||
+      request.context?.[contextKey]
+    );
+  }
+
+  private getNestedValue(obj: any, path: string): any {
+    return path.split('.').reduce((current, key) => current?.[key], obj);
+  }
+
+  private getRepository(entityType: string): Repository<any> | null {
+    switch (entityType) {
+<% it.scopedEntities.forEach((entity) => { %>
+      case '<%= entity.routeName %>':
+        return this.<%= entity.repoName %>;
+<% }) %>
+      default:
+        return null;
+    }
+  }
+}

package/dist/lib/types/entity.d.ts

@@ -2,6 +2,28 @@ import { Unique } from "./constraints";
 import { Field } from "./field";
 import { Index } from "./indices";
 import { Association } from "./relationship";
+/**
+ * Operations that can have scope enforcement applied
+ */
+export type ScopeOperation = 'find' | 'get' | 'create' | 'update' | 'delete';
+/**
+ * Configuration options for scope enforcement behavior
+ */
+export interface ScopeOptions {
+    /**
+     * If true (default), scope fields are automatically injected from
+     * the request context on create when not provided.
+     */
+    injectOnCreate?: boolean;
+    /**
+     * Which operations should enforce scope. Defaults to all operations.
+     */
+    enforceOn?: ScopeOperation[];
+    /**
+     * Roles allowed to bypass scope enforcement (e.g., 'system_admin').
+     */
+    bypassRoles?: string[];
+}
 export interface Entity {
     name: string;
     created_at?: boolean;
@@ -10,5 +32,18 @@ export interface Entity {
     fields?: Field[];
     indexes?: Index[];
     uniques?: Unique[];
+    /**
+     * Fields or paths that define the authorization scope for this entity.
+     * Can be a single field name (e.g., 'workspaceId') or an array of fields/paths
+     * (e.g., ['workspaceId', 'serviceId'] or ['task.workspaceId']).
+     *
+     * - Direct fields: 'workspaceId' - enforces WHERE workspaceId = ctx.workspaceId
+     * - Nested paths: 'task.workspaceId' - joins to related entity and enforces scope
+     */
+    scopeBy?: string | string[];
+    /**
+     * Optional configuration for how scope enforcement should behave.
+     */
+    scopeOptions?: ScopeOptions;
     associations?: Association[];
 }

package/dist/lib/types/index.d.ts

@@ -1,4 +1,4 @@
-export { Entity } from "./entity";
+export { Entity, ScopeOptions, ScopeOperation } from "./entity";
 export { FieldType, Field, ComputedField } from "./field";
 export { Index } from "./indices";
 export { JSONValue } from "./json";

package/oclif.manifest.json

@@ -1,5 +1,5 @@
 {
-  "version": "0.4.2",
+  "version": "0.5.0",
   "commands": {
     "server:new": {
       "id": "server:new",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@apso/cli",
-  "version": "0.4.2",
+  "version": "0.5.0",
   "description": "Apso CLI",
   "author": "Apso by Mavric - @mavric",
   "bin": {