@ahmed109/gatekeeper-express 0.0.0-stage → 0.3.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ahmed Tamer
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,92 @@
-# Temporary Holding Version
+# @ahmed109/gatekeeper-express
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+> Express middleware for authorization and feature flags with customizable callbacks.
+
+Part of the **Gatekeeper** toolkit. Built on top of [`@ahmed109/gatekeeper-core`](https://www.npmjs.com/package/@ahmed109/gatekeeper-core).
+
+## Installation
+
+```bash
+npm install @ahmed109/gatekeeper-express @ahmed109/gatekeeper-core
+# or
+pnpm add @ahmed109/gatekeeper-express @ahmed109/gatekeeper-core
+```
+
+### Peer Dependencies
+
+- `express`: `>=4.18.0`
+
+## Features
+
+- **Route Guards**: `requirePermission()`, `requireAnyPermission()`, and `requireFeatureFlag()`.
+- **Customizable Auth Callbacks**: Route-level and global `onUnauthorized(req, res)` and `onForbidden(req, res, missing)`.
+- **Safe Fallbacks**: Returns standard JSON 401/403 responses if custom callbacks are not supplied.
+- **Request Augmentation**: Safely types `req.user`, `req.gatekeeperFlags`, and `req.can(perm)`.
+
+## Quickstart
+
+```typescript
+import express from 'express';
+import {
+  gatekeeperMiddleware,
+  requirePermission,
+  requireFeatureFlag,
+} from '@ahmed109/gatekeeper-express';
+
+const app = express();
+app.use(express.json());
+
+// Attach authenticated user and active flags in upstream middleware
+app.use((req, _res, next) => {
+  req.user = {
+    id: 'usr_123',
+    name: 'Bob Manager',
+    role: 'manager',
+    permissions: [],
+  };
+  req.gatekeeperFlags = {
+    'export-reports': true,
+  };
+  next();
+});
+
+// Mount Gatekeeper helper middleware
+app.use(gatekeeperMiddleware());
+
+// Protected route: requires 'reports.view' permission
+app.get('/api/reports', requirePermission('reports.view'), (req, res) => {
+  res.json({ reports: [] });
+});
+
+// Protected route: requires permission AND active feature flag
+app.get(
+  '/api/reports/export',
+  requirePermission('reports.view'),
+  requireFeatureFlag('export-reports'),
+  (req, res) => {
+    res.send('id,title,date\n1,Audit,2026-10-17');
+  },
+);
+
+// Custom forbidden handler
+app.post(
+  '/api/admin/action',
+  requirePermission('settings.manage', {
+    onForbidden: (req, res, missing) => {
+      res.status(403).json({
+        customError: 'FORBIDDEN_CUSTOM',
+        missingPermissions: missing,
+      });
+    },
+  }),
+  (req, res) => {
+    res.json({ success: true });
+  },
+);
+
+app.listen(3001);
+```
+
+## License
+
+MIT © [Ahmed Tamer](https://github.com/Ahmed1092002)

package/dist/index.cjs

@@ -0,0 +1,147 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  FORBIDDEN_PAYLOAD: () => FORBIDDEN_PAYLOAD,
+  UNAUTHORIZED_PAYLOAD: () => UNAUTHORIZED_PAYLOAD,
+  gatekeeperMiddleware: () => gatekeeperMiddleware,
+  requireAnyPermission: () => requireAnyPermission,
+  requireFeatureFlag: () => requireFeatureFlag,
+  requirePermission: () => requirePermission
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/middleware.ts
+var import_gatekeeper_core = require("@ahmed109/gatekeeper-core");
+var UNAUTHORIZED_PAYLOAD = {
+  error: "UNAUTHORIZED",
+  message: "Authentication required."
+};
+var FORBIDDEN_PAYLOAD = {
+  error: "FORBIDDEN",
+  message: "You do not have permission to perform this action."
+};
+function gatekeeperMiddleware(options = {}) {
+  return (req, _res, next) => {
+    req.gatekeeperOptions = options;
+    const extractor = options.getSubject ?? options.getUser;
+    const subject = extractor ? extractor(req) : req.subject ?? req.user;
+    if (subject) {
+      if (!req.user) req.user = subject;
+      if (!req.subject) req.subject = subject;
+    }
+    if (options.getFlags && !req.gatekeeperFlags) {
+      req.gatekeeperFlags = options.getFlags(req);
+    }
+    req.can = (permission, canOptions) => {
+      const activeUser = extractor ? extractor(req) : req.subject ?? req.user;
+      const resolvedContext = canOptions?.context ?? options.context ?? (options.getContext ? options.getContext(req) : void 0);
+      return (0, import_gatekeeper_core.can)(activeUser, permission, {
+        roleMap: canOptions?.roleMap ?? options.roleMap,
+        policy: canOptions?.policy ?? options.policy,
+        context: resolvedContext
+      });
+    };
+    next();
+  };
+}
+function requirePermission(permission, options = {}) {
+  return async (req, res, next) => {
+    const userExtractor = options.getSubject ?? options.getUser ?? req.gatekeeperOptions?.getSubject ?? req.gatekeeperOptions?.getUser;
+    const user = userExtractor ? userExtractor(req) : req.subject ?? req.user;
+    const roleMap = options.roleMap ?? req.gatekeeperOptions?.roleMap;
+    const policy = options.policy ?? req.gatekeeperOptions?.policy;
+    const context = options.context ?? (options.getContext ? options.getContext(req) : req.gatekeeperOptions?.context ?? req.gatekeeperOptions?.getContext?.(req));
+    if (!user) {
+      const onUnauthorized = options.onUnauthorized ?? req.gatekeeperOptions?.onUnauthorized;
+      if (onUnauthorized) {
+        await onUnauthorized(res, req);
+        return;
+      }
+      res.status(401).json(UNAUTHORIZED_PAYLOAD);
+      return;
+    }
+    const hasPermission = (0, import_gatekeeper_core.can)(user, permission, { roleMap, policy, context });
+    if (!hasPermission) {
+      const onForbidden = options.onForbidden ?? req.gatekeeperOptions?.onForbidden;
+      if (onForbidden) {
+        await onForbidden(res, [permission], req);
+        return;
+      }
+      res.status(403).json(FORBIDDEN_PAYLOAD);
+      return;
+    }
+    next();
+  };
+}
+function requireAnyPermission(permissions, options = {}) {
+  return async (req, res, next) => {
+    const userExtractor = options.getSubject ?? options.getUser ?? req.gatekeeperOptions?.getSubject ?? req.gatekeeperOptions?.getUser;
+    const user = userExtractor ? userExtractor(req) : req.subject ?? req.user;
+    const roleMap = options.roleMap ?? req.gatekeeperOptions?.roleMap;
+    const policy = options.policy ?? req.gatekeeperOptions?.policy;
+    const context = options.context ?? (options.getContext ? options.getContext(req) : req.gatekeeperOptions?.context ?? req.gatekeeperOptions?.getContext?.(req));
+    if (!user) {
+      const onUnauthorized = options.onUnauthorized ?? req.gatekeeperOptions?.onUnauthorized;
+      if (onUnauthorized) {
+        await onUnauthorized(res, req);
+        return;
+      }
+      res.status(401).json(UNAUTHORIZED_PAYLOAD);
+      return;
+    }
+    const hasAny = (0, import_gatekeeper_core.canAny)(user, permissions, { roleMap, policy, context });
+    if (!hasAny) {
+      const onForbidden = options.onForbidden ?? req.gatekeeperOptions?.onForbidden;
+      if (onForbidden) {
+        await onForbidden(res, permissions, req);
+        return;
+      }
+      res.status(403).json(FORBIDDEN_PAYLOAD);
+      return;
+    }
+    next();
+  };
+}
+function requireFeatureFlag(flagKey, options = {}) {
+  return (req, res, next) => {
+    const flagsResolver = options.getFlags ?? req.gatekeeperOptions?.getFlags;
+    const flags = flagsResolver ? flagsResolver(req) : req.gatekeeperFlags;
+    const enabled = (0, import_gatekeeper_core.isFeatureEnabled)(flags, flagKey);
+    if (!enabled) {
+      res.status(403).json({
+        error: "FORBIDDEN",
+        message: `Feature '${flagKey}' is disabled.`
+      });
+      return;
+    }
+    next();
+  };
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  FORBIDDEN_PAYLOAD,
+  UNAUTHORIZED_PAYLOAD,
+  gatekeeperMiddleware,
+  requireAnyPermission,
+  requireFeatureFlag,
+  requirePermission
+});

package/dist/index.d.cts

@@ -0,0 +1,111 @@
+import { Request, Response, RequestHandler } from 'express';
+import { AuthorizationSubject, RolePermissionsMap, AuthorizationPolicy, Permission, EvaluateOptions } from '@ahmed109/gatekeeper-core';
+export { AuthorizationResult, FeatureFlag, GatekeeperUser, Permission, Role, RolePermissionsMap } from '@ahmed109/gatekeeper-core';
+
+type UnauthorizedHandler = (res: Response, req: Request) => void | Promise<void>;
+type ForbiddenHandler = (res: Response, missingPermissions: Permission[], req: Request) => void | Promise<void>;
+declare global {
+    namespace Express {
+        interface Request {
+            user?: AuthorizationSubject;
+            subject?: AuthorizationSubject;
+            gatekeeperFlags?: Record<string, boolean>;
+            gatekeeperOptions?: GatekeeperMiddlewareOptions;
+            can?: (permission: Permission, options?: EvaluateOptions) => boolean;
+        }
+    }
+}
+interface GatekeeperMiddlewareOptions {
+    /**
+     * Optional custom role-to-permissions map to use across middleware checks.
+     */
+    roleMap?: RolePermissionsMap;
+    /**
+     * Optional custom user extractor if user is stored in a non-standard property.
+     */
+    getUser?: (req: Request) => AuthorizationSubject | undefined | null;
+    /**
+     * Optional custom subject extractor.
+     */
+    getSubject?: (req: Request) => AuthorizationSubject | undefined | null;
+    /**
+     * Optional feature flag resolver.
+     */
+    getFlags?: (req: Request) => Record<string, boolean> | undefined;
+    /**
+     * Optional global policy callback for scoped or attribute checks.
+     */
+    policy?: AuthorizationPolicy;
+    /**
+     * Optional resolver for contextual attributes (e.g. { tenantId: req.params.tenantId }).
+     */
+    getContext?: (req: Request) => Record<string, unknown> | undefined;
+    /**
+     * Static context dictionary.
+     */
+    context?: Record<string, unknown>;
+    /**
+     * Custom unauthorized response handler for missing users (defaults to 401 JSON).
+     */
+    onUnauthorized?: UnauthorizedHandler;
+    /**
+     * Custom forbidden response handler for denied permissions (defaults to 403 JSON).
+     */
+    onForbidden?: ForbiddenHandler;
+}
+interface PermissionMiddlewareOptions {
+    roleMap?: RolePermissionsMap;
+    getUser?: (req: Request) => AuthorizationSubject | undefined | null;
+    getSubject?: (req: Request) => AuthorizationSubject | undefined | null;
+    policy?: AuthorizationPolicy;
+    getContext?: (req: Request) => Record<string, unknown> | undefined;
+    context?: Record<string, unknown>;
+    /**
+     * Custom unauthorized response handler overriding global settings.
+     */
+    onUnauthorized?: UnauthorizedHandler;
+    /**
+     * Custom forbidden response handler overriding global settings.
+     */
+    onForbidden?: ForbiddenHandler;
+}
+interface FeatureFlagMiddlewareOptions {
+    getFlags?: (req: Request) => Record<string, boolean> | undefined;
+}
+
+/**
+ * Standard HTTP 401 response payload.
+ */
+declare const UNAUTHORIZED_PAYLOAD: {
+    error: string;
+    message: string;
+};
+/**
+ * Standard HTTP 403 response payload.
+ */
+declare const FORBIDDEN_PAYLOAD: {
+    error: string;
+    message: string;
+};
+/**
+ * Global Gatekeeper middleware that attaches utility helpers to the Request object.
+ */
+declare function gatekeeperMiddleware(options?: GatekeeperMiddlewareOptions): RequestHandler;
+/**
+ * Express middleware requiring the authenticated user to possess a specific permission.
+ *
+ * @param permission - The permission required to access the route.
+ * @param options - Optional custom role map, user extractor, scoped policy, or failure callbacks.
+ */
+declare function requirePermission(permission: Permission, options?: PermissionMiddlewareOptions): RequestHandler;
+/**
+ * Express middleware requiring the authenticated user to possess AT LEAST ONE
+ * of the specified permissions.
+ */
+declare function requireAnyPermission(permissions: Permission[], options?: PermissionMiddlewareOptions): RequestHandler;
+/**
+ * Express middleware that guards an endpoint behind a feature flag.
+ */
+declare function requireFeatureFlag(flagKey: string, options?: FeatureFlagMiddlewareOptions): RequestHandler;
+
+export { FORBIDDEN_PAYLOAD, type FeatureFlagMiddlewareOptions, type ForbiddenHandler, type GatekeeperMiddlewareOptions, type PermissionMiddlewareOptions, UNAUTHORIZED_PAYLOAD, type UnauthorizedHandler, gatekeeperMiddleware, requireAnyPermission, requireFeatureFlag, requirePermission };

package/dist/index.d.ts

@@ -0,0 +1,111 @@
+import { Request, Response, RequestHandler } from 'express';
+import { AuthorizationSubject, RolePermissionsMap, AuthorizationPolicy, Permission, EvaluateOptions } from '@ahmed109/gatekeeper-core';
+export { AuthorizationResult, FeatureFlag, GatekeeperUser, Permission, Role, RolePermissionsMap } from '@ahmed109/gatekeeper-core';
+
+type UnauthorizedHandler = (res: Response, req: Request) => void | Promise<void>;
+type ForbiddenHandler = (res: Response, missingPermissions: Permission[], req: Request) => void | Promise<void>;
+declare global {
+    namespace Express {
+        interface Request {
+            user?: AuthorizationSubject;
+            subject?: AuthorizationSubject;
+            gatekeeperFlags?: Record<string, boolean>;
+            gatekeeperOptions?: GatekeeperMiddlewareOptions;
+            can?: (permission: Permission, options?: EvaluateOptions) => boolean;
+        }
+    }
+}
+interface GatekeeperMiddlewareOptions {
+    /**
+     * Optional custom role-to-permissions map to use across middleware checks.
+     */
+    roleMap?: RolePermissionsMap;
+    /**
+     * Optional custom user extractor if user is stored in a non-standard property.
+     */
+    getUser?: (req: Request) => AuthorizationSubject | undefined | null;
+    /**
+     * Optional custom subject extractor.
+     */
+    getSubject?: (req: Request) => AuthorizationSubject | undefined | null;
+    /**
+     * Optional feature flag resolver.
+     */
+    getFlags?: (req: Request) => Record<string, boolean> | undefined;
+    /**
+     * Optional global policy callback for scoped or attribute checks.
+     */
+    policy?: AuthorizationPolicy;
+    /**
+     * Optional resolver for contextual attributes (e.g. { tenantId: req.params.tenantId }).
+     */
+    getContext?: (req: Request) => Record<string, unknown> | undefined;
+    /**
+     * Static context dictionary.
+     */
+    context?: Record<string, unknown>;
+    /**
+     * Custom unauthorized response handler for missing users (defaults to 401 JSON).
+     */
+    onUnauthorized?: UnauthorizedHandler;
+    /**
+     * Custom forbidden response handler for denied permissions (defaults to 403 JSON).
+     */
+    onForbidden?: ForbiddenHandler;
+}
+interface PermissionMiddlewareOptions {
+    roleMap?: RolePermissionsMap;
+    getUser?: (req: Request) => AuthorizationSubject | undefined | null;
+    getSubject?: (req: Request) => AuthorizationSubject | undefined | null;
+    policy?: AuthorizationPolicy;
+    getContext?: (req: Request) => Record<string, unknown> | undefined;
+    context?: Record<string, unknown>;
+    /**
+     * Custom unauthorized response handler overriding global settings.
+     */
+    onUnauthorized?: UnauthorizedHandler;
+    /**
+     * Custom forbidden response handler overriding global settings.
+     */
+    onForbidden?: ForbiddenHandler;
+}
+interface FeatureFlagMiddlewareOptions {
+    getFlags?: (req: Request) => Record<string, boolean> | undefined;
+}
+
+/**
+ * Standard HTTP 401 response payload.
+ */
+declare const UNAUTHORIZED_PAYLOAD: {
+    error: string;
+    message: string;
+};
+/**
+ * Standard HTTP 403 response payload.
+ */
+declare const FORBIDDEN_PAYLOAD: {
+    error: string;
+    message: string;
+};
+/**
+ * Global Gatekeeper middleware that attaches utility helpers to the Request object.
+ */
+declare function gatekeeperMiddleware(options?: GatekeeperMiddlewareOptions): RequestHandler;
+/**
+ * Express middleware requiring the authenticated user to possess a specific permission.
+ *
+ * @param permission - The permission required to access the route.
+ * @param options - Optional custom role map, user extractor, scoped policy, or failure callbacks.
+ */
+declare function requirePermission(permission: Permission, options?: PermissionMiddlewareOptions): RequestHandler;
+/**
+ * Express middleware requiring the authenticated user to possess AT LEAST ONE
+ * of the specified permissions.
+ */
+declare function requireAnyPermission(permissions: Permission[], options?: PermissionMiddlewareOptions): RequestHandler;
+/**
+ * Express middleware that guards an endpoint behind a feature flag.
+ */
+declare function requireFeatureFlag(flagKey: string, options?: FeatureFlagMiddlewareOptions): RequestHandler;
+
+export { FORBIDDEN_PAYLOAD, type FeatureFlagMiddlewareOptions, type ForbiddenHandler, type GatekeeperMiddlewareOptions, type PermissionMiddlewareOptions, UNAUTHORIZED_PAYLOAD, type UnauthorizedHandler, gatekeeperMiddleware, requireAnyPermission, requireFeatureFlag, requirePermission };

package/dist/index.js

@@ -0,0 +1,119 @@
+// src/middleware.ts
+import {
+  can as coreCan,
+  canAny as coreCanAny,
+  isFeatureEnabled
+} from "@ahmed109/gatekeeper-core";
+var UNAUTHORIZED_PAYLOAD = {
+  error: "UNAUTHORIZED",
+  message: "Authentication required."
+};
+var FORBIDDEN_PAYLOAD = {
+  error: "FORBIDDEN",
+  message: "You do not have permission to perform this action."
+};
+function gatekeeperMiddleware(options = {}) {
+  return (req, _res, next) => {
+    req.gatekeeperOptions = options;
+    const extractor = options.getSubject ?? options.getUser;
+    const subject = extractor ? extractor(req) : req.subject ?? req.user;
+    if (subject) {
+      if (!req.user) req.user = subject;
+      if (!req.subject) req.subject = subject;
+    }
+    if (options.getFlags && !req.gatekeeperFlags) {
+      req.gatekeeperFlags = options.getFlags(req);
+    }
+    req.can = (permission, canOptions) => {
+      const activeUser = extractor ? extractor(req) : req.subject ?? req.user;
+      const resolvedContext = canOptions?.context ?? options.context ?? (options.getContext ? options.getContext(req) : void 0);
+      return coreCan(activeUser, permission, {
+        roleMap: canOptions?.roleMap ?? options.roleMap,
+        policy: canOptions?.policy ?? options.policy,
+        context: resolvedContext
+      });
+    };
+    next();
+  };
+}
+function requirePermission(permission, options = {}) {
+  return async (req, res, next) => {
+    const userExtractor = options.getSubject ?? options.getUser ?? req.gatekeeperOptions?.getSubject ?? req.gatekeeperOptions?.getUser;
+    const user = userExtractor ? userExtractor(req) : req.subject ?? req.user;
+    const roleMap = options.roleMap ?? req.gatekeeperOptions?.roleMap;
+    const policy = options.policy ?? req.gatekeeperOptions?.policy;
+    const context = options.context ?? (options.getContext ? options.getContext(req) : req.gatekeeperOptions?.context ?? req.gatekeeperOptions?.getContext?.(req));
+    if (!user) {
+      const onUnauthorized = options.onUnauthorized ?? req.gatekeeperOptions?.onUnauthorized;
+      if (onUnauthorized) {
+        await onUnauthorized(res, req);
+        return;
+      }
+      res.status(401).json(UNAUTHORIZED_PAYLOAD);
+      return;
+    }
+    const hasPermission = coreCan(user, permission, { roleMap, policy, context });
+    if (!hasPermission) {
+      const onForbidden = options.onForbidden ?? req.gatekeeperOptions?.onForbidden;
+      if (onForbidden) {
+        await onForbidden(res, [permission], req);
+        return;
+      }
+      res.status(403).json(FORBIDDEN_PAYLOAD);
+      return;
+    }
+    next();
+  };
+}
+function requireAnyPermission(permissions, options = {}) {
+  return async (req, res, next) => {
+    const userExtractor = options.getSubject ?? options.getUser ?? req.gatekeeperOptions?.getSubject ?? req.gatekeeperOptions?.getUser;
+    const user = userExtractor ? userExtractor(req) : req.subject ?? req.user;
+    const roleMap = options.roleMap ?? req.gatekeeperOptions?.roleMap;
+    const policy = options.policy ?? req.gatekeeperOptions?.policy;
+    const context = options.context ?? (options.getContext ? options.getContext(req) : req.gatekeeperOptions?.context ?? req.gatekeeperOptions?.getContext?.(req));
+    if (!user) {
+      const onUnauthorized = options.onUnauthorized ?? req.gatekeeperOptions?.onUnauthorized;
+      if (onUnauthorized) {
+        await onUnauthorized(res, req);
+        return;
+      }
+      res.status(401).json(UNAUTHORIZED_PAYLOAD);
+      return;
+    }
+    const hasAny = coreCanAny(user, permissions, { roleMap, policy, context });
+    if (!hasAny) {
+      const onForbidden = options.onForbidden ?? req.gatekeeperOptions?.onForbidden;
+      if (onForbidden) {
+        await onForbidden(res, permissions, req);
+        return;
+      }
+      res.status(403).json(FORBIDDEN_PAYLOAD);
+      return;
+    }
+    next();
+  };
+}
+function requireFeatureFlag(flagKey, options = {}) {
+  return (req, res, next) => {
+    const flagsResolver = options.getFlags ?? req.gatekeeperOptions?.getFlags;
+    const flags = flagsResolver ? flagsResolver(req) : req.gatekeeperFlags;
+    const enabled = isFeatureEnabled(flags, flagKey);
+    if (!enabled) {
+      res.status(403).json({
+        error: "FORBIDDEN",
+        message: `Feature '${flagKey}' is disabled.`
+      });
+      return;
+    }
+    next();
+  };
+}
+export {
+  FORBIDDEN_PAYLOAD,
+  UNAUTHORIZED_PAYLOAD,
+  gatekeeperMiddleware,
+  requireAnyPermission,
+  requireFeatureFlag,
+  requirePermission
+};

package/package.json

@@ -1,6 +1,64 @@
 {
   "name": "@ahmed109/gatekeeper-express",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.3.0",
+  "description": "Express middleware for authorization and feature flags with customizable callbacks powered by Gatekeeper Core",
+  "keywords": [
+    "express",
+    "middleware",
+    "authorization",
+    "rbac",
+    "permissions",
+    "feature-flags"
+  ],
+  "author": "Ahmed Tamer",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Ahmed1092002/npm-packages.git",
+    "directory": "gatekeeper/packages/express"
+  },
+  "bugs": {
+    "url": "https://github.com/Ahmed1092002/npm-packages/issues"
+  },
+  "homepage": "https://github.com/Ahmed1092002/npm-packages/tree/main/gatekeeper#readme",
+  "publishConfig": {
+    "access": "public"
+  },
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "peerDependencies": {
+    "express": ">=4.18.0"
+  },
+  "dependencies": {
+    "@ahmed109/gatekeeper-core": "^0.3.0"
+  },
+  "devDependencies": {
+    "@types/express": "^5.0.0",
+    "@types/supertest": "^6.0.2",
+    "express": "^4.21.2",
+    "supertest": "^7.0.0",
+    "tsup": "^8.3.6",
+    "typescript": "^5.7.3",
+    "vitest": "^3.0.5"
+  },
+  "scripts": {
+    "build": "tsup src/index.ts --format esm,cjs --dts --clean --external express,@ahmed109/gatekeeper-core",
+    "dev": "tsup src/index.ts --format esm,cjs --dts --watch --external express,@ahmed109/gatekeeper-core",
+    "test": "vitest run",
+    "lint": "eslint src"
+  }
 }