najm-guard 0.1.1

package/dist/index.d.ts

@@ -0,0 +1,201 @@
+import * as najm_core from 'najm-core';
+import { Constructor } from 'najm-core';
+export { GUARD_CODES, GuardError } from 'najm-core';
+import * as diject from 'diject';
+
+/**
+ * Structured guard result for automatic ALS token setting.
+ * Return this from canActivate() to automatically set tokens.
+ *
+ * @example
+ * ```ts
+ * async canActivate(@Headers('auth') token: string) {
+ *   const user = await this.auth.verify(token);
+ *   if (!user) return false;
+ *   return { user, role: 'admin', permissions: ['read', 'write'] };  // Auto-sets tokens
+ * }
+ * ```
+ */
+interface GuardResult {
+    /** User data → accessible via @User() decorator */
+    user?: any;
+    /** Owner data → accessible via @Owner() decorator */
+    owner?: any;
+    /** Additional info → accessible via @Info() decorator */
+    info?: any;
+    /** Generic data storage → accessible via @Data() decorator */
+    data?: any;
+    /** Filter criteria → accessible via @Filter() decorator */
+    filter?: any;
+    /** User role → accessible via @Role() decorator */
+    role?: string;
+    /** User permissions → accessible via @Permissions() decorator */
+    permissions?: string[];
+}
+/**
+ * Guard method return type
+ * - `false` → Guard failed, request rejected
+ * - `true` → Guard passed, no tokens set
+ * - `GuardResult` → Guard passed, tokens auto-set
+ */
+type GuardReturnType = boolean | GuardResult;
+/**
+ * Guard metadata stored by decorators
+ */
+interface GuardMetadata {
+    guardClass: Constructor;
+    methodName: string;
+    params?: any;
+}
+/**
+ * Plugin configuration
+ */
+type GuardPluginConfig = boolean | {
+    /** Enable/disable guard plugin */
+    enabled?: boolean;
+    /** Paths to exclude from guards (supports wildcards) */
+    exclude?: string[];
+};
+/**
+ * Composite guard params for AND/OR logic
+ */
+interface CompositeGuardParams {
+    type: 'AND' | 'OR';
+    guards: GuardMetadata[];
+}
+/**
+ * Options for createGuard factory
+ */
+interface CreateGuardOptions {
+    methodName?: string;
+}
+
+/**
+ * User data populated by authentication guards
+ * Use generic type to maintain type safety in your app:
+ *
+ * @example
+ * ```ts
+ * // In your app
+ * interface UserData { id: string; roles: string[]; }
+ *
+ * @Service()
+ * class AuthGuard {
+ *    canActivate(@Headers('auth') token: string, @Ctx() ctx: Context): boolean {
+ *       const user = verifyToken(token);
+ *       ctx.set(USER.name, user);  // Populate user context
+ *       return !!user;
+ *    }
+ * }
+ *
+ * // In your controller
+ * @Get('/profile')
+ * getProfile(@User() user: UserData) {  // Type-safe!
+ *    return { id: user.id };
+ * }
+ * ```
+ */
+declare const USER: diject.AlsToken<any>;
+/**
+ * User role populated by authorization guards
+ * Use to get the current user's role
+ *
+ * @example
+ * ```ts
+ * @Get('/admin')
+ * async getAdmin(@Role() role: string) {
+ *    if (role !== 'admin') throw new HttpError(403, 'Forbidden');
+ *    return { data: 'admin-only' };
+ * }
+ * ```
+ */
+declare const ROLE: diject.AlsToken<string>;
+/**
+ * User permissions populated by authorization guards
+ * Use to get the current user's permissions
+ *
+ * @example
+ * ```ts
+ * @Get('/edit/:id')
+ * async editResource(
+ *    @Params('id') id: string,
+ *    @Permissions() permissions: string[]
+ * ) {
+ *    if (!permissions.includes('edit:resource')) {
+ *       throw new HttpError(403, 'Forbidden');
+ *    }
+ *    return { id };
+ * }
+ * ```
+ */
+declare const PERMISSIONS: diject.AlsToken<string[]>;
+/**
+ * Resource owner data (for ownership-based guards)
+ */
+declare const OWNER: diject.AlsToken<any>;
+/**
+ * Additional info populated by guards
+ */
+declare const INFO: diject.AlsToken<any>;
+/**
+ * Generic data storage for guards
+ */
+declare const DATA: diject.AlsToken<any>;
+/**
+ * Filter criteria (for query/permission filtering)
+ */
+declare const FILTER: diject.AlsToken<any>;
+/**
+ * Guard parameters passed to guard decorators
+ * This is populated automatically by the guard system
+ */
+declare const GUARD_PARAMS: diject.AlsToken<any>;
+/**
+ * Metadata key for guards applied to class/method
+ */
+declare const GUARDS_META: unique symbol;
+/**
+ * Plugin config token
+ */
+declare const GUARD_CONFIG: unique symbol;
+
+declare function createGuard<TParams = void>(guardClass: Constructor, options?: CreateGuardOptions): TParams extends void ? () => ClassDecorator & MethodDecorator : (params: TParams) => ClassDecorator & MethodDecorator;
+/**
+ * Compose multiple guard decorators to run sequentially.
+ * All guards must pass for access to be granted.
+ *
+ * @example
+ * export const isAdmin = composeGuards(isAuth(), Role(ROLES.ADMIN));
+ *
+ * @usage
+ * @isAdmin()  // Note: called as a function
+ * method() { ... }
+ */
+declare function composeGuards(...decorators: (ClassDecorator & MethodDecorator)[]): () => ClassDecorator & MethodDecorator;
+declare function getGuardMetadata(target: any, methodName?: string): GuardMetadata[];
+declare function hasGuards(target: any, methodName?: string): boolean;
+
+declare const guards: (config?: GuardPluginConfig) => najm_core.NajmPlugin;
+declare const GuardPlugin: (config?: GuardPluginConfig) => najm_core.NajmPlugin;
+
+declare class GuardService {
+    private container;
+    private scanner;
+    private config;
+    private log;
+    private guardCount;
+    private resolver;
+    private enabled;
+    private excludePaths;
+    onInit(): void;
+    scan(): Promise<void>;
+    configure(): Promise<void>;
+    activate(): Promise<void>;
+    onReady(): Promise<void>;
+    private createGuardsMiddleware;
+    private isPathExcluded;
+    private executeGuard;
+    private processGuardResult;
+}
+
+export { type CompositeGuardParams, type CreateGuardOptions, DATA, FILTER, GUARDS_META, GUARD_CONFIG, GUARD_PARAMS, type GuardMetadata, GuardPlugin, type GuardPluginConfig, type GuardResult, type GuardReturnType, GuardService, INFO, OWNER, PERMISSIONS, ROLE, USER, composeGuards, createGuard, getGuardMetadata, guards, hasGuards };

package/dist/index.mjs

@@ -0,0 +1,277 @@
+var __defProp = Object.defineProperty;
+var __name = (target, value) => __defProp(target, "name", { value, configurable: true });
+
+// src/tokens.ts
+import { createAlsToken } from "najm-core";
+var USER = createAlsToken("user");
+var ROLE = createAlsToken("role");
+var PERMISSIONS = createAlsToken("permissions");
+var OWNER = createAlsToken("owner");
+var INFO = createAlsToken("info");
+var DATA = createAlsToken("data");
+var FILTER = createAlsToken("filter");
+var GUARD_PARAMS = createAlsToken("guardParams");
+var GUARDS_META = /* @__PURE__ */ Symbol("guards:meta");
+var GUARD_CONFIG = /* @__PURE__ */ Symbol("GUARD_CONFIG");
+
+// src/decorator.ts
+import { MetaHelper } from "najm-core";
+function createGuard(guardClass, options) {
+  const methodName = options?.methodName ?? "canActivate";
+  return ((params) => {
+    return function(target, propertyKey) {
+      const metadata = {
+        guardClass,
+        methodName,
+        params
+      };
+      if (propertyKey) {
+        MetaHelper.appendMany(GUARDS_META, [metadata], target, propertyKey);
+      } else {
+        MetaHelper.appendMany(GUARDS_META, [metadata], target);
+      }
+    };
+  });
+}
+__name(createGuard, "createGuard");
+function composeGuards(...decorators) {
+  return () => {
+    return function(target, propertyKey, descriptor) {
+      for (const decoratorFn of decorators) {
+        if (propertyKey !== void 0) {
+          decoratorFn(target, propertyKey, descriptor);
+        } else {
+          decoratorFn(target);
+        }
+      }
+    };
+  };
+}
+__name(composeGuards, "composeGuards");
+function getGuardMetadata(target, methodName) {
+  if (methodName) {
+    return MetaHelper.get(GUARDS_META, target.prototype, methodName) || [];
+  }
+  return MetaHelper.get(GUARDS_META, target) || [];
+}
+__name(getGuardMetadata, "getGuardMetadata");
+function hasGuards(target, methodName) {
+  return getGuardMetadata(target, methodName).length > 0;
+}
+__name(hasGuards, "hasGuards");
+
+// src/GuardPlugin.ts
+import { plugin } from "najm-core";
+
+// src/GuardService.ts
+import { Service, Meta, DI, Container, Inject } from "najm-core";
+import { ScannerService, Scan, ScanType, INJECTION_TYPES, Err, LOGGER } from "najm-core";
+import { ParamResolver } from "najm-core";
+var __decorate = 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 __metadata = function(k, v) {
+  if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
+var _a;
+var _b;
+var GuardService = class GuardService2 {
+  static {
+    __name(this, "GuardService");
+  }
+  container;
+  scanner;
+  config;
+  log;
+  guardCount = 0;
+  resolver;
+  enabled = true;
+  excludePaths = [];
+  // ============================================================================
+  // LIFECYCLE: SCAN
+  // ============================================================================
+  onInit() {
+    this.enabled = typeof this.config === "boolean" ? this.config : this.config.enabled ?? true;
+    this.excludePaths = typeof this.config === "object" ? this.config.exclude || [] : [];
+    this.guardCount = 0;
+  }
+  async scan() {
+    if (!this.enabled)
+      return;
+    this.scanner.scan(ScanType.CONTROLLER, {
+      onClass: /* @__PURE__ */ __name((controller) => {
+        const guards2 = getGuardMetadata(controller);
+        if (guards2?.length) {
+          this.container.setInjection({
+            type: INJECTION_TYPES.MIDDLEWARE,
+            target: controller,
+            handler: this.createGuardsMiddleware(guards2),
+            order: 50,
+            source: "guard"
+          });
+          this.guardCount += guards2.length;
+        }
+      }, "onClass"),
+      onMethod: /* @__PURE__ */ __name((controller, methodName) => {
+        const guards2 = getGuardMetadata(controller, methodName);
+        if (guards2?.length) {
+          this.container.setInjection({
+            type: INJECTION_TYPES.MIDDLEWARE,
+            target: controller,
+            methodName,
+            handler: this.createGuardsMiddleware(guards2),
+            order: 50,
+            source: "guard"
+          });
+          this.guardCount += guards2.length;
+        }
+      }, "onMethod")
+    });
+  }
+  // ============================================================================
+  // LIFECYCLE: CONFIGURE, ACTIVATE, READY
+  // ============================================================================
+  async configure() {
+    if (!this.enabled)
+      return;
+    this.resolver = new ParamResolver(this.container);
+  }
+  async activate() {
+  }
+  async onReady() {
+    if (!this.enabled) {
+      this.log.info("Guard plugin disabled");
+      return;
+    }
+    this.log.info(`Guard plugin ready: ${this.guardCount} guard(s) registered`);
+  }
+  // ============================================================================
+  // MIDDLEWARE
+  // ============================================================================
+  createGuardsMiddleware(guards2) {
+    return async (context, next) => {
+      const path = context.req.path;
+      if (this.isPathExcluded(path)) {
+        return next();
+      }
+      try {
+        for (const guard of guards2) {
+          const canActivate = await this.executeGuard(guard);
+          if (!canActivate) {
+            throw Err.unauthorized();
+          }
+        }
+        await next();
+      } catch (error) {
+        return Err.handle(error);
+      }
+    };
+  }
+  // ============================================================================
+  // PATH EXCLUSION
+  // ============================================================================
+  isPathExcluded(path) {
+    return this.excludePaths.some((pattern) => {
+      if (pattern === path)
+        return true;
+      if (pattern.endsWith("/*")) {
+        const prefix = pattern.slice(0, -2);
+        return path.startsWith(prefix);
+      }
+      if (pattern.endsWith("/**")) {
+        const prefix = pattern.slice(0, -3);
+        return path.startsWith(prefix);
+      }
+      return false;
+    });
+  }
+  // ============================================================================
+  // GUARD EXECUTION (unchanged)
+  // ============================================================================
+  async executeGuard(guard) {
+    const { guardClass, methodName = "canActivate", params } = guard;
+    const instance = await this.container.resolve(guardClass);
+    const method = instance[methodName];
+    const result = await this.container.run({ guardParams: params }, async () => {
+      const args = await this.resolver.resolveArgs(method);
+      return method.call(instance, ...args);
+    });
+    return this.processGuardResult(result);
+  }
+  processGuardResult(result) {
+    if (typeof result === "boolean")
+      return result;
+    if (result == null)
+      return false;
+    if (typeof result === "object") {
+      const { user, owner, info, data, filter, role, permissions } = result;
+      if (user !== void 0)
+        this.container.set(USER, user);
+      if (owner !== void 0)
+        this.container.set(OWNER, owner);
+      if (info !== void 0)
+        this.container.set(INFO, info);
+      if (data !== void 0)
+        this.container.set(DATA, data);
+      if (filter !== void 0)
+        this.container.set(FILTER, filter);
+      if (role !== void 0)
+        this.container.set(ROLE, role);
+      if (permissions !== void 0)
+        this.container.set(PERMISSIONS, permissions);
+      return true;
+    }
+    return false;
+  }
+};
+__decorate([
+  DI(),
+  __metadata("design:type", typeof (_a = typeof Container !== "undefined" && Container) === "function" ? _a : Object)
+], GuardService.prototype, "container", void 0);
+__decorate([
+  Scan(),
+  __metadata("design:type", typeof (_b = typeof ScannerService !== "undefined" && ScannerService) === "function" ? _b : Object)
+], GuardService.prototype, "scanner", void 0);
+__decorate([
+  Inject(GUARD_CONFIG),
+  __metadata("design:type", Object)
+], GuardService.prototype, "config", void 0);
+__decorate([
+  Inject(LOGGER),
+  __metadata("design:type", Object)
+], GuardService.prototype, "log", void 0);
+GuardService = __decorate([
+  Service(),
+  Meta({ layer: "plugin" })
+], GuardService);
+
+// src/GuardPlugin.ts
+var guards = /* @__PURE__ */ __name((config = true) => plugin("guards").services(GuardService).config(GUARD_CONFIG, config).build(), "guards");
+var GuardPlugin = guards;
+
+// src/index.ts
+import { GuardError, GUARD_CODES } from "najm-core";
+export {
+  DATA,
+  FILTER,
+  GUARDS_META,
+  GUARD_CODES,
+  GUARD_CONFIG,
+  GUARD_PARAMS,
+  GuardError,
+  GuardPlugin,
+  GuardService,
+  INFO,
+  OWNER,
+  PERMISSIONS,
+  ROLE,
+  USER,
+  composeGuards,
+  createGuard,
+  getGuardMetadata,
+  guards,
+  hasGuards
+};

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "najm-guard",
+  "version": "0.1.1",
+  "type": "module",
+  "files": [
+    "dist"
+  ],
+  "main": "./dist/index.mjs",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "bun": "./src/index.ts",
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs",
+      "default": "./dist/index.mjs"
+    },
+    "./*": {
+      "bun": "./src/*.ts",
+      "types": "./src/*.ts",
+      "import": "./src/*.ts",
+      "default": "./src/*.ts"
+    }
+  },
+  "scripts": {
+    "build": "tsup",
+    "test": "bun test",
+    "test:watch": "bun test --watch",
+    "clean": "rimraf dist tsconfig.tsbuildinfo"
+  },
+  "dependencies": {
+    "najm-core": "^0.1.1"
+  },
+  "peerDependencies": {
+    "hono": "^4.0.0"
+  },
+  "devDependencies": {
+    "typescript": "^5.7.3",
+    "rimraf": "^6.0.1"
+  }
+}