@globaltracking/auth-middleware 2.0.0

package/README.md

@@ -0,0 +1,372 @@
+# @globaltracking/auth-middleware
+
+Unified authentication and authorization middleware for the **Global Tracking** platform. Shared by all backend microservices — supports both **Express** and **NestJS**.
+
+## Features
+
+- **Strategy pattern**: Gateway header, trusted headers, JWT — configurable per service
+- **NestJS adapter**: `GtAuthModule`, guards, decorators, interceptors, exception filter
+- **Express middleware**: `authenticate`, `requirePermission`, `requireRole`, `requireSelf`, `requireTenant`
+- **Hybrid permission resolution**: JWT claims (fast) → custom resolver → RBAC HTTP call → deny (fail-closed)
+- **Multi-tenant RLS**: `OrgContextInterceptor` sets `SET LOCAL app.current_org_id` for PostgreSQL Row-Level Security
+- **Admin bypass**: Configurable `adminRoles[]` bypass all permission checks
+- **TypeScript-first**: Full type definitions with Express `Request` augmentation
+- **98%+ test coverage**: 89 tests across strategies, middlewares, and config
+
+## Installation
+
+```bash
+npm install @globaltracking/auth-middleware
+```
+
+**Peer dependencies:**
+
+| Package | Required for | Optional? |
+|---------|-------------|-----------|
+| `express` ^4.18 | Express middleware | Required |
+| `@nestjs/common` ^11.0 | NestJS adapter | Optional |
+| `@nestjs/core` ^11.0 | NestJS adapter | Optional |
+| `typeorm` ^0.3.0 | OrgContextInterceptor (RLS) | Optional |
+| `rxjs` ^7.0 | OrgContextInterceptor | Optional |
+
+---
+
+## NestJS Integration (Recommended)
+
+This is the primary integration path for Global Tracking microservices.
+
+### 1. Import GtAuthModule in your AppModule
+
+```typescript
+import { Module } from '@nestjs/common';
+import { ConfigService } from '@nestjs/config';
+import { GtAuthModule } from '@globaltracking/auth-middleware/nestjs';
+
+@Module({
+  imports: [
+    // ... ConfigModule, TypeOrmModule, ThrottlerModule ...
+
+    GtAuthModule.forRootAsync({
+      inject: [ConfigService],
+      useFactory: (config: ConfigService) => ({
+        strategies: ['trusted-headers'],
+        internalGatewayToken: config.get('INTERNAL_GATEWAY_TOKEN'),
+        adminRoles: ['system_admin', 'org_admin'],
+        rbacServiceUrl: config.get('RBAC_SERVICE_URL'),
+      }),
+    }),
+
+    // ... domain modules ...
+  ],
+})
+export class AppModule {}
+```
+
+**What `GtAuthModule` provides (globally):**
+
+| Component | What it does |
+|-----------|-------------|
+| `GtTrustedHeadersMiddleware` | Extracts `req.user` from configured strategy chain (auto-applied to all routes) |
+| `InternalOnlyGuard` | Validates `X-Gateway-Token` header — register as `APP_GUARD` |
+| `GtPermissionsGuard` | Checks `@RequirePermissions()` — register as `APP_GUARD` |
+| `OrgContextInterceptor` | Sets PostgreSQL RLS context — register as `APP_INTERCEPTOR` |
+| `AuthExceptionFilter` | Catches `AuthError` and returns standard error envelope |
+
+### 2. Use decorators in controllers
+
+```typescript
+import {
+  RequirePermissions,
+  CurrentUser,
+  CurrentOrg,
+  Public,
+  RequireRoles,
+} from '@globaltracking/auth-middleware/nestjs';
+
+@Controller('vehicles')
+export class VehiclesController {
+  @Post()
+  @RequirePermissions('vehicles:create')
+  create(
+    @CurrentOrg() orgId: string,
+    @CurrentUser('userId') userId: string,
+    @Body() dto: CreateVehicleDto,
+  ) {
+    // orgId and userId extracted from trusted headers
+  }
+
+  @Get(':id')
+  @RequirePermissions('vehicles:read')
+  findOne(
+    @CurrentOrg() orgId: string,
+    @Param('id', ParseUUIDPipe) id: string,
+  ) { ... }
+
+  @Delete(':id')
+  @RequireRoles('system_admin')
+  remove(@Param('id', ParseUUIDPipe) id: string) { ... }
+}
+```
+
+```typescript
+// Health endpoints skip auth
+@Controller('health')
+export class HealthController {
+  @Get()
+  @Public()
+  liveness() {
+    return { status: 'ok' };
+  }
+}
+```
+
+### 3. Register guards and interceptors
+
+```typescript
+// app.module.ts providers
+import {
+  InternalOnlyGuard,
+  GtPermissionsGuard,
+  OrgContextInterceptor,
+} from '@globaltracking/auth-middleware/nestjs';
+
+providers: [
+  { provide: APP_GUARD, useClass: InternalOnlyGuard },
+  { provide: APP_GUARD, useClass: GtPermissionsGuard },
+  { provide: APP_GUARD, useClass: ThrottlerGuard },
+  { provide: APP_INTERCEPTOR, useClass: OrgContextInterceptor },
+  // ... your other interceptors
+],
+```
+
+### 4. Add env vars
+
+```env
+INTERNAL_GATEWAY_TOKEN=your-32-char-min-secret
+RBAC_SERVICE_URL=http://gt-rbac-service:3000   # optional, for permission resolution
+```
+
+### Special case: gt-rbac-service
+
+The RBAC service **cannot call itself** for permission resolution. Instead, inject its own `ResolveService` via `permissionResolver`:
+
+```typescript
+GtAuthModule.forRootAsync({
+  imports: [ResolveModule],
+  inject: [ConfigService, ResolveService],
+  useFactory: (config: ConfigService, resolveService: ResolveService) => ({
+    strategies: ['trusted-headers'],
+    internalGatewayToken: config.get('INTERNAL_GATEWAY_TOKEN'),
+    adminRoles: ['system_admin', 'org_admin'],
+    permissionResolver: (orgId, userId, resource, action) =>
+      resolveService.checkPermission(orgId, userId, resource, action),
+  }),
+}),
+```
+
+---
+
+## Express Integration
+
+For services that use plain Express (no NestJS):
+
+```typescript
+import express from 'express';
+import {
+  initAuth,
+  authenticate,
+  requirePermission,
+  requireTenant,
+  authErrorHandler,
+} from '@globaltracking/auth-middleware';
+
+const app = express();
+
+// Initialize once at startup
+initAuth({
+  strategies: ['gateway-header', 'jwt'],
+  adminRoles: ['system_admin', 'org_admin'],
+  publicKeyPath: './keys/public.pem',
+});
+
+// Protected route
+app.get('/v1/vehicles',
+  authenticate,
+  requireTenant,
+  requirePermission('vehicles:read'),
+  async (req, res) => {
+    // req.user.userId, req.user.orgId, etc.
+    // req.tenantId set by requireTenant
+  }
+);
+
+// Error handler (must be last)
+app.use(authErrorHandler);
+```
+
+---
+
+## Configuration
+
+```typescript
+initAuth({
+  // Strategy chain — tried in order until one matches
+  strategies: ['gateway-header', 'jwt'],  // default
+
+  // Gateway header name (GCP API Gateway)
+  gatewayHeaderName: 'x-apigateway-api-userinfo',  // default
+
+  // JWT verification (for local dev / non-gateway)
+  jwtIssuer: 'globaltracking-auth',  // default
+  publicKey: '-----BEGIN PUBLIC KEY-----\n...',  // PEM string
+  publicKeyPath: './keys/public.pem',             // or file path
+
+  // Roles that bypass all permission checks
+  adminRoles: ['system_admin', 'org_admin'],  // default
+
+  // Trusted headers strategy config
+  internalGatewayToken: 'secret',  // also reads env INTERNAL_GATEWAY_TOKEN
+  trustedHeaderNames: {
+    userId: 'x-user-id',        // default
+    orgId: 'x-org-id',          // default
+    userRole: 'x-user-role',    // default
+    requestId: 'x-request-id',  // default
+    gatewayToken: 'x-gateway-token',  // default
+  },
+
+  // Permission resolution (NestJS GtPermissionsGuard)
+  rbacServiceUrl: 'http://gt-rbac-service:3000',  // HTTP fallback
+  permissionResolver: async (orgId, userId, resource, action) => {
+    // Custom resolver (e.g., direct DB call)
+    return true;
+  },
+});
+```
+
+Public key resolution order: `publicKey` → `publicKeyPath` → `AUTH_PUBLIC_KEY` env → `AUTH_PUBLIC_KEY_PATH` env.
+
+---
+
+## Auth Strategies
+
+| Strategy | When used | What it reads |
+|----------|-----------|---------------|
+| `gateway-header` | Production (GCP API Gateway) | Base64-encoded JSON in `X-Apigateway-Api-Userinfo` |
+| `trusted-headers` | NestJS services behind API Gateway | `X-User-Id`, `X-Org-Id`, `X-User-Role`, `X-Request-Id`, `X-Gateway-Token` |
+| `jwt` | Local dev, non-gateway environments | `Authorization: Bearer <token>` (RS256 verification) |
+
+The strategy chain iterates in the configured order. The first strategy whose `canHandle(req)` returns true is used.
+
+---
+
+## AuthUser Shape
+
+Every authenticated request gets `req.user` populated with:
+
+```typescript
+interface AuthUser {
+  userId: string;          // from JWT sub or X-User-Id
+  email: string;           // from JWT email (empty in trusted-headers mode)
+  role: UserRole;          // from JWT role or X-User-Role
+  orgId: string;           // from JWT org_id or X-Org-Id
+  tenantId: string;        // = orgId in trusted-headers mode
+  permissions: string[];   // from JWT claims (empty in trusted-headers mode)
+  requestId: string;       // from X-Request-Id
+  authSource: AuthStrategy; // 'gateway-header' | 'trusted-headers' | 'jwt'
+}
+```
+
+---
+
+## Permission Resolution (GtPermissionsGuard)
+
+The NestJS `GtPermissionsGuard` resolves permissions in 3 tiers:
+
+1. **JWT claims** — If `user.permissions` is non-empty, check in-memory (fast path)
+2. **permissionResolver** — If configured, call the function directly (for RBAC service)
+3. **RBAC HTTP call** — If `rbacServiceUrl` is configured, POST to `/v1/resolve/check`
+4. **Deny** — Fail-closed if no resolution mechanism is available
+
+Admin roles (`config.adminRoles`) always bypass all checks.
+
+---
+
+## Express Middlewares
+
+| Middleware | Purpose |
+|-----------|---------|
+| `authenticate` | Extracts `req.user` from strategy chain |
+| `requireRole(...roles)` | Checks `req.user.role` against allowed roles |
+| `requirePermission(...perms)` | Requires ALL listed permissions (admin bypass) |
+| `requireAnyPermission(...perms)` | Requires AT LEAST ONE permission (admin bypass) |
+| `requireTenant` | Ensures `req.user.tenantId` exists, sets `req.tenantId` |
+| `requireSelf(paramName?)` | Compares `req.user.userId` with route param (admin bypass) |
+| `authErrorHandler` | Error handler for `AuthError` subclasses |
+
+---
+
+## Error Handling
+
+All auth errors extend `AuthError` and produce the standard Global Tracking error envelope:
+
+```typescript
+import { UnauthorizedError, ForbiddenError } from '@globaltracking/auth-middleware';
+
+throw new UnauthorizedError('Token expired');
+// → 401 { success: false, error: { code: 'UNAUTHORIZED', message: 'Token expired', statusCode: 401 } }
+
+throw new ForbiddenError('Insufficient permissions', { required: ['vehicles:write'] });
+// → 403 { success: false, error: { code: 'FORBIDDEN', message: 'Insufficient permissions', statusCode: 403 } }
+```
+
+---
+
+## Utility Functions
+
+```typescript
+import { extractUser, hasRole, hasPermission, hasAnyPermission } from '@globaltracking/auth-middleware';
+
+const user = extractUser(req);            // throws UnauthorizedError if missing
+hasRole(user, 'system_admin');            // boolean
+hasPermission(user, 'vehicles:read');     // all must match
+hasAnyPermission(user, 'a:read', 'b:read'); // at least one
+```
+
+---
+
+## Files Replaced Per Service
+
+When a NestJS service adopts this package, these ~10 files can be deleted:
+
+```
+src/common/decorators/current-org.decorator.ts      → @CurrentOrg from package
+src/common/decorators/current-user.decorator.ts     → @CurrentUser from package
+src/common/decorators/permissions.decorator.ts      → @RequirePermissions from package
+src/common/decorators/public.decorator.ts           → @Public from package
+src/common/guards/internal-only.guard.ts            → InternalOnlyGuard from package
+src/common/guards/permissions.guard.ts              → GtPermissionsGuard from package
+src/common/interceptors/org-context.interceptor.ts  → OrgContextInterceptor from package
+src/common/middleware/trusted-headers.middleware.ts  → GtTrustedHeadersMiddleware from package
+src/common/interfaces/jwt-payload.interface.ts      → AuthUser from package
+src/common/interfaces/request-context.interface.ts  → (Express augmentation from package)
+```
+
+---
+
+## Development
+
+```bash
+npm test           # run tests with coverage (89 tests, 98%+ coverage)
+npm run test:watch # watch mode
+npm run build      # compile to dist/
+npm run clean      # remove dist/
+```
+
+---
+
+## Migration from v1.x
+
+- `superAdminRole` → use `adminRoles: ['system_admin', 'org_admin']` (legacy `superAdminRole` still works)
+- `RequestUser` type alias still exported for backward compatibility
+- Error handler now returns `{ success: false, error: { code, message, statusCode } }` envelope instead of `{ error: message }`
+- `extractUser()` now sets `authSource` and `requestId` on returned user

package/dist/config.d.ts

@@ -0,0 +1,9 @@
+import { AuthConfig, ResolvedAuthConfig } from './types';
+/**
+ * Initialize auth middleware configuration. Call once at app startup.
+ */
+export declare function initAuth(config?: AuthConfig): void;
+export declare function getConfig(): ResolvedAuthConfig;
+/** Reset config to defaults (used in tests) */
+export declare function resetConfig(): void;
+//# sourceMappingURL=config.d.ts.map

package/dist/config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,UAAU,EAAE,kBAAkB,EAAE,MAAM,SAAS,CAAC;AAyBzD;;GAEG;AACH,wBAAgB,QAAQ,CAAC,MAAM,GAAE,UAAe,GAAG,IAAI,CAqCtD;AAED,wBAAgB,SAAS,IAAI,kBAAkB,CAE9C;AAED,+CAA+C;AAC/C,wBAAgB,WAAW,IAAI,IAAI,CAElC"}

package/dist/config.js

@@ -0,0 +1,110 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.initAuth = initAuth;
+exports.getConfig = getConfig;
+exports.resetConfig = resetConfig;
+const fs = __importStar(require("fs"));
+const DEFAULT_TRUSTED_HEADERS = {
+    userId: 'x-user-id',
+    orgId: 'x-org-id',
+    userRole: 'x-user-role',
+    requestId: 'x-request-id',
+    gatewayToken: 'x-gateway-token',
+};
+const DEFAULT_CONFIG = {
+    gatewayHeaderName: 'x-apigateway-api-userinfo',
+    jwtIssuer: 'globaltracking-auth',
+    publicKey: '',
+    publicKeyPath: '',
+    strategies: ['gateway-header', 'jwt'],
+    adminRoles: ['system_admin', 'org_admin'],
+    internalGatewayToken: '',
+    trustedHeaderNames: { ...DEFAULT_TRUSTED_HEADERS },
+    rbacServiceUrl: '',
+    permissionResolver: undefined,
+};
+let currentConfig = { ...DEFAULT_CONFIG, trustedHeaderNames: { ...DEFAULT_TRUSTED_HEADERS } };
+/**
+ * Initialize auth middleware configuration. Call once at app startup.
+ */
+function initAuth(config = {}) {
+    // Resolve adminRoles: explicit adminRoles > legacy superAdminRole > default
+    let adminRoles = DEFAULT_CONFIG.adminRoles;
+    if (config.adminRoles) {
+        adminRoles = config.adminRoles;
+    }
+    else if (config.superAdminRole) {
+        adminRoles = [config.superAdminRole];
+    }
+    currentConfig = {
+        gatewayHeaderName: config.gatewayHeaderName ?? DEFAULT_CONFIG.gatewayHeaderName,
+        jwtIssuer: config.jwtIssuer ?? DEFAULT_CONFIG.jwtIssuer,
+        publicKey: '',
+        publicKeyPath: '',
+        strategies: config.strategies ?? DEFAULT_CONFIG.strategies,
+        adminRoles,
+        internalGatewayToken: config.internalGatewayToken || process.env.INTERNAL_GATEWAY_TOKEN || '',
+        trustedHeaderNames: {
+            ...DEFAULT_TRUSTED_HEADERS,
+            ...config.trustedHeaderNames,
+        },
+        rbacServiceUrl: config.rbacServiceUrl ?? '',
+        permissionResolver: config.permissionResolver,
+    };
+    // Resolve public key: explicit config → env vars → empty (gateway-only mode)
+    if (config.publicKey) {
+        currentConfig.publicKey = config.publicKey;
+    }
+    else if (config.publicKeyPath) {
+        currentConfig.publicKey = fs.readFileSync(config.publicKeyPath, 'utf-8');
+        currentConfig.publicKeyPath = config.publicKeyPath;
+    }
+    else if (process.env.AUTH_PUBLIC_KEY) {
+        currentConfig.publicKey = process.env.AUTH_PUBLIC_KEY;
+    }
+    else if (process.env.AUTH_PUBLIC_KEY_PATH) {
+        currentConfig.publicKey = fs.readFileSync(process.env.AUTH_PUBLIC_KEY_PATH, 'utf-8');
+        currentConfig.publicKeyPath = process.env.AUTH_PUBLIC_KEY_PATH;
+    }
+}
+function getConfig() {
+    return currentConfig;
+}
+/** Reset config to defaults (used in tests) */
+function resetConfig() {
+    currentConfig = { ...DEFAULT_CONFIG, trustedHeaderNames: { ...DEFAULT_TRUSTED_HEADERS } };
+}
+//# sourceMappingURL=config.js.map

package/dist/config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.js","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"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"}

package/dist/errors.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Base auth error class. Works in both Express and NestJS contexts.
+ * Contains a `toResponse()` method that produces the standard error envelope.
+ */
+export declare class AuthError extends Error {
+    readonly statusCode: number;
+    readonly code: string;
+    constructor(message: string, statusCode: number, code: string);
+    /** Returns the standard Global Tracking error envelope */
+    toResponse(): {
+        success: false;
+        error: {
+            code: string;
+            message: string;
+            statusCode: number;
+        };
+    };
+}
+export declare class UnauthorizedError extends AuthError {
+    constructor(message?: string);
+}
+export declare class ForbiddenError extends AuthError {
+    readonly details?: Record<string, unknown>;
+    constructor(message?: string, details?: Record<string, unknown>);
+}
+//# sourceMappingURL=errors.d.ts.map

package/dist/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,qBAAa,SAAU,SAAQ,KAAK;IAClC,SAAgB,UAAU,EAAE,MAAM,CAAC;IACnC,SAAgB,IAAI,EAAE,MAAM,CAAC;gBAEjB,OAAO,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM;IAQ7D,0DAA0D;IAC1D,UAAU,IAAI;QAAE,OAAO,EAAE,KAAK,CAAC;QAAC,KAAK,EAAE;YAAE,IAAI,EAAE,MAAM,CAAC;YAAC,OAAO,EAAE,MAAM,CAAC;YAAC,UAAU,EAAE,MAAM,CAAA;SAAE,CAAA;KAAE;CAU/F;AAED,qBAAa,iBAAkB,SAAQ,SAAS;gBAClC,OAAO,SAA4B;CAGhD;AAED,qBAAa,cAAe,SAAQ,SAAS;IAC3C,SAAgB,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;gBAEtC,OAAO,SAAkB,EAAE,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;CAIzE"}

package/dist/errors.js

@@ -0,0 +1,42 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ForbiddenError = exports.UnauthorizedError = exports.AuthError = void 0;
+/**
+ * Base auth error class. Works in both Express and NestJS contexts.
+ * Contains a `toResponse()` method that produces the standard error envelope.
+ */
+class AuthError extends Error {
+    constructor(message, statusCode, code) {
+        super(message);
+        this.name = this.constructor.name;
+        this.statusCode = statusCode;
+        this.code = code;
+        Object.setPrototypeOf(this, new.target.prototype);
+    }
+    /** Returns the standard Global Tracking error envelope */
+    toResponse() {
+        return {
+            success: false,
+            error: {
+                code: this.code,
+                message: this.message,
+                statusCode: this.statusCode,
+            },
+        };
+    }
+}
+exports.AuthError = AuthError;
+class UnauthorizedError extends AuthError {
+    constructor(message = 'Authentication required') {
+        super(message, 401, 'UNAUTHORIZED');
+    }
+}
+exports.UnauthorizedError = UnauthorizedError;
+class ForbiddenError extends AuthError {
+    constructor(message = 'Access denied', details) {
+        super(message, 403, 'FORBIDDEN');
+        this.details = details;
+    }
+}
+exports.ForbiddenError = ForbiddenError;
+//# sourceMappingURL=errors.js.map

package/dist/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":";;;AAAA;;;GAGG;AACH,MAAa,SAAU,SAAQ,KAAK;IAIlC,YAAY,OAAe,EAAE,UAAkB,EAAE,IAAY;QAC3D,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC,WAAW,CAAC,IAAI,CAAC;QAClC,IAAI,CAAC,UAAU,GAAG,UAAU,CAAC;QAC7B,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;QACjB,MAAM,CAAC,cAAc,CAAC,IAAI,EAAE,GAAG,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC;IACpD,CAAC;IAED,0DAA0D;IAC1D,UAAU;QACR,OAAO;YACL,OAAO,EAAE,KAAK;YACd,KAAK,EAAE;gBACL,IAAI,EAAE,IAAI,CAAC,IAAI;gBACf,OAAO,EAAE,IAAI,CAAC,OAAO;gBACrB,UAAU,EAAE,IAAI,CAAC,UAAU;aAC5B;SACF,CAAC;IACJ,CAAC;CACF;AAvBD,8BAuBC;AAED,MAAa,iBAAkB,SAAQ,SAAS;IAC9C,YAAY,OAAO,GAAG,yBAAyB;QAC7C,KAAK,CAAC,OAAO,EAAE,GAAG,EAAE,cAAc,CAAC,CAAC;IACtC,CAAC;CACF;AAJD,8CAIC;AAED,MAAa,cAAe,SAAQ,SAAS;IAG3C,YAAY,OAAO,GAAG,eAAe,EAAE,OAAiC;QACtE,KAAK,CAAC,OAAO,EAAE,GAAG,EAAE,WAAW,CAAC,CAAC;QACjC,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC;IACzB,CAAC;CACF;AAPD,wCAOC"}

package/dist/extract-user.d.ts

@@ -0,0 +1,10 @@
+import { Request } from 'express';
+import { AuthUser } from './types';
+/**
+ * Extract AuthUser from a request using the configured strategy chain.
+ * Iterates through `config.strategies` in order, trying each until one succeeds.
+ *
+ * Throws UnauthorizedError if no strategy can handle the request.
+ */
+export declare function extractUser(req: Request): AuthUser;
+//# sourceMappingURL=extract-user.d.ts.map

package/dist/extract-user.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"extract-user.d.ts","sourceRoot":"","sources":["../src/extract-user.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,SAAS,CAAC;AAGlC,OAAO,EAAE,QAAQ,EAAgB,MAAM,SAAS,CAAC;AAYjD;;;;;GAKG;AACH,wBAAgB,WAAW,CAAC,GAAG,EAAE,OAAO,GAAG,QAAQ,CAWlD"}

package/dist/extract-user.js

@@ -0,0 +1,30 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.extractUser = extractUser;
+const config_1 = require("./config");
+const errors_1 = require("./errors");
+const gateway_header_strategy_1 = require("./strategies/gateway-header.strategy");
+const trusted_headers_strategy_1 = require("./strategies/trusted-headers.strategy");
+const jwt_strategy_1 = require("./strategies/jwt.strategy");
+const strategyMap = {
+    'gateway-header': new gateway_header_strategy_1.GatewayHeaderStrategy(),
+    'trusted-headers': new trusted_headers_strategy_1.TrustedHeadersStrategy(),
+    'jwt': new jwt_strategy_1.JwtStrategy(),
+};
+/**
+ * Extract AuthUser from a request using the configured strategy chain.
+ * Iterates through `config.strategies` in order, trying each until one succeeds.
+ *
+ * Throws UnauthorizedError if no strategy can handle the request.
+ */
+function extractUser(req) {
+    const config = (0, config_1.getConfig)();
+    for (const strategyName of config.strategies) {
+        const strategy = strategyMap[strategyName];
+        if (strategy && strategy.canHandle(req)) {
+            return strategy.extract(req);
+        }
+    }
+    throw new errors_1.UnauthorizedError('No authentication credentials provided');
+}
+//# sourceMappingURL=extract-user.js.map

package/dist/extract-user.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"extract-user.js","sourceRoot":"","sources":["../src/extract-user.ts"],"names":[],"mappings":";;AAqBA,kCAWC;AA/BD,qCAAqC;AACrC,qCAA6C;AAG7C,kFAA6E;AAC7E,oFAA+E;AAC/E,4DAAwD;AAExD,MAAM,WAAW,GAAiD;IAChE,gBAAgB,EAAE,IAAI,+CAAqB,EAAE;IAC7C,iBAAiB,EAAE,IAAI,iDAAsB,EAAE;IAC/C,KAAK,EAAE,IAAI,0BAAW,EAAE;CACzB,CAAC;AAEF;;;;;GAKG;AACH,SAAgB,WAAW,CAAC,GAAY;IACtC,MAAM,MAAM,GAAG,IAAA,kBAAS,GAAE,CAAC;IAE3B,KAAK,MAAM,YAAY,IAAI,MAAM,CAAC,UAAU,EAAE,CAAC;QAC7C,MAAM,QAAQ,GAAG,WAAW,CAAC,YAAY,CAAC,CAAC;QAC3C,IAAI,QAAQ,IAAI,QAAQ,CAAC,SAAS,CAAC,GAAG,CAAC,EAAE,CAAC;YACxC,OAAO,QAAQ,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;QAC/B,CAAC;IACH,CAAC;IAED,MAAM,IAAI,0BAAiB,CAAC,wCAAwC,CAAC,CAAC;AACxE,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,16 @@
+export { initAuth, getConfig, resetConfig } from './config';
+export { AuthUser, RequestUser, AuthConfig, AuthStrategy, JwtPayload, UserRole, TrustedHeaderNames, ResolvedAuthConfig } from './types';
+export { AuthError, UnauthorizedError, ForbiddenError } from './errors';
+export { extractUser } from './extract-user';
+export { AuthExtractionStrategy } from './strategies/strategy.interface';
+export { GatewayHeaderStrategy } from './strategies/gateway-header.strategy';
+export { TrustedHeadersStrategy } from './strategies/trusted-headers.strategy';
+export { JwtStrategy } from './strategies/jwt.strategy';
+export { authenticate } from './middlewares/authenticate';
+export { requireRole } from './middlewares/require-role';
+export { requirePermission, requireAnyPermission } from './middlewares/require-permission';
+export { requireTenant } from './middlewares/require-tenant';
+export { requireSelf } from './middlewares/require-self';
+export { authErrorHandler } from './middlewares/error-handler';
+export { hasRole, hasPermission, hasAnyPermission } from './utils/helpers';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,QAAQ,EAAE,SAAS,EAAE,WAAW,EAAE,MAAM,UAAU,CAAC;AAG5D,OAAO,EAAE,QAAQ,EAAE,WAAW,EAAE,UAAU,EAAE,YAAY,EAAE,UAAU,EAAE,QAAQ,EAAE,kBAAkB,EAAE,kBAAkB,EAAE,MAAM,SAAS,CAAC;AAGxI,OAAO,EAAE,SAAS,EAAE,iBAAiB,EAAE,cAAc,EAAE,MAAM,UAAU,CAAC;AAGxE,OAAO,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAG7C,OAAO,EAAE,sBAAsB,EAAE,MAAM,iCAAiC,CAAC;AACzE,OAAO,EAAE,qBAAqB,EAAE,MAAM,sCAAsC,CAAC;AAC7E,OAAO,EAAE,sBAAsB,EAAE,MAAM,uCAAuC,CAAC;AAC/E,OAAO,EAAE,WAAW,EAAE,MAAM,2BAA2B,CAAC;AAGxD,OAAO,EAAE,YAAY,EAAE,MAAM,4BAA4B,CAAC;AAC1D,OAAO,EAAE,WAAW,EAAE,MAAM,4BAA4B,CAAC;AACzD,OAAO,EAAE,iBAAiB,EAAE,oBAAoB,EAAE,MAAM,kCAAkC,CAAC;AAC3F,OAAO,EAAE,aAAa,EAAE,MAAM,8BAA8B,CAAC;AAC7D,OAAO,EAAE,WAAW,EAAE,MAAM,4BAA4B,CAAC;AACzD,OAAO,EAAE,gBAAgB,EAAE,MAAM,6BAA6B,CAAC;AAG/D,OAAO,EAAE,OAAO,EAAE,aAAa,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAC"}