@yuva-devlab/auth-server 0.0.0-stage → 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Yuva Devlab
+
+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/dist/index.cjs

@@ -0,0 +1,273 @@
+'use strict';
+
+var errors = require('@yuva-devlab/errors');
+var logger$1 = require('@yuva-devlab/logger');
+
+// src/constants/auth.constants.ts
+var DEFAULT_AUTH_HEADER = "authorization";
+var DEFAULT_API_KEY_HEADER = "x-api-key";
+var DEFAULT_BEARER_PREFIX = "Bearer ";
+var DEFAULT_JWKS_CACHE_TTL_MS = 36e5;
+var DEFAULT_PUBLIC_PATHS = Object.freeze([
+  "/health",
+  "/ready",
+  "/live",
+  "/metrics"
+]);
+var HTTP_STATUS_UNAUTHORIZED = 401;
+var HTTP_STATUS_FORBIDDEN = 403;
+var HTTP_STATUS_SERVICE_UNAVAILABLE = 503;
+
+// src/types/auth.types.ts
+var AppStatus = /* @__PURE__ */ ((AppStatus2) => {
+  AppStatus2["ACTIVE"] = "ACTIVE";
+  AppStatus2["INACTIVE"] = "INACTIVE";
+  AppStatus2["MAINTENANCE"] = "MAINTENANCE";
+  return AppStatus2;
+})(AppStatus || {});
+var logger = logger$1.loggerWithConfig(new logger$1.Logger("JwksValidator"));
+var JwksValidator = class {
+  jwksUri;
+  audience;
+  issuer;
+  cacheTtlMs;
+  keyCache = /* @__PURE__ */ new Map();
+  /**
+   * Initializes the JWKS validator.
+   *
+   * @param config - JWKS configuration parameters
+   */
+  constructor(config) {
+    this.jwksUri = config.jwksUri;
+    this.audience = config.audience;
+    this.issuer = config.issuer;
+    this.cacheTtlMs = config.cacheTtlMs ?? DEFAULT_JWKS_CACHE_TTL_MS;
+    logger.debug("[constructor] JwksValidator initialized", {
+      jwksUri: this.jwksUri,
+      issuer: this.issuer,
+      audience: this.audience
+    });
+  }
+  /**
+   * Decodes a JWT token without verifying cryptographic signature.
+   *
+   * @param token - Base64Url encoded JWT string
+   * @returns Header and payload objects
+   */
+  parseUnverified(token) {
+    const parts = token.split(".");
+    if (parts.length !== 3) {
+      throw new errors.UnauthorizedError("Malformed JWT token format");
+    }
+    try {
+      const header = JSON.parse(
+        Buffer.from(parts[0], "base64url").toString("utf-8")
+      );
+      const payload = JSON.parse(
+        Buffer.from(parts[1], "base64url").toString("utf-8")
+      );
+      return { header, payload };
+    } catch {
+      throw new errors.UnauthorizedError("Unable to decode JWT payload");
+    }
+  }
+  /**
+   * Verifies standard claims (exp, nbf, iss, aud) on a JWT token.
+   *
+   * @param token - Bearer access token
+   * @returns Validated JwtPayload claims
+   */
+  async verifyToken(token) {
+    const { payload } = this.parseUnverified(token);
+    const nowSeconds = Math.floor(Date.now() / 1e3);
+    if (typeof payload.exp === "number" && nowSeconds >= payload.exp) {
+      logger.warn("[verifyToken] Token has expired", {
+        exp: payload.exp,
+        now: nowSeconds
+      });
+      throw new errors.UnauthorizedError("Authentication token has expired");
+    }
+    if (typeof payload.nbf === "number" && nowSeconds < payload.nbf) {
+      logger.warn("[verifyToken] Token not yet valid", {
+        nbf: payload.nbf,
+        now: nowSeconds
+      });
+      throw new errors.UnauthorizedError("Authentication token is not yet active");
+    }
+    if (this.issuer && payload.iss && payload.iss !== this.issuer) {
+      logger.warn("[verifyToken] Issuer mismatch", {
+        expected: this.issuer,
+        actual: payload.iss
+      });
+      throw new errors.UnauthorizedError("Token issuer mismatch");
+    }
+    if (this.audience && payload.aud) {
+      const audList = Array.isArray(payload.aud) ? payload.aud : [payload.aud];
+      if (!audList.includes(this.audience)) {
+        logger.warn("[verifyToken] Audience mismatch", {
+          expected: this.audience,
+          actual: payload.aud
+        });
+        throw new errors.UnauthorizedError("Token audience mismatch");
+      }
+    }
+    logger.debug("[verifyToken] Successfully validated token claims", {
+      sub: payload.sub
+    });
+    return payload;
+  }
+  /**
+   * Clears cached public keys from memory.
+   */
+  clearKeyCache() {
+    this.keyCache.clear();
+    logger.info("[clearKeyCache] JWKS public key cache cleared");
+  }
+};
+var logger2 = logger$1.loggerWithConfig(new logger$1.Logger("AuthGuards"));
+function requireUser(ctx, requiredRoles) {
+  if (!ctx.authenticated || !ctx.user) {
+    logger2.warn(
+      "[requireUser] Request rejected: missing authenticated user context"
+    );
+    throw new errors.UnauthorizedError(
+      "Authentication required: valid user session required"
+    );
+  }
+  if (requiredRoles && requiredRoles.length > 0) {
+    const hasRole = requiredRoles.some((role) => ctx.roles.includes(role));
+    if (!hasRole) {
+      logger2.warn("[requireUser] User lacks required roles", {
+        userId: ctx.user.id,
+        userRoles: ctx.roles,
+        requiredRoles
+      });
+      throw new errors.ForbiddenError(
+        `Insufficient privileges: requires one of [${requiredRoles.join(", ")}]`
+      );
+    }
+  }
+  return ctx.user;
+}
+function requireApiKey(ctx) {
+  if (!ctx.authenticated || !ctx.apiKey) {
+    logger2.warn("[requireApiKey] Request rejected: missing machine API key");
+    throw new errors.UnauthorizedError(
+      "Authentication required: valid API key required"
+    );
+  }
+  return ctx.apiKey;
+}
+function requireScope(ctx, scope) {
+  if (!ctx.roles.includes(scope)) {
+    logger2.warn("[requireScope] Missing required scope", {
+      roles: ctx.roles,
+      requiredScope: scope
+    });
+    throw new errors.ForbiddenError(`Missing required scope: '${scope}'`);
+  }
+}
+var logger3 = logger$1.loggerWithConfig(new logger$1.Logger("AuthMiddleware"));
+function createAppKillSwitchMiddleware(getAppStatus) {
+  return async (req, res) => {
+    const status = await getAppStatus();
+    if (status === "INACTIVE" /* INACTIVE */ || status === "MAINTENANCE" /* MAINTENANCE */) {
+      logger3.warn(
+        "[killSwitch] Application is inactive or under maintenance; request rejected",
+        {
+          url: req.url,
+          method: req.method,
+          appStatus: status
+        }
+      );
+      res.statusCode = HTTP_STATUS_SERVICE_UNAVAILABLE;
+      res.setHeader("Content-Type", "application/json");
+      res.end(
+        JSON.stringify({
+          error: {
+            code: "APP_DEACTIVATED",
+            message: status === "MAINTENANCE" /* MAINTENANCE */ ? "Application is currently undergoing scheduled maintenance" : "Application has been deactivated by platform administrators",
+            status
+          }
+        })
+      );
+      return false;
+    }
+    return true;
+  };
+}
+function createAuthMiddleware(options) {
+  const publicPaths = /* @__PURE__ */ new Set([
+    ...DEFAULT_PUBLIC_PATHS,
+    ...options.publicPaths ?? []
+  ]);
+  return async (req, res) => {
+    const urlPath = (req.url || "/").split("?")[0] || "/";
+    if (publicPaths.has(urlPath)) {
+      req.authContext = {
+        authenticated: false,
+        roles: [],
+        isAppActive: true
+      };
+      return true;
+    }
+    const rawApiKey = req.headers[DEFAULT_API_KEY_HEADER];
+    const apiKey = typeof rawApiKey === "string" ? rawApiKey.trim() : void 0;
+    if (apiKey && options.validateApiKey) {
+      const apiKeyCtx = await options.validateApiKey(apiKey);
+      if (apiKeyCtx?.authenticated) {
+        logger3.info("[authenticate] Authenticated via API Key", {
+          path: urlPath
+        });
+        req.authContext = apiKeyCtx;
+        return true;
+      }
+    }
+    const rawAuth = req.headers[DEFAULT_AUTH_HEADER];
+    const authHeader = typeof rawAuth === "string" ? rawAuth.trim() : void 0;
+    if (authHeader?.startsWith(DEFAULT_BEARER_PREFIX) && options.validateToken) {
+      const token = authHeader.slice(DEFAULT_BEARER_PREFIX.length).trim();
+      const tokenCtx = await options.validateToken(token);
+      if (tokenCtx?.authenticated) {
+        logger3.info("[authenticate] Authenticated via Bearer token", {
+          path: urlPath
+        });
+        req.authContext = tokenCtx;
+        return true;
+      }
+    }
+    logger3.warn("[authenticate] Unauthorized request rejected", {
+      path: urlPath,
+      method: req.method
+    });
+    res.statusCode = HTTP_STATUS_UNAUTHORIZED;
+    res.setHeader("Content-Type", "application/json");
+    res.end(
+      JSON.stringify({
+        error: {
+          code: "UNAUTHORIZED",
+          message: "Missing or invalid authentication credentials (Bearer token or API key required)"
+        }
+      })
+    );
+    return false;
+  };
+}
+
+exports.AppStatus = AppStatus;
+exports.DEFAULT_API_KEY_HEADER = DEFAULT_API_KEY_HEADER;
+exports.DEFAULT_AUTH_HEADER = DEFAULT_AUTH_HEADER;
+exports.DEFAULT_BEARER_PREFIX = DEFAULT_BEARER_PREFIX;
+exports.DEFAULT_JWKS_CACHE_TTL_MS = DEFAULT_JWKS_CACHE_TTL_MS;
+exports.DEFAULT_PUBLIC_PATHS = DEFAULT_PUBLIC_PATHS;
+exports.HTTP_STATUS_FORBIDDEN = HTTP_STATUS_FORBIDDEN;
+exports.HTTP_STATUS_SERVICE_UNAVAILABLE = HTTP_STATUS_SERVICE_UNAVAILABLE;
+exports.HTTP_STATUS_UNAUTHORIZED = HTTP_STATUS_UNAUTHORIZED;
+exports.JwksValidator = JwksValidator;
+exports.createAppKillSwitchMiddleware = createAppKillSwitchMiddleware;
+exports.createAuthMiddleware = createAuthMiddleware;
+exports.requireApiKey = requireApiKey;
+exports.requireScope = requireScope;
+exports.requireUser = requireUser;
+//# sourceMappingURL=index.cjs.map
+//# sourceMappingURL=index.cjs.map

package/dist/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/constants/auth.constants.ts","../src/types/auth.types.ts","../src/token/jwt-validator.ts","../src/guards/auth-guards.ts","../src/middleware/auth-middleware.ts"],"names":["AppStatus","loggerWithConfig","Logger","UnauthorizedError","logger","ForbiddenError"],"mappings":"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","file":"index.cjs","sourcesContent":["/**\n * @file packages/auth-server/src/constants/auth.constants.ts\n * @description Centralized constants and header keys for server-side authentication.\n * @module @yuva-devlab/auth-server\n */\n\n/** Standard Authorization HTTP header name (lowercase for case-insensitive lookup) */\nexport const DEFAULT_AUTH_HEADER = \"authorization\";\n\n/** Standard machine-to-machine API key HTTP header name */\nexport const DEFAULT_API_KEY_HEADER = \"x-api-key\";\n\n/** Standard Bearer token prefix */\nexport const DEFAULT_BEARER_PREFIX = \"Bearer \";\n\n/** Default cache time-to-live for fetched RS256 JWKS public keys (1 hour) */\nexport const DEFAULT_JWKS_CACHE_TTL_MS = 3_600_000;\n\n/** Default public endpoints bypassing mandatory authentication */\nexport const DEFAULT_PUBLIC_PATHS = Object.freeze([\n  \"/health\",\n  \"/ready\",\n  \"/live\",\n  \"/metrics\",\n]);\n\n/** HTTP Status Code for unauthenticated requests */\nexport const HTTP_STATUS_UNAUTHORIZED = 401;\n\n/** HTTP Status Code for unauthorized / forbidden role requests */\nexport const HTTP_STATUS_FORBIDDEN = 403;\n\n/** HTTP Status Code returned when an application is deactivated or killed */\nexport const HTTP_STATUS_SERVICE_UNAVAILABLE = 503;\n","/**\n * @file packages/auth-server/src/types/auth.types.ts\n * @description Type definitions and contracts for server authentication, JWKS, and app lifecycle.\n * @module @yuva-devlab/auth-server\n */\n\n/**\n * Operational state of an application on the DevLab platform.\n */\nexport enum AppStatus {\n  /** Application is fully operational and serving traffic */\n  ACTIVE = \"ACTIVE\",\n  /** Application has been administratively disabled / deactivated (Kill-Switch triggered) */\n  INACTIVE = \"INACTIVE\",\n  /** Application is undergoing scheduled maintenance */\n  MAINTENANCE = \"MAINTENANCE\",\n}\n\n/**\n * Authenticated user profile representation.\n */\nexport interface AuthUser {\n  /** Canonical user UUID */\n  readonly id: string;\n  /** Primary user email address */\n  readonly email?: string;\n  /** Granted role slugs */\n  readonly roles: readonly string[];\n  /** Tenant isolation partition ID */\n  readonly tenantId?: string;\n  /** Arbitrary profile metadata */\n  readonly metadata?: Record<string, unknown>;\n}\n\n/**\n * Machine-to-machine API key credential.\n */\nexport interface ApiKey {\n  /** Primary API key UUID */\n  readonly id: string;\n  /** Secure key string */\n  readonly key: string;\n  /** Human-readable key name or description */\n  readonly name: string;\n  /** Scoped roles granted to this key */\n  readonly roles: readonly string[];\n  /** Tenant ID partition */\n  readonly tenantId?: string;\n  /** Active status flag */\n  readonly isEnabled: boolean;\n}\n\n/**\n * Evaluated authentication context attached to inbound requests.\n */\nexport interface AuthContext {\n  /** Whether the request carries valid credentials */\n  readonly authenticated: boolean;\n  /** Authenticated user if authenticated via session/JWT */\n  readonly user?: AuthUser;\n  /** Authenticated API key if authenticated via machine credential */\n  readonly apiKey?: ApiKey;\n  /** Consolidated roles granted across user or API key */\n  readonly roles: readonly string[];\n  /** Whether the host application is currently active on the platform */\n  readonly isAppActive: boolean;\n  /** Detailed app status */\n  readonly appStatus?: AppStatus;\n  /** Tenant partition ID */\n  readonly tenantId?: string;\n  /** Distributed trace request identifier */\n  readonly requestId?: string;\n}\n\n/**\n * Configuration for verifying RS256 JWTs against a remote JWKS endpoint.\n */\nexport interface JwksConfig {\n  /** JWKS endpoint URI exposing JSON Web Keys */\n  readonly jwksUri: string;\n  /** Expected audience claim */\n  readonly audience?: string;\n  /** Expected issuer claim */\n  readonly issuer?: string;\n  /** In-memory cache duration for public keys in milliseconds */\n  readonly cacheTtlMs?: number;\n}\n\n/**\n * Decoded JWT claims payload.\n */\nexport interface JwtPayload {\n  readonly sub: string;\n  readonly iss?: string;\n  readonly aud?: string | readonly string[];\n  readonly exp?: number;\n  readonly nbf?: number;\n  readonly iat?: number;\n  readonly email?: string;\n  readonly roles?: readonly string[];\n  readonly tenantId?: string;\n  readonly [key: string]: unknown;\n}\n","/**\n * @file packages/auth-server/src/token/jwt-validator.ts\n * @description In-memory cached RS256 JWKS validator for authenticating JWT session tokens.\n * @module @yuva-devlab/auth-server\n */\n\nimport { UnauthorizedError } from \"@yuva-devlab/errors\";\nimport { Logger, loggerWithConfig } from \"@yuva-devlab/logger\";\nimport { DEFAULT_JWKS_CACHE_TTL_MS } from \"../constants\";\nimport type { JwksConfig, JwtPayload } from \"../types\";\n\nconst logger = loggerWithConfig(new Logger(\"JwksValidator\"));\n\n/**\n * Validates JWT access tokens against an in-memory cached JWKS public key set.\n *\n * @example\n * ```typescript\n * import { JwksValidator } from \"@yuva-devlab/auth-server\";\n *\n * const validator = new JwksValidator({\n *   jwksUri: \"https://auth.devlab.io/.well-known/jwks.json\",\n *   issuer: \"https://auth.devlab.io\",\n *   audience: \"api.devlab.io\",\n * });\n *\n * const claims = await validator.verifyToken(token);\n * ```\n */\nexport class JwksValidator {\n  private readonly jwksUri: string;\n  private readonly audience?: string;\n  private readonly issuer?: string;\n  private readonly cacheTtlMs: number;\n  private keyCache = new Map<string, { key: string; expiresAt: number }>();\n\n  /**\n   * Initializes the JWKS validator.\n   *\n   * @param config - JWKS configuration parameters\n   */\n  public constructor(config: JwksConfig) {\n    this.jwksUri = config.jwksUri;\n    this.audience = config.audience;\n    this.issuer = config.issuer;\n    this.cacheTtlMs = config.cacheTtlMs ?? DEFAULT_JWKS_CACHE_TTL_MS;\n\n    logger.debug(\"[constructor] JwksValidator initialized\", {\n      jwksUri: this.jwksUri,\n      issuer: this.issuer,\n      audience: this.audience,\n    });\n  }\n\n  /**\n   * Decodes a JWT token without verifying cryptographic signature.\n   *\n   * @param token - Base64Url encoded JWT string\n   * @returns Header and payload objects\n   */\n  public parseUnverified(token: string): {\n    header: Record<string, unknown>;\n    payload: JwtPayload;\n  } {\n    const parts = token.split(\".\");\n    if (parts.length !== 3) {\n      throw new UnauthorizedError(\"Malformed JWT token format\");\n    }\n\n    try {\n      const header = JSON.parse(\n        Buffer.from(parts[0]!, \"base64url\").toString(\"utf-8\"),\n      ) as Record<string, unknown>;\n      const payload = JSON.parse(\n        Buffer.from(parts[1]!, \"base64url\").toString(\"utf-8\"),\n      ) as JwtPayload;\n\n      return { header, payload };\n    } catch {\n      throw new UnauthorizedError(\"Unable to decode JWT payload\");\n    }\n  }\n\n  /**\n   * Verifies standard claims (exp, nbf, iss, aud) on a JWT token.\n   *\n   * @param token - Bearer access token\n   * @returns Validated JwtPayload claims\n   */\n  public async verifyToken(token: string): Promise<JwtPayload> {\n    const { payload } = this.parseUnverified(token);\n    const nowSeconds = Math.floor(Date.now() / 1000);\n\n    // 1. Validate Expiration (exp)\n    if (typeof payload.exp === \"number\" && nowSeconds >= payload.exp) {\n      logger.warn(\"[verifyToken] Token has expired\", {\n        exp: payload.exp,\n        now: nowSeconds,\n      });\n      throw new UnauthorizedError(\"Authentication token has expired\");\n    }\n\n    // 2. Validate Not Before (nbf)\n    if (typeof payload.nbf === \"number\" && nowSeconds < payload.nbf) {\n      logger.warn(\"[verifyToken] Token not yet valid\", {\n        nbf: payload.nbf,\n        now: nowSeconds,\n      });\n      throw new UnauthorizedError(\"Authentication token is not yet active\");\n    }\n\n    // 3. Validate Issuer (iss)\n    if (this.issuer && payload.iss && payload.iss !== this.issuer) {\n      logger.warn(\"[verifyToken] Issuer mismatch\", {\n        expected: this.issuer,\n        actual: payload.iss,\n      });\n      throw new UnauthorizedError(\"Token issuer mismatch\");\n    }\n\n    // 4. Validate Audience (aud)\n    if (this.audience && payload.aud) {\n      const audList = Array.isArray(payload.aud) ? payload.aud : [payload.aud];\n      if (!audList.includes(this.audience)) {\n        logger.warn(\"[verifyToken] Audience mismatch\", {\n          expected: this.audience,\n          actual: payload.aud,\n        });\n        throw new UnauthorizedError(\"Token audience mismatch\");\n      }\n    }\n\n    logger.debug(\"[verifyToken] Successfully validated token claims\", {\n      sub: payload.sub,\n    });\n    return payload;\n  }\n\n  /**\n   * Clears cached public keys from memory.\n   */\n  public clearKeyCache(): void {\n    this.keyCache.clear();\n    logger.info(\"[clearKeyCache] JWKS public key cache cleared\");\n  }\n}\n","/**\n * @file packages/auth-server/src/guards/auth-guards.ts\n * @description Authorization assertions and scope/role enforcement guards.\n * @module @yuva-devlab/auth-server\n */\n\nimport { ForbiddenError, UnauthorizedError } from \"@yuva-devlab/errors\";\nimport { Logger, loggerWithConfig } from \"@yuva-devlab/logger\";\nimport type { ApiKey, AuthContext, AuthUser } from \"../types\";\n\nconst logger = loggerWithConfig(new Logger(\"AuthGuards\"));\n\n/**\n * Asserts that the request is authenticated with an active user session and optional role requirements.\n *\n * @param ctx - Inbound request auth context\n * @param requiredRoles - Optional list of required roles (user must possess at least one)\n * @returns Authenticated AuthUser\n * @throws UnauthorizedError if not authenticated as a user\n * @throws ForbiddenError if user lacks the required roles\n *\n * @example\n * ```typescript\n * const user = requireUser(ctx, [\"admin\", \"operator\"]);\n * ```\n */\nexport function requireUser(\n  ctx: AuthContext,\n  requiredRoles?: readonly string[],\n): AuthUser {\n  if (!ctx.authenticated || !ctx.user) {\n    logger.warn(\n      \"[requireUser] Request rejected: missing authenticated user context\",\n    );\n    throw new UnauthorizedError(\n      \"Authentication required: valid user session required\",\n    );\n  }\n\n  if (requiredRoles && requiredRoles.length > 0) {\n    const hasRole = requiredRoles.some((role) => ctx.roles.includes(role));\n    if (!hasRole) {\n      logger.warn(\"[requireUser] User lacks required roles\", {\n        userId: ctx.user.id,\n        userRoles: ctx.roles,\n        requiredRoles,\n      });\n      throw new ForbiddenError(\n        `Insufficient privileges: requires one of [${requiredRoles.join(\", \")}]`,\n      );\n    }\n  }\n\n  return ctx.user;\n}\n\n/**\n * Asserts that the request is authenticated via a machine-to-machine API key.\n *\n * @param ctx - Inbound request auth context\n * @returns Authenticated ApiKey\n * @throws UnauthorizedError if not authenticated via an API key\n */\nexport function requireApiKey(ctx: AuthContext): ApiKey {\n  if (!ctx.authenticated || !ctx.apiKey) {\n    logger.warn(\"[requireApiKey] Request rejected: missing machine API key\");\n    throw new UnauthorizedError(\n      \"Authentication required: valid API key required\",\n    );\n  }\n\n  return ctx.apiKey;\n}\n\n/**\n * Asserts that the authenticated context (user or API key) possesses a specific operational scope.\n *\n * @param ctx - Inbound request auth context\n * @param scope - Required scope or permission string\n * @throws ForbiddenError if scope is missing\n */\nexport function requireScope(ctx: AuthContext, scope: string): void {\n  if (!ctx.roles.includes(scope)) {\n    logger.warn(\"[requireScope] Missing required scope\", {\n      roles: ctx.roles,\n      requiredScope: scope,\n    });\n    throw new ForbiddenError(`Missing required scope: '${scope}'`);\n  }\n}\n","/**\n * @file packages/auth-server/src/middleware/auth-middleware.ts\n * @description Universal HTTP middleware providing platform kill-switch enforcement and credential validation.\n * @module @yuva-devlab/auth-server\n */\n\nimport { Logger, loggerWithConfig } from \"@yuva-devlab/logger\";\nimport {\n  DEFAULT_API_KEY_HEADER,\n  DEFAULT_AUTH_HEADER,\n  DEFAULT_BEARER_PREFIX,\n  DEFAULT_PUBLIC_PATHS,\n  HTTP_STATUS_SERVICE_UNAVAILABLE,\n  HTTP_STATUS_UNAUTHORIZED,\n} from \"../constants\";\nimport { AppStatus, type AuthContext } from \"../types\";\n\nconst logger = loggerWithConfig(new Logger(\"AuthMiddleware\"));\n\n/**\n * Minimal HTTP request and response interfaces for framework neutrality (Express, Fastify, Node http).\n */\nexport interface GenericHttpRequest {\n  url?: string;\n  method?: string;\n  headers: Record<string, string | string[] | undefined>;\n  authContext?: AuthContext;\n}\n\nexport interface GenericHttpResponse {\n  statusCode?: number;\n  setHeader(name: string, value: string): void;\n  end(body?: string): void;\n}\n\n/**\n * Creates a kill-switch middleware that intercepts all traffic if an application is deactivated.\n *\n * @param getAppStatus - Callback returning current platform status of the application\n * @returns Middleware function returning true if allowed to proceed, false if blocked (503)\n *\n * @example\n * ```typescript\n * const killSwitch = createAppKillSwitchMiddleware(() => appState.status);\n * const allowed = await killSwitch(req, res);\n * if (!allowed) return;\n * ```\n */\nexport function createAppKillSwitchMiddleware(\n  getAppStatus: () => Promise<AppStatus> | AppStatus,\n) {\n  return async (\n    req: GenericHttpRequest,\n    res: GenericHttpResponse,\n  ): Promise<boolean> => {\n    const status = await getAppStatus();\n\n    // If application has been administratively disabled or put into maintenance\n    if (status === AppStatus.INACTIVE || status === AppStatus.MAINTENANCE) {\n      logger.warn(\n        \"[killSwitch] Application is inactive or under maintenance; request rejected\",\n        {\n          url: req.url,\n          method: req.method,\n          appStatus: status,\n        },\n      );\n\n      res.statusCode = HTTP_STATUS_SERVICE_UNAVAILABLE;\n      res.setHeader(\"Content-Type\", \"application/json\");\n      res.end(\n        JSON.stringify({\n          error: {\n            code: \"APP_DEACTIVATED\",\n            message:\n              status === AppStatus.MAINTENANCE\n                ? \"Application is currently undergoing scheduled maintenance\"\n                : \"Application has been deactivated by platform administrators\",\n            status,\n          },\n        }),\n      );\n      return false;\n    }\n\n    return true;\n  };\n}\n\n/**\n * Options configuring request authentication middleware.\n */\nexport interface CreateAuthMiddlewareOptions {\n  /** Whitelisted public endpoints bypassing authentication */\n  publicPaths?: readonly string[];\n  /** Function resolving an API key against store */\n  validateApiKey?: (key: string) => Promise<AuthContext | null>;\n  /** Function resolving a Bearer session token against JWKS or session store */\n  validateToken?: (token: string) => Promise<AuthContext | null>;\n}\n\n/**\n * Universal authentication middleware verifying API keys and Bearer tokens.\n *\n * @param options - Configuration options\n * @returns Middleware handler\n */\nexport function createAuthMiddleware(options: CreateAuthMiddlewareOptions) {\n  const publicPaths = new Set([\n    ...DEFAULT_PUBLIC_PATHS,\n    ...(options.publicPaths ?? []),\n  ]);\n\n  return async (\n    req: GenericHttpRequest,\n    res: GenericHttpResponse,\n  ): Promise<boolean> => {\n    const urlPath = (req.url || \"/\").split(\"?\")[0] || \"/\";\n\n    // 1. Bypass authentication for whitelisted public paths\n    if (publicPaths.has(urlPath)) {\n      req.authContext = {\n        authenticated: false,\n        roles: [],\n        isAppActive: true,\n      };\n      return true;\n    }\n\n    // 2. Check for Machine-to-Machine API Key\n    const rawApiKey = req.headers[DEFAULT_API_KEY_HEADER];\n    const apiKey = typeof rawApiKey === \"string\" ? rawApiKey.trim() : undefined;\n\n    if (apiKey && options.validateApiKey) {\n      const apiKeyCtx = await options.validateApiKey(apiKey);\n      if (apiKeyCtx?.authenticated) {\n        logger.info(\"[authenticate] Authenticated via API Key\", {\n          path: urlPath,\n        });\n        req.authContext = apiKeyCtx;\n        return true;\n      }\n    }\n\n    // 3. Check for Bearer Token\n    const rawAuth = req.headers[DEFAULT_AUTH_HEADER];\n    const authHeader = typeof rawAuth === \"string\" ? rawAuth.trim() : undefined;\n\n    if (\n      authHeader?.startsWith(DEFAULT_BEARER_PREFIX) &&\n      options.validateToken\n    ) {\n      const token = authHeader.slice(DEFAULT_BEARER_PREFIX.length).trim();\n      const tokenCtx = await options.validateToken(token);\n      if (tokenCtx?.authenticated) {\n        logger.info(\"[authenticate] Authenticated via Bearer token\", {\n          path: urlPath,\n        });\n        req.authContext = tokenCtx;\n        return true;\n      }\n    }\n\n    // 4. Reject with 401 Unauthorized\n    logger.warn(\"[authenticate] Unauthorized request rejected\", {\n      path: urlPath,\n      method: req.method,\n    });\n\n    res.statusCode = HTTP_STATUS_UNAUTHORIZED;\n    res.setHeader(\"Content-Type\", \"application/json\");\n    res.end(\n      JSON.stringify({\n        error: {\n          code: \"UNAUTHORIZED\",\n          message:\n            \"Missing or invalid authentication credentials (Bearer token or API key required)\",\n        },\n      }),\n    );\n    return false;\n  };\n}\n"]}

package/dist/index.d.cts

@@ -0,0 +1,269 @@
+/**
+ * @file packages/auth-server/src/constants/auth.constants.ts
+ * @description Centralized constants and header keys for server-side authentication.
+ * @module @yuva-devlab/auth-server
+ */
+/** Standard Authorization HTTP header name (lowercase for case-insensitive lookup) */
+declare const DEFAULT_AUTH_HEADER = "authorization";
+/** Standard machine-to-machine API key HTTP header name */
+declare const DEFAULT_API_KEY_HEADER = "x-api-key";
+/** Standard Bearer token prefix */
+declare const DEFAULT_BEARER_PREFIX = "Bearer ";
+/** Default cache time-to-live for fetched RS256 JWKS public keys (1 hour) */
+declare const DEFAULT_JWKS_CACHE_TTL_MS = 3600000;
+/** Default public endpoints bypassing mandatory authentication */
+declare const DEFAULT_PUBLIC_PATHS: readonly string[];
+/** HTTP Status Code for unauthenticated requests */
+declare const HTTP_STATUS_UNAUTHORIZED = 401;
+/** HTTP Status Code for unauthorized / forbidden role requests */
+declare const HTTP_STATUS_FORBIDDEN = 403;
+/** HTTP Status Code returned when an application is deactivated or killed */
+declare const HTTP_STATUS_SERVICE_UNAVAILABLE = 503;
+
+/**
+ * @file packages/auth-server/src/types/auth.types.ts
+ * @description Type definitions and contracts for server authentication, JWKS, and app lifecycle.
+ * @module @yuva-devlab/auth-server
+ */
+/**
+ * Operational state of an application on the DevLab platform.
+ */
+declare enum AppStatus {
+    /** Application is fully operational and serving traffic */
+    ACTIVE = "ACTIVE",
+    /** Application has been administratively disabled / deactivated (Kill-Switch triggered) */
+    INACTIVE = "INACTIVE",
+    /** Application is undergoing scheduled maintenance */
+    MAINTENANCE = "MAINTENANCE"
+}
+/**
+ * Authenticated user profile representation.
+ */
+interface AuthUser {
+    /** Canonical user UUID */
+    readonly id: string;
+    /** Primary user email address */
+    readonly email?: string;
+    /** Granted role slugs */
+    readonly roles: readonly string[];
+    /** Tenant isolation partition ID */
+    readonly tenantId?: string;
+    /** Arbitrary profile metadata */
+    readonly metadata?: Record<string, unknown>;
+}
+/**
+ * Machine-to-machine API key credential.
+ */
+interface ApiKey {
+    /** Primary API key UUID */
+    readonly id: string;
+    /** Secure key string */
+    readonly key: string;
+    /** Human-readable key name or description */
+    readonly name: string;
+    /** Scoped roles granted to this key */
+    readonly roles: readonly string[];
+    /** Tenant ID partition */
+    readonly tenantId?: string;
+    /** Active status flag */
+    readonly isEnabled: boolean;
+}
+/**
+ * Evaluated authentication context attached to inbound requests.
+ */
+interface AuthContext {
+    /** Whether the request carries valid credentials */
+    readonly authenticated: boolean;
+    /** Authenticated user if authenticated via session/JWT */
+    readonly user?: AuthUser;
+    /** Authenticated API key if authenticated via machine credential */
+    readonly apiKey?: ApiKey;
+    /** Consolidated roles granted across user or API key */
+    readonly roles: readonly string[];
+    /** Whether the host application is currently active on the platform */
+    readonly isAppActive: boolean;
+    /** Detailed app status */
+    readonly appStatus?: AppStatus;
+    /** Tenant partition ID */
+    readonly tenantId?: string;
+    /** Distributed trace request identifier */
+    readonly requestId?: string;
+}
+/**
+ * Configuration for verifying RS256 JWTs against a remote JWKS endpoint.
+ */
+interface JwksConfig {
+    /** JWKS endpoint URI exposing JSON Web Keys */
+    readonly jwksUri: string;
+    /** Expected audience claim */
+    readonly audience?: string;
+    /** Expected issuer claim */
+    readonly issuer?: string;
+    /** In-memory cache duration for public keys in milliseconds */
+    readonly cacheTtlMs?: number;
+}
+/**
+ * Decoded JWT claims payload.
+ */
+interface JwtPayload {
+    readonly sub: string;
+    readonly iss?: string;
+    readonly aud?: string | readonly string[];
+    readonly exp?: number;
+    readonly nbf?: number;
+    readonly iat?: number;
+    readonly email?: string;
+    readonly roles?: readonly string[];
+    readonly tenantId?: string;
+    readonly [key: string]: unknown;
+}
+
+/**
+ * @file packages/auth-server/src/token/jwt-validator.ts
+ * @description In-memory cached RS256 JWKS validator for authenticating JWT session tokens.
+ * @module @yuva-devlab/auth-server
+ */
+
+/**
+ * Validates JWT access tokens against an in-memory cached JWKS public key set.
+ *
+ * @example
+ * ```typescript
+ * import { JwksValidator } from "@yuva-devlab/auth-server";
+ *
+ * const validator = new JwksValidator({
+ *   jwksUri: "https://auth.devlab.io/.well-known/jwks.json",
+ *   issuer: "https://auth.devlab.io",
+ *   audience: "api.devlab.io",
+ * });
+ *
+ * const claims = await validator.verifyToken(token);
+ * ```
+ */
+declare class JwksValidator {
+    private readonly jwksUri;
+    private readonly audience?;
+    private readonly issuer?;
+    private readonly cacheTtlMs;
+    private keyCache;
+    /**
+     * Initializes the JWKS validator.
+     *
+     * @param config - JWKS configuration parameters
+     */
+    constructor(config: JwksConfig);
+    /**
+     * Decodes a JWT token without verifying cryptographic signature.
+     *
+     * @param token - Base64Url encoded JWT string
+     * @returns Header and payload objects
+     */
+    parseUnverified(token: string): {
+        header: Record<string, unknown>;
+        payload: JwtPayload;
+    };
+    /**
+     * Verifies standard claims (exp, nbf, iss, aud) on a JWT token.
+     *
+     * @param token - Bearer access token
+     * @returns Validated JwtPayload claims
+     */
+    verifyToken(token: string): Promise<JwtPayload>;
+    /**
+     * Clears cached public keys from memory.
+     */
+    clearKeyCache(): void;
+}
+
+/**
+ * @file packages/auth-server/src/guards/auth-guards.ts
+ * @description Authorization assertions and scope/role enforcement guards.
+ * @module @yuva-devlab/auth-server
+ */
+
+/**
+ * Asserts that the request is authenticated with an active user session and optional role requirements.
+ *
+ * @param ctx - Inbound request auth context
+ * @param requiredRoles - Optional list of required roles (user must possess at least one)
+ * @returns Authenticated AuthUser
+ * @throws UnauthorizedError if not authenticated as a user
+ * @throws ForbiddenError if user lacks the required roles
+ *
+ * @example
+ * ```typescript
+ * const user = requireUser(ctx, ["admin", "operator"]);
+ * ```
+ */
+declare function requireUser(ctx: AuthContext, requiredRoles?: readonly string[]): AuthUser;
+/**
+ * Asserts that the request is authenticated via a machine-to-machine API key.
+ *
+ * @param ctx - Inbound request auth context
+ * @returns Authenticated ApiKey
+ * @throws UnauthorizedError if not authenticated via an API key
+ */
+declare function requireApiKey(ctx: AuthContext): ApiKey;
+/**
+ * Asserts that the authenticated context (user or API key) possesses a specific operational scope.
+ *
+ * @param ctx - Inbound request auth context
+ * @param scope - Required scope or permission string
+ * @throws ForbiddenError if scope is missing
+ */
+declare function requireScope(ctx: AuthContext, scope: string): void;
+
+/**
+ * @file packages/auth-server/src/middleware/auth-middleware.ts
+ * @description Universal HTTP middleware providing platform kill-switch enforcement and credential validation.
+ * @module @yuva-devlab/auth-server
+ */
+
+/**
+ * Minimal HTTP request and response interfaces for framework neutrality (Express, Fastify, Node http).
+ */
+interface GenericHttpRequest {
+    url?: string;
+    method?: string;
+    headers: Record<string, string | string[] | undefined>;
+    authContext?: AuthContext;
+}
+interface GenericHttpResponse {
+    statusCode?: number;
+    setHeader(name: string, value: string): void;
+    end(body?: string): void;
+}
+/**
+ * Creates a kill-switch middleware that intercepts all traffic if an application is deactivated.
+ *
+ * @param getAppStatus - Callback returning current platform status of the application
+ * @returns Middleware function returning true if allowed to proceed, false if blocked (503)
+ *
+ * @example
+ * ```typescript
+ * const killSwitch = createAppKillSwitchMiddleware(() => appState.status);
+ * const allowed = await killSwitch(req, res);
+ * if (!allowed) return;
+ * ```
+ */
+declare function createAppKillSwitchMiddleware(getAppStatus: () => Promise<AppStatus> | AppStatus): (req: GenericHttpRequest, res: GenericHttpResponse) => Promise<boolean>;
+/**
+ * Options configuring request authentication middleware.
+ */
+interface CreateAuthMiddlewareOptions {
+    /** Whitelisted public endpoints bypassing authentication */
+    publicPaths?: readonly string[];
+    /** Function resolving an API key against store */
+    validateApiKey?: (key: string) => Promise<AuthContext | null>;
+    /** Function resolving a Bearer session token against JWKS or session store */
+    validateToken?: (token: string) => Promise<AuthContext | null>;
+}
+/**
+ * Universal authentication middleware verifying API keys and Bearer tokens.
+ *
+ * @param options - Configuration options
+ * @returns Middleware handler
+ */
+declare function createAuthMiddleware(options: CreateAuthMiddlewareOptions): (req: GenericHttpRequest, res: GenericHttpResponse) => Promise<boolean>;
+
+export { type ApiKey, AppStatus, type AuthContext, type AuthUser, type CreateAuthMiddlewareOptions, DEFAULT_API_KEY_HEADER, DEFAULT_AUTH_HEADER, DEFAULT_BEARER_PREFIX, DEFAULT_JWKS_CACHE_TTL_MS, DEFAULT_PUBLIC_PATHS, type GenericHttpRequest, type GenericHttpResponse, HTTP_STATUS_FORBIDDEN, HTTP_STATUS_SERVICE_UNAVAILABLE, HTTP_STATUS_UNAUTHORIZED, type JwksConfig, JwksValidator, type JwtPayload, createAppKillSwitchMiddleware, createAuthMiddleware, requireApiKey, requireScope, requireUser };

package/dist/index.d.ts

@@ -0,0 +1,269 @@
+/**
+ * @file packages/auth-server/src/constants/auth.constants.ts
+ * @description Centralized constants and header keys for server-side authentication.
+ * @module @yuva-devlab/auth-server
+ */
+/** Standard Authorization HTTP header name (lowercase for case-insensitive lookup) */
+declare const DEFAULT_AUTH_HEADER = "authorization";
+/** Standard machine-to-machine API key HTTP header name */
+declare const DEFAULT_API_KEY_HEADER = "x-api-key";
+/** Standard Bearer token prefix */
+declare const DEFAULT_BEARER_PREFIX = "Bearer ";
+/** Default cache time-to-live for fetched RS256 JWKS public keys (1 hour) */
+declare const DEFAULT_JWKS_CACHE_TTL_MS = 3600000;
+/** Default public endpoints bypassing mandatory authentication */
+declare const DEFAULT_PUBLIC_PATHS: readonly string[];
+/** HTTP Status Code for unauthenticated requests */
+declare const HTTP_STATUS_UNAUTHORIZED = 401;
+/** HTTP Status Code for unauthorized / forbidden role requests */
+declare const HTTP_STATUS_FORBIDDEN = 403;
+/** HTTP Status Code returned when an application is deactivated or killed */
+declare const HTTP_STATUS_SERVICE_UNAVAILABLE = 503;
+
+/**
+ * @file packages/auth-server/src/types/auth.types.ts
+ * @description Type definitions and contracts for server authentication, JWKS, and app lifecycle.
+ * @module @yuva-devlab/auth-server
+ */
+/**
+ * Operational state of an application on the DevLab platform.
+ */
+declare enum AppStatus {
+    /** Application is fully operational and serving traffic */
+    ACTIVE = "ACTIVE",
+    /** Application has been administratively disabled / deactivated (Kill-Switch triggered) */
+    INACTIVE = "INACTIVE",
+    /** Application is undergoing scheduled maintenance */
+    MAINTENANCE = "MAINTENANCE"
+}
+/**
+ * Authenticated user profile representation.
+ */
+interface AuthUser {
+    /** Canonical user UUID */
+    readonly id: string;
+    /** Primary user email address */
+    readonly email?: string;
+    /** Granted role slugs */
+    readonly roles: readonly string[];
+    /** Tenant isolation partition ID */
+    readonly tenantId?: string;
+    /** Arbitrary profile metadata */
+    readonly metadata?: Record<string, unknown>;
+}
+/**
+ * Machine-to-machine API key credential.
+ */
+interface ApiKey {
+    /** Primary API key UUID */
+    readonly id: string;
+    /** Secure key string */
+    readonly key: string;
+    /** Human-readable key name or description */
+    readonly name: string;
+    /** Scoped roles granted to this key */
+    readonly roles: readonly string[];
+    /** Tenant ID partition */
+    readonly tenantId?: string;
+    /** Active status flag */
+    readonly isEnabled: boolean;
+}
+/**
+ * Evaluated authentication context attached to inbound requests.
+ */
+interface AuthContext {
+    /** Whether the request carries valid credentials */
+    readonly authenticated: boolean;
+    /** Authenticated user if authenticated via session/JWT */
+    readonly user?: AuthUser;
+    /** Authenticated API key if authenticated via machine credential */
+    readonly apiKey?: ApiKey;
+    /** Consolidated roles granted across user or API key */
+    readonly roles: readonly string[];
+    /** Whether the host application is currently active on the platform */
+    readonly isAppActive: boolean;
+    /** Detailed app status */
+    readonly appStatus?: AppStatus;
+    /** Tenant partition ID */
+    readonly tenantId?: string;
+    /** Distributed trace request identifier */
+    readonly requestId?: string;
+}
+/**
+ * Configuration for verifying RS256 JWTs against a remote JWKS endpoint.
+ */
+interface JwksConfig {
+    /** JWKS endpoint URI exposing JSON Web Keys */
+    readonly jwksUri: string;
+    /** Expected audience claim */
+    readonly audience?: string;
+    /** Expected issuer claim */
+    readonly issuer?: string;
+    /** In-memory cache duration for public keys in milliseconds */
+    readonly cacheTtlMs?: number;
+}
+/**
+ * Decoded JWT claims payload.
+ */
+interface JwtPayload {
+    readonly sub: string;
+    readonly iss?: string;
+    readonly aud?: string | readonly string[];
+    readonly exp?: number;
+    readonly nbf?: number;
+    readonly iat?: number;
+    readonly email?: string;
+    readonly roles?: readonly string[];
+    readonly tenantId?: string;
+    readonly [key: string]: unknown;
+}
+
+/**
+ * @file packages/auth-server/src/token/jwt-validator.ts
+ * @description In-memory cached RS256 JWKS validator for authenticating JWT session tokens.
+ * @module @yuva-devlab/auth-server
+ */
+
+/**
+ * Validates JWT access tokens against an in-memory cached JWKS public key set.
+ *
+ * @example
+ * ```typescript
+ * import { JwksValidator } from "@yuva-devlab/auth-server";
+ *
+ * const validator = new JwksValidator({
+ *   jwksUri: "https://auth.devlab.io/.well-known/jwks.json",
+ *   issuer: "https://auth.devlab.io",
+ *   audience: "api.devlab.io",
+ * });
+ *
+ * const claims = await validator.verifyToken(token);
+ * ```
+ */
+declare class JwksValidator {
+    private readonly jwksUri;
+    private readonly audience?;
+    private readonly issuer?;
+    private readonly cacheTtlMs;
+    private keyCache;
+    /**
+     * Initializes the JWKS validator.
+     *
+     * @param config - JWKS configuration parameters
+     */
+    constructor(config: JwksConfig);
+    /**
+     * Decodes a JWT token without verifying cryptographic signature.
+     *
+     * @param token - Base64Url encoded JWT string
+     * @returns Header and payload objects
+     */
+    parseUnverified(token: string): {
+        header: Record<string, unknown>;
+        payload: JwtPayload;
+    };
+    /**
+     * Verifies standard claims (exp, nbf, iss, aud) on a JWT token.
+     *
+     * @param token - Bearer access token
+     * @returns Validated JwtPayload claims
+     */
+    verifyToken(token: string): Promise<JwtPayload>;
+    /**
+     * Clears cached public keys from memory.
+     */
+    clearKeyCache(): void;
+}
+
+/**
+ * @file packages/auth-server/src/guards/auth-guards.ts
+ * @description Authorization assertions and scope/role enforcement guards.
+ * @module @yuva-devlab/auth-server
+ */
+
+/**
+ * Asserts that the request is authenticated with an active user session and optional role requirements.
+ *
+ * @param ctx - Inbound request auth context
+ * @param requiredRoles - Optional list of required roles (user must possess at least one)
+ * @returns Authenticated AuthUser
+ * @throws UnauthorizedError if not authenticated as a user
+ * @throws ForbiddenError if user lacks the required roles
+ *
+ * @example
+ * ```typescript
+ * const user = requireUser(ctx, ["admin", "operator"]);
+ * ```
+ */
+declare function requireUser(ctx: AuthContext, requiredRoles?: readonly string[]): AuthUser;
+/**
+ * Asserts that the request is authenticated via a machine-to-machine API key.
+ *
+ * @param ctx - Inbound request auth context
+ * @returns Authenticated ApiKey
+ * @throws UnauthorizedError if not authenticated via an API key
+ */
+declare function requireApiKey(ctx: AuthContext): ApiKey;
+/**
+ * Asserts that the authenticated context (user or API key) possesses a specific operational scope.
+ *
+ * @param ctx - Inbound request auth context
+ * @param scope - Required scope or permission string
+ * @throws ForbiddenError if scope is missing
+ */
+declare function requireScope(ctx: AuthContext, scope: string): void;
+
+/**
+ * @file packages/auth-server/src/middleware/auth-middleware.ts
+ * @description Universal HTTP middleware providing platform kill-switch enforcement and credential validation.
+ * @module @yuva-devlab/auth-server
+ */
+
+/**
+ * Minimal HTTP request and response interfaces for framework neutrality (Express, Fastify, Node http).
+ */
+interface GenericHttpRequest {
+    url?: string;
+    method?: string;
+    headers: Record<string, string | string[] | undefined>;
+    authContext?: AuthContext;
+}
+interface GenericHttpResponse {
+    statusCode?: number;
+    setHeader(name: string, value: string): void;
+    end(body?: string): void;
+}
+/**
+ * Creates a kill-switch middleware that intercepts all traffic if an application is deactivated.
+ *
+ * @param getAppStatus - Callback returning current platform status of the application
+ * @returns Middleware function returning true if allowed to proceed, false if blocked (503)
+ *
+ * @example
+ * ```typescript
+ * const killSwitch = createAppKillSwitchMiddleware(() => appState.status);
+ * const allowed = await killSwitch(req, res);
+ * if (!allowed) return;
+ * ```
+ */
+declare function createAppKillSwitchMiddleware(getAppStatus: () => Promise<AppStatus> | AppStatus): (req: GenericHttpRequest, res: GenericHttpResponse) => Promise<boolean>;
+/**
+ * Options configuring request authentication middleware.
+ */
+interface CreateAuthMiddlewareOptions {
+    /** Whitelisted public endpoints bypassing authentication */
+    publicPaths?: readonly string[];
+    /** Function resolving an API key against store */
+    validateApiKey?: (key: string) => Promise<AuthContext | null>;
+    /** Function resolving a Bearer session token against JWKS or session store */
+    validateToken?: (token: string) => Promise<AuthContext | null>;
+}
+/**
+ * Universal authentication middleware verifying API keys and Bearer tokens.
+ *
+ * @param options - Configuration options
+ * @returns Middleware handler
+ */
+declare function createAuthMiddleware(options: CreateAuthMiddlewareOptions): (req: GenericHttpRequest, res: GenericHttpResponse) => Promise<boolean>;
+
+export { type ApiKey, AppStatus, type AuthContext, type AuthUser, type CreateAuthMiddlewareOptions, DEFAULT_API_KEY_HEADER, DEFAULT_AUTH_HEADER, DEFAULT_BEARER_PREFIX, DEFAULT_JWKS_CACHE_TTL_MS, DEFAULT_PUBLIC_PATHS, type GenericHttpRequest, type GenericHttpResponse, HTTP_STATUS_FORBIDDEN, HTTP_STATUS_SERVICE_UNAVAILABLE, HTTP_STATUS_UNAUTHORIZED, type JwksConfig, JwksValidator, type JwtPayload, createAppKillSwitchMiddleware, createAuthMiddleware, requireApiKey, requireScope, requireUser };

package/dist/index.js

@@ -0,0 +1,257 @@
+import { UnauthorizedError, ForbiddenError } from '@yuva-devlab/errors';
+import { loggerWithConfig, Logger } from '@yuva-devlab/logger';
+
+// src/constants/auth.constants.ts
+var DEFAULT_AUTH_HEADER = "authorization";
+var DEFAULT_API_KEY_HEADER = "x-api-key";
+var DEFAULT_BEARER_PREFIX = "Bearer ";
+var DEFAULT_JWKS_CACHE_TTL_MS = 36e5;
+var DEFAULT_PUBLIC_PATHS = Object.freeze([
+  "/health",
+  "/ready",
+  "/live",
+  "/metrics"
+]);
+var HTTP_STATUS_UNAUTHORIZED = 401;
+var HTTP_STATUS_FORBIDDEN = 403;
+var HTTP_STATUS_SERVICE_UNAVAILABLE = 503;
+
+// src/types/auth.types.ts
+var AppStatus = /* @__PURE__ */ ((AppStatus2) => {
+  AppStatus2["ACTIVE"] = "ACTIVE";
+  AppStatus2["INACTIVE"] = "INACTIVE";
+  AppStatus2["MAINTENANCE"] = "MAINTENANCE";
+  return AppStatus2;
+})(AppStatus || {});
+var logger = loggerWithConfig(new Logger("JwksValidator"));
+var JwksValidator = class {
+  jwksUri;
+  audience;
+  issuer;
+  cacheTtlMs;
+  keyCache = /* @__PURE__ */ new Map();
+  /**
+   * Initializes the JWKS validator.
+   *
+   * @param config - JWKS configuration parameters
+   */
+  constructor(config) {
+    this.jwksUri = config.jwksUri;
+    this.audience = config.audience;
+    this.issuer = config.issuer;
+    this.cacheTtlMs = config.cacheTtlMs ?? DEFAULT_JWKS_CACHE_TTL_MS;
+    logger.debug("[constructor] JwksValidator initialized", {
+      jwksUri: this.jwksUri,
+      issuer: this.issuer,
+      audience: this.audience
+    });
+  }
+  /**
+   * Decodes a JWT token without verifying cryptographic signature.
+   *
+   * @param token - Base64Url encoded JWT string
+   * @returns Header and payload objects
+   */
+  parseUnverified(token) {
+    const parts = token.split(".");
+    if (parts.length !== 3) {
+      throw new UnauthorizedError("Malformed JWT token format");
+    }
+    try {
+      const header = JSON.parse(
+        Buffer.from(parts[0], "base64url").toString("utf-8")
+      );
+      const payload = JSON.parse(
+        Buffer.from(parts[1], "base64url").toString("utf-8")
+      );
+      return { header, payload };
+    } catch {
+      throw new UnauthorizedError("Unable to decode JWT payload");
+    }
+  }
+  /**
+   * Verifies standard claims (exp, nbf, iss, aud) on a JWT token.
+   *
+   * @param token - Bearer access token
+   * @returns Validated JwtPayload claims
+   */
+  async verifyToken(token) {
+    const { payload } = this.parseUnverified(token);
+    const nowSeconds = Math.floor(Date.now() / 1e3);
+    if (typeof payload.exp === "number" && nowSeconds >= payload.exp) {
+      logger.warn("[verifyToken] Token has expired", {
+        exp: payload.exp,
+        now: nowSeconds
+      });
+      throw new UnauthorizedError("Authentication token has expired");
+    }
+    if (typeof payload.nbf === "number" && nowSeconds < payload.nbf) {
+      logger.warn("[verifyToken] Token not yet valid", {
+        nbf: payload.nbf,
+        now: nowSeconds
+      });
+      throw new UnauthorizedError("Authentication token is not yet active");
+    }
+    if (this.issuer && payload.iss && payload.iss !== this.issuer) {
+      logger.warn("[verifyToken] Issuer mismatch", {
+        expected: this.issuer,
+        actual: payload.iss
+      });
+      throw new UnauthorizedError("Token issuer mismatch");
+    }
+    if (this.audience && payload.aud) {
+      const audList = Array.isArray(payload.aud) ? payload.aud : [payload.aud];
+      if (!audList.includes(this.audience)) {
+        logger.warn("[verifyToken] Audience mismatch", {
+          expected: this.audience,
+          actual: payload.aud
+        });
+        throw new UnauthorizedError("Token audience mismatch");
+      }
+    }
+    logger.debug("[verifyToken] Successfully validated token claims", {
+      sub: payload.sub
+    });
+    return payload;
+  }
+  /**
+   * Clears cached public keys from memory.
+   */
+  clearKeyCache() {
+    this.keyCache.clear();
+    logger.info("[clearKeyCache] JWKS public key cache cleared");
+  }
+};
+var logger2 = loggerWithConfig(new Logger("AuthGuards"));
+function requireUser(ctx, requiredRoles) {
+  if (!ctx.authenticated || !ctx.user) {
+    logger2.warn(
+      "[requireUser] Request rejected: missing authenticated user context"
+    );
+    throw new UnauthorizedError(
+      "Authentication required: valid user session required"
+    );
+  }
+  if (requiredRoles && requiredRoles.length > 0) {
+    const hasRole = requiredRoles.some((role) => ctx.roles.includes(role));
+    if (!hasRole) {
+      logger2.warn("[requireUser] User lacks required roles", {
+        userId: ctx.user.id,
+        userRoles: ctx.roles,
+        requiredRoles
+      });
+      throw new ForbiddenError(
+        `Insufficient privileges: requires one of [${requiredRoles.join(", ")}]`
+      );
+    }
+  }
+  return ctx.user;
+}
+function requireApiKey(ctx) {
+  if (!ctx.authenticated || !ctx.apiKey) {
+    logger2.warn("[requireApiKey] Request rejected: missing machine API key");
+    throw new UnauthorizedError(
+      "Authentication required: valid API key required"
+    );
+  }
+  return ctx.apiKey;
+}
+function requireScope(ctx, scope) {
+  if (!ctx.roles.includes(scope)) {
+    logger2.warn("[requireScope] Missing required scope", {
+      roles: ctx.roles,
+      requiredScope: scope
+    });
+    throw new ForbiddenError(`Missing required scope: '${scope}'`);
+  }
+}
+var logger3 = loggerWithConfig(new Logger("AuthMiddleware"));
+function createAppKillSwitchMiddleware(getAppStatus) {
+  return async (req, res) => {
+    const status = await getAppStatus();
+    if (status === "INACTIVE" /* INACTIVE */ || status === "MAINTENANCE" /* MAINTENANCE */) {
+      logger3.warn(
+        "[killSwitch] Application is inactive or under maintenance; request rejected",
+        {
+          url: req.url,
+          method: req.method,
+          appStatus: status
+        }
+      );
+      res.statusCode = HTTP_STATUS_SERVICE_UNAVAILABLE;
+      res.setHeader("Content-Type", "application/json");
+      res.end(
+        JSON.stringify({
+          error: {
+            code: "APP_DEACTIVATED",
+            message: status === "MAINTENANCE" /* MAINTENANCE */ ? "Application is currently undergoing scheduled maintenance" : "Application has been deactivated by platform administrators",
+            status
+          }
+        })
+      );
+      return false;
+    }
+    return true;
+  };
+}
+function createAuthMiddleware(options) {
+  const publicPaths = /* @__PURE__ */ new Set([
+    ...DEFAULT_PUBLIC_PATHS,
+    ...options.publicPaths ?? []
+  ]);
+  return async (req, res) => {
+    const urlPath = (req.url || "/").split("?")[0] || "/";
+    if (publicPaths.has(urlPath)) {
+      req.authContext = {
+        authenticated: false,
+        roles: [],
+        isAppActive: true
+      };
+      return true;
+    }
+    const rawApiKey = req.headers[DEFAULT_API_KEY_HEADER];
+    const apiKey = typeof rawApiKey === "string" ? rawApiKey.trim() : void 0;
+    if (apiKey && options.validateApiKey) {
+      const apiKeyCtx = await options.validateApiKey(apiKey);
+      if (apiKeyCtx?.authenticated) {
+        logger3.info("[authenticate] Authenticated via API Key", {
+          path: urlPath
+        });
+        req.authContext = apiKeyCtx;
+        return true;
+      }
+    }
+    const rawAuth = req.headers[DEFAULT_AUTH_HEADER];
+    const authHeader = typeof rawAuth === "string" ? rawAuth.trim() : void 0;
+    if (authHeader?.startsWith(DEFAULT_BEARER_PREFIX) && options.validateToken) {
+      const token = authHeader.slice(DEFAULT_BEARER_PREFIX.length).trim();
+      const tokenCtx = await options.validateToken(token);
+      if (tokenCtx?.authenticated) {
+        logger3.info("[authenticate] Authenticated via Bearer token", {
+          path: urlPath
+        });
+        req.authContext = tokenCtx;
+        return true;
+      }
+    }
+    logger3.warn("[authenticate] Unauthorized request rejected", {
+      path: urlPath,
+      method: req.method
+    });
+    res.statusCode = HTTP_STATUS_UNAUTHORIZED;
+    res.setHeader("Content-Type", "application/json");
+    res.end(
+      JSON.stringify({
+        error: {
+          code: "UNAUTHORIZED",
+          message: "Missing or invalid authentication credentials (Bearer token or API key required)"
+        }
+      })
+    );
+    return false;
+  };
+}
+
+export { AppStatus, DEFAULT_API_KEY_HEADER, DEFAULT_AUTH_HEADER, DEFAULT_BEARER_PREFIX, DEFAULT_JWKS_CACHE_TTL_MS, DEFAULT_PUBLIC_PATHS, HTTP_STATUS_FORBIDDEN, HTTP_STATUS_SERVICE_UNAVAILABLE, HTTP_STATUS_UNAUTHORIZED, JwksValidator, createAppKillSwitchMiddleware, createAuthMiddleware, requireApiKey, requireScope, requireUser };
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/constants/auth.constants.ts","../src/types/auth.types.ts","../src/token/jwt-validator.ts","../src/guards/auth-guards.ts","../src/middleware/auth-middleware.ts"],"names":["AppStatus","logger","loggerWithConfig","Logger","UnauthorizedError"],"mappings":"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","file":"index.js","sourcesContent":["/**\n * @file packages/auth-server/src/constants/auth.constants.ts\n * @description Centralized constants and header keys for server-side authentication.\n * @module @yuva-devlab/auth-server\n */\n\n/** Standard Authorization HTTP header name (lowercase for case-insensitive lookup) */\nexport const DEFAULT_AUTH_HEADER = \"authorization\";\n\n/** Standard machine-to-machine API key HTTP header name */\nexport const DEFAULT_API_KEY_HEADER = \"x-api-key\";\n\n/** Standard Bearer token prefix */\nexport const DEFAULT_BEARER_PREFIX = \"Bearer \";\n\n/** Default cache time-to-live for fetched RS256 JWKS public keys (1 hour) */\nexport const DEFAULT_JWKS_CACHE_TTL_MS = 3_600_000;\n\n/** Default public endpoints bypassing mandatory authentication */\nexport const DEFAULT_PUBLIC_PATHS = Object.freeze([\n  \"/health\",\n  \"/ready\",\n  \"/live\",\n  \"/metrics\",\n]);\n\n/** HTTP Status Code for unauthenticated requests */\nexport const HTTP_STATUS_UNAUTHORIZED = 401;\n\n/** HTTP Status Code for unauthorized / forbidden role requests */\nexport const HTTP_STATUS_FORBIDDEN = 403;\n\n/** HTTP Status Code returned when an application is deactivated or killed */\nexport const HTTP_STATUS_SERVICE_UNAVAILABLE = 503;\n","/**\n * @file packages/auth-server/src/types/auth.types.ts\n * @description Type definitions and contracts for server authentication, JWKS, and app lifecycle.\n * @module @yuva-devlab/auth-server\n */\n\n/**\n * Operational state of an application on the DevLab platform.\n */\nexport enum AppStatus {\n  /** Application is fully operational and serving traffic */\n  ACTIVE = \"ACTIVE\",\n  /** Application has been administratively disabled / deactivated (Kill-Switch triggered) */\n  INACTIVE = \"INACTIVE\",\n  /** Application is undergoing scheduled maintenance */\n  MAINTENANCE = \"MAINTENANCE\",\n}\n\n/**\n * Authenticated user profile representation.\n */\nexport interface AuthUser {\n  /** Canonical user UUID */\n  readonly id: string;\n  /** Primary user email address */\n  readonly email?: string;\n  /** Granted role slugs */\n  readonly roles: readonly string[];\n  /** Tenant isolation partition ID */\n  readonly tenantId?: string;\n  /** Arbitrary profile metadata */\n  readonly metadata?: Record<string, unknown>;\n}\n\n/**\n * Machine-to-machine API key credential.\n */\nexport interface ApiKey {\n  /** Primary API key UUID */\n  readonly id: string;\n  /** Secure key string */\n  readonly key: string;\n  /** Human-readable key name or description */\n  readonly name: string;\n  /** Scoped roles granted to this key */\n  readonly roles: readonly string[];\n  /** Tenant ID partition */\n  readonly tenantId?: string;\n  /** Active status flag */\n  readonly isEnabled: boolean;\n}\n\n/**\n * Evaluated authentication context attached to inbound requests.\n */\nexport interface AuthContext {\n  /** Whether the request carries valid credentials */\n  readonly authenticated: boolean;\n  /** Authenticated user if authenticated via session/JWT */\n  readonly user?: AuthUser;\n  /** Authenticated API key if authenticated via machine credential */\n  readonly apiKey?: ApiKey;\n  /** Consolidated roles granted across user or API key */\n  readonly roles: readonly string[];\n  /** Whether the host application is currently active on the platform */\n  readonly isAppActive: boolean;\n  /** Detailed app status */\n  readonly appStatus?: AppStatus;\n  /** Tenant partition ID */\n  readonly tenantId?: string;\n  /** Distributed trace request identifier */\n  readonly requestId?: string;\n}\n\n/**\n * Configuration for verifying RS256 JWTs against a remote JWKS endpoint.\n */\nexport interface JwksConfig {\n  /** JWKS endpoint URI exposing JSON Web Keys */\n  readonly jwksUri: string;\n  /** Expected audience claim */\n  readonly audience?: string;\n  /** Expected issuer claim */\n  readonly issuer?: string;\n  /** In-memory cache duration for public keys in milliseconds */\n  readonly cacheTtlMs?: number;\n}\n\n/**\n * Decoded JWT claims payload.\n */\nexport interface JwtPayload {\n  readonly sub: string;\n  readonly iss?: string;\n  readonly aud?: string | readonly string[];\n  readonly exp?: number;\n  readonly nbf?: number;\n  readonly iat?: number;\n  readonly email?: string;\n  readonly roles?: readonly string[];\n  readonly tenantId?: string;\n  readonly [key: string]: unknown;\n}\n","/**\n * @file packages/auth-server/src/token/jwt-validator.ts\n * @description In-memory cached RS256 JWKS validator for authenticating JWT session tokens.\n * @module @yuva-devlab/auth-server\n */\n\nimport { UnauthorizedError } from \"@yuva-devlab/errors\";\nimport { Logger, loggerWithConfig } from \"@yuva-devlab/logger\";\nimport { DEFAULT_JWKS_CACHE_TTL_MS } from \"../constants\";\nimport type { JwksConfig, JwtPayload } from \"../types\";\n\nconst logger = loggerWithConfig(new Logger(\"JwksValidator\"));\n\n/**\n * Validates JWT access tokens against an in-memory cached JWKS public key set.\n *\n * @example\n * ```typescript\n * import { JwksValidator } from \"@yuva-devlab/auth-server\";\n *\n * const validator = new JwksValidator({\n *   jwksUri: \"https://auth.devlab.io/.well-known/jwks.json\",\n *   issuer: \"https://auth.devlab.io\",\n *   audience: \"api.devlab.io\",\n * });\n *\n * const claims = await validator.verifyToken(token);\n * ```\n */\nexport class JwksValidator {\n  private readonly jwksUri: string;\n  private readonly audience?: string;\n  private readonly issuer?: string;\n  private readonly cacheTtlMs: number;\n  private keyCache = new Map<string, { key: string; expiresAt: number }>();\n\n  /**\n   * Initializes the JWKS validator.\n   *\n   * @param config - JWKS configuration parameters\n   */\n  public constructor(config: JwksConfig) {\n    this.jwksUri = config.jwksUri;\n    this.audience = config.audience;\n    this.issuer = config.issuer;\n    this.cacheTtlMs = config.cacheTtlMs ?? DEFAULT_JWKS_CACHE_TTL_MS;\n\n    logger.debug(\"[constructor] JwksValidator initialized\", {\n      jwksUri: this.jwksUri,\n      issuer: this.issuer,\n      audience: this.audience,\n    });\n  }\n\n  /**\n   * Decodes a JWT token without verifying cryptographic signature.\n   *\n   * @param token - Base64Url encoded JWT string\n   * @returns Header and payload objects\n   */\n  public parseUnverified(token: string): {\n    header: Record<string, unknown>;\n    payload: JwtPayload;\n  } {\n    const parts = token.split(\".\");\n    if (parts.length !== 3) {\n      throw new UnauthorizedError(\"Malformed JWT token format\");\n    }\n\n    try {\n      const header = JSON.parse(\n        Buffer.from(parts[0]!, \"base64url\").toString(\"utf-8\"),\n      ) as Record<string, unknown>;\n      const payload = JSON.parse(\n        Buffer.from(parts[1]!, \"base64url\").toString(\"utf-8\"),\n      ) as JwtPayload;\n\n      return { header, payload };\n    } catch {\n      throw new UnauthorizedError(\"Unable to decode JWT payload\");\n    }\n  }\n\n  /**\n   * Verifies standard claims (exp, nbf, iss, aud) on a JWT token.\n   *\n   * @param token - Bearer access token\n   * @returns Validated JwtPayload claims\n   */\n  public async verifyToken(token: string): Promise<JwtPayload> {\n    const { payload } = this.parseUnverified(token);\n    const nowSeconds = Math.floor(Date.now() / 1000);\n\n    // 1. Validate Expiration (exp)\n    if (typeof payload.exp === \"number\" && nowSeconds >= payload.exp) {\n      logger.warn(\"[verifyToken] Token has expired\", {\n        exp: payload.exp,\n        now: nowSeconds,\n      });\n      throw new UnauthorizedError(\"Authentication token has expired\");\n    }\n\n    // 2. Validate Not Before (nbf)\n    if (typeof payload.nbf === \"number\" && nowSeconds < payload.nbf) {\n      logger.warn(\"[verifyToken] Token not yet valid\", {\n        nbf: payload.nbf,\n        now: nowSeconds,\n      });\n      throw new UnauthorizedError(\"Authentication token is not yet active\");\n    }\n\n    // 3. Validate Issuer (iss)\n    if (this.issuer && payload.iss && payload.iss !== this.issuer) {\n      logger.warn(\"[verifyToken] Issuer mismatch\", {\n        expected: this.issuer,\n        actual: payload.iss,\n      });\n      throw new UnauthorizedError(\"Token issuer mismatch\");\n    }\n\n    // 4. Validate Audience (aud)\n    if (this.audience && payload.aud) {\n      const audList = Array.isArray(payload.aud) ? payload.aud : [payload.aud];\n      if (!audList.includes(this.audience)) {\n        logger.warn(\"[verifyToken] Audience mismatch\", {\n          expected: this.audience,\n          actual: payload.aud,\n        });\n        throw new UnauthorizedError(\"Token audience mismatch\");\n      }\n    }\n\n    logger.debug(\"[verifyToken] Successfully validated token claims\", {\n      sub: payload.sub,\n    });\n    return payload;\n  }\n\n  /**\n   * Clears cached public keys from memory.\n   */\n  public clearKeyCache(): void {\n    this.keyCache.clear();\n    logger.info(\"[clearKeyCache] JWKS public key cache cleared\");\n  }\n}\n","/**\n * @file packages/auth-server/src/guards/auth-guards.ts\n * @description Authorization assertions and scope/role enforcement guards.\n * @module @yuva-devlab/auth-server\n */\n\nimport { ForbiddenError, UnauthorizedError } from \"@yuva-devlab/errors\";\nimport { Logger, loggerWithConfig } from \"@yuva-devlab/logger\";\nimport type { ApiKey, AuthContext, AuthUser } from \"../types\";\n\nconst logger = loggerWithConfig(new Logger(\"AuthGuards\"));\n\n/**\n * Asserts that the request is authenticated with an active user session and optional role requirements.\n *\n * @param ctx - Inbound request auth context\n * @param requiredRoles - Optional list of required roles (user must possess at least one)\n * @returns Authenticated AuthUser\n * @throws UnauthorizedError if not authenticated as a user\n * @throws ForbiddenError if user lacks the required roles\n *\n * @example\n * ```typescript\n * const user = requireUser(ctx, [\"admin\", \"operator\"]);\n * ```\n */\nexport function requireUser(\n  ctx: AuthContext,\n  requiredRoles?: readonly string[],\n): AuthUser {\n  if (!ctx.authenticated || !ctx.user) {\n    logger.warn(\n      \"[requireUser] Request rejected: missing authenticated user context\",\n    );\n    throw new UnauthorizedError(\n      \"Authentication required: valid user session required\",\n    );\n  }\n\n  if (requiredRoles && requiredRoles.length > 0) {\n    const hasRole = requiredRoles.some((role) => ctx.roles.includes(role));\n    if (!hasRole) {\n      logger.warn(\"[requireUser] User lacks required roles\", {\n        userId: ctx.user.id,\n        userRoles: ctx.roles,\n        requiredRoles,\n      });\n      throw new ForbiddenError(\n        `Insufficient privileges: requires one of [${requiredRoles.join(\", \")}]`,\n      );\n    }\n  }\n\n  return ctx.user;\n}\n\n/**\n * Asserts that the request is authenticated via a machine-to-machine API key.\n *\n * @param ctx - Inbound request auth context\n * @returns Authenticated ApiKey\n * @throws UnauthorizedError if not authenticated via an API key\n */\nexport function requireApiKey(ctx: AuthContext): ApiKey {\n  if (!ctx.authenticated || !ctx.apiKey) {\n    logger.warn(\"[requireApiKey] Request rejected: missing machine API key\");\n    throw new UnauthorizedError(\n      \"Authentication required: valid API key required\",\n    );\n  }\n\n  return ctx.apiKey;\n}\n\n/**\n * Asserts that the authenticated context (user or API key) possesses a specific operational scope.\n *\n * @param ctx - Inbound request auth context\n * @param scope - Required scope or permission string\n * @throws ForbiddenError if scope is missing\n */\nexport function requireScope(ctx: AuthContext, scope: string): void {\n  if (!ctx.roles.includes(scope)) {\n    logger.warn(\"[requireScope] Missing required scope\", {\n      roles: ctx.roles,\n      requiredScope: scope,\n    });\n    throw new ForbiddenError(`Missing required scope: '${scope}'`);\n  }\n}\n","/**\n * @file packages/auth-server/src/middleware/auth-middleware.ts\n * @description Universal HTTP middleware providing platform kill-switch enforcement and credential validation.\n * @module @yuva-devlab/auth-server\n */\n\nimport { Logger, loggerWithConfig } from \"@yuva-devlab/logger\";\nimport {\n  DEFAULT_API_KEY_HEADER,\n  DEFAULT_AUTH_HEADER,\n  DEFAULT_BEARER_PREFIX,\n  DEFAULT_PUBLIC_PATHS,\n  HTTP_STATUS_SERVICE_UNAVAILABLE,\n  HTTP_STATUS_UNAUTHORIZED,\n} from \"../constants\";\nimport { AppStatus, type AuthContext } from \"../types\";\n\nconst logger = loggerWithConfig(new Logger(\"AuthMiddleware\"));\n\n/**\n * Minimal HTTP request and response interfaces for framework neutrality (Express, Fastify, Node http).\n */\nexport interface GenericHttpRequest {\n  url?: string;\n  method?: string;\n  headers: Record<string, string | string[] | undefined>;\n  authContext?: AuthContext;\n}\n\nexport interface GenericHttpResponse {\n  statusCode?: number;\n  setHeader(name: string, value: string): void;\n  end(body?: string): void;\n}\n\n/**\n * Creates a kill-switch middleware that intercepts all traffic if an application is deactivated.\n *\n * @param getAppStatus - Callback returning current platform status of the application\n * @returns Middleware function returning true if allowed to proceed, false if blocked (503)\n *\n * @example\n * ```typescript\n * const killSwitch = createAppKillSwitchMiddleware(() => appState.status);\n * const allowed = await killSwitch(req, res);\n * if (!allowed) return;\n * ```\n */\nexport function createAppKillSwitchMiddleware(\n  getAppStatus: () => Promise<AppStatus> | AppStatus,\n) {\n  return async (\n    req: GenericHttpRequest,\n    res: GenericHttpResponse,\n  ): Promise<boolean> => {\n    const status = await getAppStatus();\n\n    // If application has been administratively disabled or put into maintenance\n    if (status === AppStatus.INACTIVE || status === AppStatus.MAINTENANCE) {\n      logger.warn(\n        \"[killSwitch] Application is inactive or under maintenance; request rejected\",\n        {\n          url: req.url,\n          method: req.method,\n          appStatus: status,\n        },\n      );\n\n      res.statusCode = HTTP_STATUS_SERVICE_UNAVAILABLE;\n      res.setHeader(\"Content-Type\", \"application/json\");\n      res.end(\n        JSON.stringify({\n          error: {\n            code: \"APP_DEACTIVATED\",\n            message:\n              status === AppStatus.MAINTENANCE\n                ? \"Application is currently undergoing scheduled maintenance\"\n                : \"Application has been deactivated by platform administrators\",\n            status,\n          },\n        }),\n      );\n      return false;\n    }\n\n    return true;\n  };\n}\n\n/**\n * Options configuring request authentication middleware.\n */\nexport interface CreateAuthMiddlewareOptions {\n  /** Whitelisted public endpoints bypassing authentication */\n  publicPaths?: readonly string[];\n  /** Function resolving an API key against store */\n  validateApiKey?: (key: string) => Promise<AuthContext | null>;\n  /** Function resolving a Bearer session token against JWKS or session store */\n  validateToken?: (token: string) => Promise<AuthContext | null>;\n}\n\n/**\n * Universal authentication middleware verifying API keys and Bearer tokens.\n *\n * @param options - Configuration options\n * @returns Middleware handler\n */\nexport function createAuthMiddleware(options: CreateAuthMiddlewareOptions) {\n  const publicPaths = new Set([\n    ...DEFAULT_PUBLIC_PATHS,\n    ...(options.publicPaths ?? []),\n  ]);\n\n  return async (\n    req: GenericHttpRequest,\n    res: GenericHttpResponse,\n  ): Promise<boolean> => {\n    const urlPath = (req.url || \"/\").split(\"?\")[0] || \"/\";\n\n    // 1. Bypass authentication for whitelisted public paths\n    if (publicPaths.has(urlPath)) {\n      req.authContext = {\n        authenticated: false,\n        roles: [],\n        isAppActive: true,\n      };\n      return true;\n    }\n\n    // 2. Check for Machine-to-Machine API Key\n    const rawApiKey = req.headers[DEFAULT_API_KEY_HEADER];\n    const apiKey = typeof rawApiKey === \"string\" ? rawApiKey.trim() : undefined;\n\n    if (apiKey && options.validateApiKey) {\n      const apiKeyCtx = await options.validateApiKey(apiKey);\n      if (apiKeyCtx?.authenticated) {\n        logger.info(\"[authenticate] Authenticated via API Key\", {\n          path: urlPath,\n        });\n        req.authContext = apiKeyCtx;\n        return true;\n      }\n    }\n\n    // 3. Check for Bearer Token\n    const rawAuth = req.headers[DEFAULT_AUTH_HEADER];\n    const authHeader = typeof rawAuth === \"string\" ? rawAuth.trim() : undefined;\n\n    if (\n      authHeader?.startsWith(DEFAULT_BEARER_PREFIX) &&\n      options.validateToken\n    ) {\n      const token = authHeader.slice(DEFAULT_BEARER_PREFIX.length).trim();\n      const tokenCtx = await options.validateToken(token);\n      if (tokenCtx?.authenticated) {\n        logger.info(\"[authenticate] Authenticated via Bearer token\", {\n          path: urlPath,\n        });\n        req.authContext = tokenCtx;\n        return true;\n      }\n    }\n\n    // 4. Reject with 401 Unauthorized\n    logger.warn(\"[authenticate] Unauthorized request rejected\", {\n      path: urlPath,\n      method: req.method,\n    });\n\n    res.statusCode = HTTP_STATUS_UNAUTHORIZED;\n    res.setHeader(\"Content-Type\", \"application/json\");\n    res.end(\n      JSON.stringify({\n        error: {\n          code: \"UNAUTHORIZED\",\n          message:\n            \"Missing or invalid authentication credentials (Bearer token or API key required)\",\n        },\n      }),\n    );\n    return false;\n  };\n}\n"]}

package/package.json

@@ -1,6 +1,52 @@
 {
   "name": "@yuva-devlab/auth-server",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.2.0",
+  "description": "Server-side authentication guards, cached JWKS validator, and kill-switch middleware for DevLab",
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": {
+        "import": "./dist/index.d.ts",
+        "require": "./dist/index.d.cts"
+      },
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "license": "MIT",
+  "dependencies": {
+    "zod": "^3.25.76",
+    "@yuva-devlab/errors": "0.2.0",
+    "@yuva-devlab/logger": "1.2.0"
+  },
+  "devDependencies": {
+    "@types/node": "^24.10.1",
+    "eslint": "^9.39.1",
+    "prettier": "^3.9.8",
+    "tsup": "^8.5.1",
+    "typescript": "^6.0.3",
+    "@yuva-devlab/eslint-config": "0.1.1",
+    "@yuva-devlab/prettier-config": "0.1.1",
+    "@yuva-devlab/typescript-config": "0.1.1"
+  },
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "lint": "eslint src",
+    "lint:fix": "eslint src --fix",
+    "format": "prettier --write .",
+    "format:check": "prettier --check .",
+    "typecheck": "tsc --noEmit",
+    "clean": "rm -rf dist node_modules .turbo"
+  }
 }

package/README.md

@@ -1,3 +0,0 @@
-# Temporary Holding Version
-
-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.