najm-auth 1.1.3 → 1.1.4

package/dist/index.d.ts

@@ -1294,97 +1294,126 @@ interface ResourceGuards {
  */
 declare function createResourceGuards<T extends new (...args: any[]) => OwnershipProvider>(ownershipClass: T, resourceType: string, resource: string, options?: ResourceGuardsOptions): ResourceGuards;
 
-/**
- * A resolver function that returns accessible IDs for a given userId.
- */
 type OwnershipResolver = (userId: string) => Promise<string[]>;
-/**
- * Rules map: role → resource → resolver function.
- *
- * @example
- * ```ts
- * {
- *   teacher: {
- *     student: (uid) => db.select(...).from(teachers).where(eq(teachers.userId, uid)).then(r => r.map(x => x.id)),
- *     class:   (uid) => db.select(...).from(classes).where(...).then(r => r.map(x => x.id)),
- *   },
- *   parent: {
- *     student: (uid) => ...,
- *   },
- * }
- * ```
- */
 type OwnershipRules = Record<string, Record<string, OwnershipResolver>>;
 interface OwnershipConfig {
     /** Roles that bypass ownership and can access everything */
     adminRoles: string[];
+    /**
+     * Default write guard applied to create/delete across all resources.
+     * Can be overridden per-resource in `guards()` or `for()`.
+     * Defaults to `isAdmin` if not provided.
+     *
+     * @example
+     * adminGuard: isAdministrator  // set once, applies everywhere
+     */
+    adminGuard?: () => ClassDecorator & MethodDecorator;
     /** Resolution rules: role → resource → resolver */
     rules: OwnershipRules;
     /** Cache TTL in ms (default: 60000) */
     cacheTtl?: number;
 }
+/**
+ * A guard factory that is also chainable.
+ * Call it as `@canCreateExam` (decorator) or chain `.body()` / `.and()` before use.
+ *
+ * @example
+ * ```ts
+ * const g = ownership.for('exams');
+ *
+ * export const canAccessExam = g.read;
+ * export const canCreateExam = g.create.body('section', 'sectionId');
+ * export const canCreateEvent = g.create
+ *   .body('class',   'classId',   true)
+ *   .body('section', 'sectionId', true);
+ * ```
+ */
+type ChainableGuard = {
+    (): ClassDecorator & MethodDecorator;
+    /**
+     * Add an ownership check on a body field.
+     * @param type     - singular resource type (e.g. 'section')
+     * @param field    - body field name (e.g. 'sectionId')
+     * @param optional - if true, missing field passes (default: false)
+     */
+    body(type: string, field: string, optional?: boolean): ChainableGuard;
+    /**
+     * Add any custom guard decorator into the chain.
+     */
+    and(guard: () => ClassDecorator & MethodDecorator): ChainableGuard;
+};
+/**
+ * Fluent resource accessor returned by `ownership.for(resource)`.
+ * Each property is a `ChainableGuard` for that CRUD action.
+ */
+interface ResourceAccessor {
+    /** Read single resource — checks :id param ownership */
+    readonly read: ChainableGuard;
+    /** Update single resource — checks :id param ownership */
+    readonly update: ChainableGuard;
+    /** Create resource — admin-only by default, chain `.body()` for extra checks */
+    readonly create: ChainableGuard;
+    /** Delete resource — admin-only by default */
+    readonly delete: ChainableGuard;
+    /** List resources — sets @Filter() ALS token for scoped queries */
+    readonly list: ChainableGuard;
+}
 interface ConfiguredOwnership {
     /** The generated OwnershipService class — register this with your DI container */
     Service: new (...args: any[]) => OwnershipProvider & {
         clearCache(userId?: string): void;
     };
     /**
-     * Generate CRUD guards for a resource.
+     * Fluent resource accessor. Each property is a `ChainableGuard`.
+     * Chain `.body(type, field)` on `create`/`update` for additional body checks.
      *
-     * @param resource - plural resource name (e.g. 'teachers')
-     *   The singular form is auto-inferred for ownership lookups.
+     * @example
+     * ```ts
+     * const g = ownership.for('exams');
+     *
+     * export const canAccessExam     = g.read;
+     * export const canUpdateExam     = g.update;
+     * export const canCreateExam     = g.create.body('section', 'sectionId');
+     * export const canDeleteExam     = g.delete;
+     * export const canAccessAllExams = g.list;
+     * ```
+     */
+    for(resource: string, options?: ResourceGuardsOptions): ResourceAccessor;
+    /**
+     * Generate CRUD guards for a resource (destructuring style).
+     * Prefer `for()` for new code — this is kept for backward compatibility.
      *
      * @example
      * ```ts
      * export const {
      *   canRead: canAccessTeacher,
-     *   canUpdate: canUpdateTeacher,
-     *   canCreate: canCreateTeacher,
-     *   canDelete: canDeleteTeacher,
      *   canList: canAccessAllTeachers,
      * } = ownership.guards('teachers');
      * ```
      */
     guards(resource: string, options?: ResourceGuardsOptions): ResourceGuards;
+    /**
+     * Create a standalone body-field ownership guard.
+     * Prefer chaining `.body()` on `ownership.for()` — this is kept for manual composition.
+     */
+    bodyGuard(resourceType: string, bodyField: string, optional?: boolean): () => ClassDecorator & MethodDecorator;
 }
 /**
  * Configure ownership for your entire app in one place.
  *
- * Returns a `Service` class (for DI) and a `guards()` helper
- * that replaces per-module boilerplate.
- *
  * @example
  * ```ts
  * // ownership.ts
- * import { configureOwnership } from 'najm-auth';
- * import { db } from './database/db';
- * import { eq } from 'drizzle-orm';
- * import { students, teachers, parents } from './database/schema';
- *
  * export const ownership = configureOwnership({
  *   adminRoles: ['admin', 'principal'],
- *   rules: {
- *     student: {
- *       student: async (uid) => {
- *         const rows = await db.select({ id: students.id }).from(students).where(eq(students.userId, uid));
- *         return rows.map(r => r.id);
- *       },
- *     },
- *     teacher: {
- *       student: async (uid) => {
- *         const rows = await db.select({ id: students.id })
- *           .from(teachers)
- *           .innerJoin(teacherAssignments, eq(teachers.id, teacherAssignments.teacherId))
- *           .innerJoin(students, eq(teacherAssignments.sectionId, students.sectionId))
- *           .where(eq(teachers.userId, uid));
- *         return rows.map(r => r.id);
- *       },
- *     },
- *   },
+ *   adminGuard: isAdministrator,       // ← set once, no need to repeat
+ *   rules: { teacher: { student: ... }, parent: { student: ... } },
  * });
  *
- * // TeacherGuards.ts — one line
- * export const { canRead: canAccessTeacher, ... } = ownership.guards('teachers');
+ * // ExamGuards.ts
+ * const g = ownership.for('exams');
+ * export const canAccessExam = g.read;
+ * export const canCreateExam = g.create.body('section', 'sectionId');
  * ```
  */
 declare function configureOwnership(config: OwnershipConfig): ConfiguredOwnership;
@@ -1633,4 +1662,4 @@ declare const authSeed: (config: AuthSeedConfig) => Record<string, SeedEntry>;
  */
 declare function seedAuthData(config: SeedAuthDataConfig): Promise<SeedAuthDataResult>;
 
-export { AUTH_CONFIG, en as AUTH_EN, AUTH_LOCALES, AUTH_MODULE, AUTH_PERMISSIONS, AUTH_ROLE, AUTH_SCHEMA, AUTH_SUPPORTED_LANGUAGES, AUTH_USER, type AssignPermissionDto, type AssignRoleDto, type AssignRoleParams, type AuthConfig, AuthController, AuthGuard, type AuthPluginConfig, AuthQueries, type AuthSchema, type AuthSeedConfig, AuthService, type AuthUser, Can, type ChangePasswordDto, type CheckPermissionDto, type ConfiguredOwnership, type ConfirmResetPasswordDto, CookieManager, type CreatePermissionDto, type CreateRoleDto, type CreateTokenDto, type CreateUserDto, type EmailParam, EncryptionService, type JwtConfig, type JwtPayload, type LanguageParam, type LoginDto, NewPermission, NewRoleEntity, NewUser, type OwnershipConfig, type OwnershipProvider, type OwnershipResolver, type OwnershipRules, Permission, PermissionController, PermissionGuard, type PermissionIdParam, PermissionRepository, PermissionService, PermissionValidator, ROLES, ROLE_GROUPS, type RefreshTokenDto, type ResetPasswordDto, type ResourceGuards, type ResourceGuardsOptions, type RevokeTokenDto, Role, RoleController, RoleEntity, RoleGuard, type RoleIdParam, type RoleInput, RolePermission, RoleRepository, RoleService, type RoleType, RoleValidator, type SanitizedUser, type SeedAuthDataConfig, type SeedAuthDataResult, type SeedUserConfig, TOKEN_STATUS, TOKEN_TYPE, type TokenIdParam, type TokenPair, TokenRepository, TokenService, USER_STATUS, type UpdatePermissionDto, type UpdateRoleDto, type UpdateTokenDto, type UpdateUserDto, User, UserController, type UserIdInParam, type UserIdParam, UserRepository, UserService, UserValidator, type UserWithPermissions, type VerifyTokenDto, assignPermissionDto, assignRoleDto, assignRoleParams, auth$1 as auth, authSeed, avatarsPath, calculateAge, calculateYearsOfExperience, canCreate, canDelete, canManage, canRead, canUpdate, changePasswordDto, checkPermissionDto, clean, configureOwnership, confirmResetPasswordDto, createPermissionDto, createResourceGuards, createRoleDto, createTokenDto, createUserDto, defineRoles, emailParam, formatDate, getAuthLocale, getAvatarFile, isAdmin, isAdministrator, isAuth, isEmpty, isFile, isPath, languageParam, loginDto, parseSchema, permissionIdParam, pickProps, refreshTokenDto, resetPasswordDto, revokeTokenDto, roleIdParam, seedAuthData, tokenIdParam, updatePermissionDto, updateRoleDto, updateTokenDto, updateUserDto, userIdInParam, userIdParam, verifyTokenDto };
+export { AUTH_CONFIG, en as AUTH_EN, AUTH_LOCALES, AUTH_MODULE, AUTH_PERMISSIONS, AUTH_ROLE, AUTH_SCHEMA, AUTH_SUPPORTED_LANGUAGES, AUTH_USER, type AssignPermissionDto, type AssignRoleDto, type AssignRoleParams, type AuthConfig, AuthController, AuthGuard, type AuthPluginConfig, AuthQueries, type AuthSchema, type AuthSeedConfig, AuthService, type AuthUser, Can, type ChainableGuard, type ChangePasswordDto, type CheckPermissionDto, type ConfiguredOwnership, type ConfirmResetPasswordDto, CookieManager, type CreatePermissionDto, type CreateRoleDto, type CreateTokenDto, type CreateUserDto, type EmailParam, EncryptionService, type JwtConfig, type JwtPayload, type LanguageParam, type LoginDto, NewPermission, NewRoleEntity, NewUser, type OwnershipConfig, type OwnershipProvider, type OwnershipResolver, type OwnershipRules, Permission, PermissionController, PermissionGuard, type PermissionIdParam, PermissionRepository, PermissionService, PermissionValidator, ROLES, ROLE_GROUPS, type RefreshTokenDto, type ResetPasswordDto, type ResourceAccessor, type ResourceGuards, type ResourceGuardsOptions, type RevokeTokenDto, Role, RoleController, RoleEntity, RoleGuard, type RoleIdParam, type RoleInput, RolePermission, RoleRepository, RoleService, type RoleType, RoleValidator, type SanitizedUser, type SeedAuthDataConfig, type SeedAuthDataResult, type SeedUserConfig, TOKEN_STATUS, TOKEN_TYPE, type TokenIdParam, type TokenPair, TokenRepository, TokenService, USER_STATUS, type UpdatePermissionDto, type UpdateRoleDto, type UpdateTokenDto, type UpdateUserDto, User, UserController, type UserIdInParam, type UserIdParam, UserRepository, UserService, UserValidator, type UserWithPermissions, type VerifyTokenDto, assignPermissionDto, assignRoleDto, assignRoleParams, auth$1 as auth, authSeed, avatarsPath, calculateAge, calculateYearsOfExperience, canCreate, canDelete, canManage, canRead, canUpdate, changePasswordDto, checkPermissionDto, clean, configureOwnership, confirmResetPasswordDto, createPermissionDto, createResourceGuards, createRoleDto, createTokenDto, createUserDto, defineRoles, emailParam, formatDate, getAuthLocale, getAvatarFile, isAdmin, isAdministrator, isAuth, isEmpty, isFile, isPath, languageParam, loginDto, parseSchema, permissionIdParam, pickProps, refreshTokenDto, resetPasswordDto, revokeTokenDto, roleIdParam, seedAuthData, tokenIdParam, updatePermissionDto, updateRoleDto, updateTokenDto, updateUserDto, userIdInParam, userIdParam, verifyTokenDto };

package/dist/index.js

@@ -3093,13 +3093,22 @@ function createResourceGuards(ownershipClass, resourceType, resource, options) {
 __name(createResourceGuards, "createResourceGuards");
 
 // src/ownership/configureOwnership.ts
-import { Injectable as Injectable12 } from "najm-core";
+import { Injectable as Injectable12, Inject as Inject10, User as User5, Body as Body5 } from "najm-core";
+import { createGuard as createGuard6, composeGuards as composeGuards5 } from "najm-guard";
 var __decorate23 = function(decorators, target, key, desc) {
   var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
   if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
   else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
   return c > 3 && r && Object.defineProperty(target, key, r), r;
 };
+var __metadata23 = function(k, v) {
+  if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
+var __param10 = function(paramIndex, decorator) {
+  return function(target, key) {
+    decorator(target, key, paramIndex);
+  };
+};
 function toSingular(plural) {
   if (plural.endsWith("ies"))
     return plural.slice(0, -3) + "y";
@@ -3112,7 +3121,7 @@ function toSingular(plural) {
 }
 __name(toSingular, "toSingular");
 function configureOwnership(config) {
-  const { adminRoles, rules, cacheTtl = 6e4 } = config;
+  const { adminRoles, rules, cacheTtl = 6e4, adminGuard: defaultAdminGuard = isAdmin } = config;
   let GeneratedOwnershipService = class GeneratedOwnershipService {
     static {
       __name(this, "GeneratedOwnershipService");
@@ -3163,14 +3172,79 @@ function configureOwnership(config) {
   GeneratedOwnershipService = __decorate23([
     Injectable12()
   ], GeneratedOwnershipService);
+  function bodyGuard(resourceType, bodyField, optional = false) {
+    var _a15;
+    let BodyAccessGuard = class BodyAccessGuard {
+      static {
+        __name(this, "BodyAccessGuard");
+      }
+      ownership;
+      async canActivate(user, body) {
+        const id = body[bodyField];
+        if (!id)
+          return optional;
+        return this.ownership.canAccess(user, resourceType, id);
+      }
+    };
+    __decorate23([
+      Inject10(GeneratedOwnershipService),
+      __metadata23("design:type", GeneratedOwnershipService)
+    ], BodyAccessGuard.prototype, "ownership", void 0);
+    __decorate23([
+      __param10(0, User5()),
+      __param10(1, Body5()),
+      __metadata23("design:type", Function),
+      __metadata23("design:paramtypes", [Object, Object]),
+      __metadata23("design:returntype", typeof (_a15 = typeof Promise !== "undefined" && Promise) === "function" ? _a15 : Object)
+    ], BodyAccessGuard.prototype, "canActivate", null);
+    BodyAccessGuard = __decorate23([
+      Injectable12()
+    ], BodyAccessGuard);
+    return createGuard6(BodyAccessGuard);
+  }
+  __name(bodyGuard, "bodyGuard");
+  function makeChainable(decorators) {
+    return Object.assign(() => composeGuards5(...decorators)(), {
+      body(type, field, optional = false) {
+        return makeChainable([...decorators, bodyGuard(type, field, optional)()]);
+      },
+      and(guard) {
+        return makeChainable([...decorators, guard()]);
+      }
+    });
+  }
+  __name(makeChainable, "makeChainable");
   function guards2(resource, options) {
-    const resourceType = toSingular(resource);
-    return createResourceGuards(GeneratedOwnershipService, resourceType, resource, options);
+    const merged = { adminGuard: defaultAdminGuard, ...options };
+    return createResourceGuards(GeneratedOwnershipService, toSingular(resource), resource, merged);
   }
   __name(guards2, "guards");
+  function for_(resource, options) {
+    const base = guards2(resource, options);
+    return {
+      get read() {
+        return makeChainable([base.canRead()]);
+      },
+      get update() {
+        return makeChainable([base.canUpdate()]);
+      },
+      get create() {
+        return makeChainable([base.canCreate()]);
+      },
+      get delete() {
+        return makeChainable([base.canDelete()]);
+      },
+      get list() {
+        return makeChainable([base.canList()]);
+      }
+    };
+  }
+  __name(for_, "for_");
   return {
     Service: GeneratedOwnershipService,
-    guards: guards2
+    for: for_,
+    guards: guards2,
+    bodyGuard
   };
 }
 __name(configureOwnership, "configureOwnership");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "najm-auth",
-  "version": "1.1.3",
+  "version": "1.1.4",
   "description": "Authentication and authorization library for najm framework",
   "type": "module",
   "files": [
@@ -62,15 +62,15 @@
     "typescript": "^5.9.3"
   },
   "dependencies": {
-    "najm-cookies": "^1.1.1",
-    "najm-core": "^1.1.1",
-    "najm-database": "^1.1.2",
-    "najm-guard": "^1.1.1",
-    "najm-i18n": "^1.1.1",
-    "najm-cache": "^1.1.1",
-    "najm-email": "^1.1.1",
-    "najm-rate": "^1.1.1",
-    "najm-validation": "^1.1.1",
+    "najm-cookies": "workspace:*",
+    "najm-core": "workspace:*",
+    "najm-database": "workspace:*",
+    "najm-guard": "workspace:*",
+    "najm-i18n": "workspace:*",
+    "najm-cache": "workspace:*",
+    "najm-email": "workspace:*",
+    "najm-rate": "workspace:*",
+    "najm-validation": "workspace:*",
     "bcryptjs": "^3.0.3",
     "hono": "^4.0.0",
     "jsonwebtoken": "^9.0.3",