@discover-cloud/shared 1.2.9 → 1.3.0

package/dist/middleware/require-workspace-permission.middleware.d.ts

@@ -0,0 +1,20 @@
+/**
+ * @file require-workspace-permission.middleware.ts
+ * @description Express middleware factory to enforce workspace-scoped permission checks.
+ */
+import { RequestHandler } from "express";
+import { Permission } from "../enums";
+import { PermissionCacheService } from "../authorization/permission-cache.service";
+/**
+ * Creates requireWorkspacePermission middleware factory.
+ *
+ * @param {PermissionCacheService} permissionCache - Shared Redis cache service.
+ * @param {(accountId: string, workspaceId: string) => Promise<string[]>} resolveFn
+ *   - Function called on a cache miss to fetch the caller's permission strings for the workspace.
+ * @returns {object} Workspace permission middlewares.
+ */
+export declare const createRequireWorkspacePermission: (permissionCache: PermissionCacheService, resolveFn: (accountId: string, workspaceId: string) => Promise<string[]>) => {
+    requireWorkspacePermission: (permission: Permission) => RequestHandler;
+    requireAnyWorkspacePermission: (...permissions: Permission[]) => RequestHandler;
+    requireAllWorkspacePermissions: (...permissions: Permission[]) => RequestHandler;
+};

package/dist/middleware/require-workspace-permission.middleware.js

@@ -0,0 +1,114 @@
+"use strict";
+/**
+ * @file require-workspace-permission.middleware.ts
+ * @description Express middleware factory to enforce workspace-scoped permission checks.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createRequireWorkspacePermission = void 0;
+const permission_checker_1 = require("../authorization/permission-checker");
+const utils_1 = require("../utils");
+/**
+ * Creates requireWorkspacePermission middleware factory.
+ *
+ * @param {PermissionCacheService} permissionCache - Shared Redis cache service.
+ * @param {(accountId: string, workspaceId: string) => Promise<string[]>} resolveFn
+ *   - Function called on a cache miss to fetch the caller's permission strings for the workspace.
+ * @returns {object} Workspace permission middlewares.
+ */
+const createRequireWorkspacePermission = (permissionCache, resolveFn) => {
+    const requireWorkspacePermission = (permission) => {
+        return async (req, res, next) => {
+            const ctx = req.authContext;
+            if (!ctx || ctx.type !== "user") {
+                (0, utils_1.failure)(res, req, "Unauthorized: No access context", "UNAUTHORIZED", 401);
+                return;
+            }
+            // Resolve workspaceId from request locations
+            const workspaceId = req.params["workspaceId"] ??
+                req.validated?.params?.["workspaceId"] ??
+                req.validated?.body?.["workspaceId"];
+            if (!workspaceId || typeof workspaceId !== "string") {
+                (0, utils_1.failure)(res, req, "Bad Request: Missing workspaceId", "BAD_REQUEST", 400);
+                return;
+            }
+            try {
+                const perms = await permissionCache.resolveWorkspacePermissions(ctx.accountId, workspaceId, async () => {
+                    return resolveFn(ctx.accountId, workspaceId);
+                });
+                if (!permission_checker_1.PermissionChecker.has(perms, permission)) {
+                    (0, utils_1.failure)(res, req, `Forbidden: Missing required workspace permission: ${permission}`, "FORBIDDEN", 403);
+                    return;
+                }
+                next();
+            }
+            catch (err) {
+                next(err);
+            }
+        };
+    };
+    const requireAnyWorkspacePermission = (...permissions) => {
+        return async (req, res, next) => {
+            const ctx = req.authContext;
+            if (!ctx || ctx.type !== "user") {
+                (0, utils_1.failure)(res, req, "Unauthorized: No access context", "UNAUTHORIZED", 401);
+                return;
+            }
+            const workspaceId = req.params["workspaceId"] ??
+                req.validated?.params?.["workspaceId"] ??
+                req.validated?.body?.["workspaceId"];
+            if (!workspaceId || typeof workspaceId !== "string") {
+                (0, utils_1.failure)(res, req, "Bad Request: Missing workspaceId", "BAD_REQUEST", 400);
+                return;
+            }
+            try {
+                const perms = await permissionCache.resolveWorkspacePermissions(ctx.accountId, workspaceId, async () => {
+                    return resolveFn(ctx.accountId, workspaceId);
+                });
+                if (!permission_checker_1.PermissionChecker.hasAny(perms, permissions)) {
+                    (0, utils_1.failure)(res, req, `Forbidden: Missing one of required workspace permissions: [${permissions.join(", ")}]`, "FORBIDDEN", 403);
+                    return;
+                }
+                next();
+            }
+            catch (err) {
+                next(err);
+            }
+        };
+    };
+    const requireAllWorkspacePermissions = (...permissions) => {
+        return async (req, res, next) => {
+            const ctx = req.authContext;
+            if (!ctx || ctx.type !== "user") {
+                (0, utils_1.failure)(res, req, "Unauthorized: No access context", "UNAUTHORIZED", 401);
+                return;
+            }
+            const workspaceId = req.params["workspaceId"] ??
+                req.validated?.params?.["workspaceId"] ??
+                req.validated?.body?.["workspaceId"];
+            if (!workspaceId || typeof workspaceId !== "string") {
+                (0, utils_1.failure)(res, req, "Bad Request: Missing workspaceId", "BAD_REQUEST", 400);
+                return;
+            }
+            try {
+                const perms = await permissionCache.resolveWorkspacePermissions(ctx.accountId, workspaceId, async () => {
+                    return resolveFn(ctx.accountId, workspaceId);
+                });
+                if (!permission_checker_1.PermissionChecker.hasAll(perms, permissions)) {
+                    const missing = permissions.filter(p => !permission_checker_1.PermissionChecker.has(perms, p));
+                    (0, utils_1.failure)(res, req, `Forbidden: Missing required workspace permissions: [${missing.join(", ")}]`, "FORBIDDEN", 403);
+                    return;
+                }
+                next();
+            }
+            catch (err) {
+                next(err);
+            }
+        };
+    };
+    return {
+        requireWorkspacePermission,
+        requireAnyWorkspacePermission,
+        requireAllWorkspacePermissions,
+    };
+};
+exports.createRequireWorkspacePermission = createRequireWorkspacePermission;

package/dist/middleware/validate.middleware.d.ts

@@ -1,35 +1,35 @@
+/**
+ * @file validate.middleware.ts
+ * @description Request validation middleware leveraging Zod schema definitions.
+ * Supports validating multiple request sources without overwriting previous results.
+ */
 import { Request, Response, NextFunction } from "express";
 import { ZodType } from "zod";
 /**
- * VALIDATOR MIDDLEWARE  (@discover-cloud/shared)
- * ────────────────────────────────────────────────
- * Validates and parses request input against a Zod schema.
- * On success, attaches the parsed (coerced + stripped) data to req.validated.
- * On failure, passes the ZodError to next() → GlobalErrorHandler → 400.
- *
- * Source options:
- *   "body"    — req.body    (POST/PUT/PATCH payloads)
- *   "params"  — req.params  (URL path parameters)
- *   "query"   — req.query   (URL query string)
- *   "headers" — req.headers (custom header validation, e.g. API keys)
- *
- * Narrowing req.validated in a controller:
- *   req.validated is typed as unknown in express.d.ts — consumers must
- *   narrow it to the schema's inferred type at the call site:
- *
- *   const body = req.validated as z.infer<typeof CreateOrderSchema>;
- *
- *   This is intentional: the middleware is schema-agnostic and cannot
- *   carry the generic type through Express's untyped req object.
- *
- * Usage:
- *   router.post(
- *     "/orders",
- *     requireAuth,
- *     Validator.validate(CreateOrderSchema, "body"),
- *     controller.create,
- *   );
+ * Supported Express request validation sources.
+ */
+type ValidationSource = "body" | "params" | "query" | "headers";
+/**
+ * Validator utility class containing Express middleware generation methods.
  */
 export declare class Validator {
-    static validate<T>(schema: ZodType<T>, source?: "body" | "params" | "query" | "headers"): (req: Request, _res: Response, next: NextFunction) => void;
+    /**
+     * Generates middleware to parse and validate request parts.
+     *
+     * Validated data is stored by source:
+     *
+     * req.validated = {
+     *   params: {},
+     *   query: {},
+     *   body: {},
+     *   headers: {}
+     * }
+     *
+     * Multiple validators can safely run on the same request.
+     *
+     * @param {ZodType<T>} schema - Zod validation schema.
+     * @param {ValidationSource} source - Request source.
+     */
+    static validate<T>(schema: ZodType<T>, source?: ValidationSource): (req: Request, _res: Response, next: NextFunction) => void;
 }
+export {};

package/dist/middleware/validate.middleware.js

@@ -1,48 +1,46 @@
 "use strict";
+/**
+ * @file validate.middleware.ts
+ * @description Request validation middleware leveraging Zod schema definitions.
+ * Supports validating multiple request sources without overwriting previous results.
+ */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.Validator = void 0;
 /**
- * VALIDATOR MIDDLEWARE  (@discover-cloud/shared)
- * ────────────────────────────────────────────────
- * Validates and parses request input against a Zod schema.
- * On success, attaches the parsed (coerced + stripped) data to req.validated.
- * On failure, passes the ZodError to next() → GlobalErrorHandler → 400.
- *
- * Source options:
- *   "body"    — req.body    (POST/PUT/PATCH payloads)
- *   "params"  — req.params  (URL path parameters)
- *   "query"   — req.query   (URL query string)
- *   "headers" — req.headers (custom header validation, e.g. API keys)
- *
- * Narrowing req.validated in a controller:
- *   req.validated is typed as unknown in express.d.ts — consumers must
- *   narrow it to the schema's inferred type at the call site:
- *
- *   const body = req.validated as z.infer<typeof CreateOrderSchema>;
- *
- *   This is intentional: the middleware is schema-agnostic and cannot
- *   carry the generic type through Express's untyped req object.
- *
- * Usage:
- *   router.post(
- *     "/orders",
- *     requireAuth,
- *     Validator.validate(CreateOrderSchema, "body"),
- *     controller.create,
- *   );
+ * Validator utility class containing Express middleware generation methods.
  */
 class Validator {
+    /**
+     * Generates middleware to parse and validate request parts.
+     *
+     * Validated data is stored by source:
+     *
+     * req.validated = {
+     *   params: {},
+     *   query: {},
+     *   body: {},
+     *   headers: {}
+     * }
+     *
+     * Multiple validators can safely run on the same request.
+     *
+     * @param {ZodType<T>} schema - Zod validation schema.
+     * @param {ValidationSource} source - Request source.
+     */
     static validate(schema, source = "body") {
         return (req, _res, next) => {
             const result = schema.safeParse(req[source]);
             if (!result.success) {
-                // Pass the ZodError to GlobalErrorHandler — it flattens and returns 400.
                 next(result.error);
                 return;
             }
-            // Attach the parsed data (coerced + unknown keys stripped by Zod).
-            // req.validated is typed as unknown — narrow to your schema type in the controller.
-            req.validated = result.data;
+            req.validated = {
+                ...(req.validated ?? {}),
+                [source]: {
+                    ...(req.validated?.[source] ?? {}),
+                    ...result.data,
+                },
+            };
             next();
         };
     }

package/dist/types/express.types.d.ts

@@ -1,49 +1,10 @@
 /**
- * EXPRESS TYPE AUGMENTATION + JWT PAYLOAD TYPES  (@discover-cloud/shared)
- * ──────────────────────────────────────────────────────────────────────────
- * Single source of truth for everything attached to Express's Request object
- * and all internal JWT payload shapes.
- *
- * Import in each service's entrypoint to activate the augmentation:
- *   import "@discover-cloud/shared/types/express";
- *
- * ─── Permission flow ────────────────────────────────────────────────────
- *   JWT carries:       accountId + accountRole    (lean payload, no perms)
- *   Redis derives:     GlobalPermission[]          (role map on cache miss)
- *   AccessContext has: perms                       (resolved by auth middleware)
- *
- *   perms never touch the JWT — they live in the Redis permission cache and
- *   are resolved into req.accessContext by RequireAuthMiddleware per request.
- * ────────────────────────────────────────────────────────────────────────
+ * @file express.types.ts
+ * @description Express Request type augmentations and authentication context definitions.
  */
 import { JWTPayload } from "jose";
-import { AccountRole, GlobalPermission } from "../enums";
-interface BaseInternalJwtPayload extends JWTPayload {
-    /**
-     * JWT ID — required.
-     * Used for the Redis kill-switch (session revocation / account suspension).
-     * Overrides JWTPayload's optional jti with a required string.
-     */
+interface BaseTokenPayload extends JWTPayload {
     jti: string;
-    /**
-     * Token type discriminator — guards against token confusion attacks.
-     * InternalJwtVerifier rejects any token where typ !== "internal",
-     * even if it passes signature verification.
-     */
-    typ: "internal";
-    /**
-     * The entity that last minted or forwarded this token.
-     *   "api-gateway"        → direct user-initiated request
-     *   "notification-service" → service-to-service call on behalf of a user
-     * Used for audit logging and conditional authorization.
-     */
-    caller: string;
-    /**
-     * Propagated request ID for distributed tracing.
-     * Ties together logs across the entire service call chain.
-     * Set by the gateway from the incoming x-request-id header.
-     */
-    requestId?: string;
     iss: string;
     aud: string | string[];
     iat: number;
@@ -51,116 +12,116 @@ interface BaseInternalJwtPayload extends JWTPayload {
     nbf: number;
 }
 /**
- * HumanInternalJwtPayload
- * Issued on behalf of an authenticated user after external JWT verification.
- * accountRole is carried so the permission cache can derive perms from
- * globalRolePermissions on a cold cache miss — without a DB call.
+ * Short-lived user access token.
+ *
+ * Contains authentication identity only.
+ * Authorization is resolved dynamically using RBAC.
+ */
+export interface AccessTokenPayload extends BaseTokenPayload {
+    typ: "access";
+    /** Account identifier. */
+    accountId: string;
+    /** Active session identifier. */
+    sessionId: string;
+    /** Token/version invalidation marker. */
+    ver: number;
+}
+/**
+ * Long-lived refresh token payload.
+ *
+ * Refresh tokens are only used for rotation.
  */
-export interface HumanInternalJwtPayload extends BaseInternalJwtPayload {
-    isMachine: false;
+export interface RefreshTokenPayload extends BaseTokenPayload {
+    typ: "refresh";
     accountId: string;
-    accountRole: AccountRole;
-    externalJti: string;
-    externalExp: number;
 }
 /**
- * MachineInternalJwtPayload
- * Issued for service-to-service calls with no user context.
- * Intentionally carries no user fields — their absence is enforced by the type.
+ * Service-to-service authentication token.
  */
-export interface MachineInternalJwtPayload extends BaseInternalJwtPayload {
-    isMachine: true;
+export interface MachineTokenPayload extends BaseTokenPayload {
+    typ: "machine";
     serviceId: string;
+    scopes: string[];
+    requestId?: string;
 }
-/** Full internal JWT payload union — use in verifiers and auth middleware */
-export type InternalJwtPayload = HumanInternalJwtPayload | MachineInternalJwtPayload;
+/**
+ * Any verified JWT generated by auth-service.
+ */
+export type VerifiedTokenPayload = AccessTokenPayload | RefreshTokenPayload | MachineTokenPayload;
+/**
+ * Minimal data needed to revoke a JWT.
+ */
 export interface TokenRevocationContext {
     jti: string;
     exp: number;
 }
-export interface HumanAccessContext {
-    kind: "human";
+/**
+ * Authenticated user request context.
+ *
+ * Created from access tokens only.
+ */
+export interface UserContext {
+    type: "user";
     accountId: string;
-    accountRole: AccountRole;
-    /**
-     * Resolved from Redis permission cache — NOT from the JWT.
-     * Always present by the time req.accessContext is populated.
-     * Invalidated on role change, suspension, and account deletion.
-     */
-    perms: GlobalPermission[];
+    sessionId: string;
 }
-export interface MachineAccessContext {
-    kind: "machine";
+/**
+ * Authenticated internal service context.
+ */
+export interface MachineContext {
+    type: "machine";
     serviceId: string;
+    scopes: string[];
+}
+export type AuthContext = UserContext | MachineContext;
+export interface RequestMetadataContext {
+    requestId: string;
+    ipAddress: string | null;
+    userAgent: string | null;
 }
-export type AccessContext = HumanAccessContext | MachineAccessContext;
-export declare function isHumanPayload(payload: InternalJwtPayload): payload is HumanInternalJwtPayload;
-export declare function isMachinePayload(payload: InternalJwtPayload): payload is MachineInternalJwtPayload;
 /**
- * Runtime assertion for jose.jwtVerify() results.
- *
- * jose returns a generic JWTPayload because it cannot know
- * our custom claims. After verification + this assertion,
- * TypeScript safely treats it as MachineInternalJwtPayload.
+ * Passed into application services for immutable auditing.
  */
-export declare function assertMachinePayload(payload: JWTPayload): asserts payload is MachineInternalJwtPayload;
-export declare function isHumanContext(ctx: AccessContext): ctx is HumanAccessContext;
-export declare function isMachineContext(ctx: AccessContext): ctx is MachineAccessContext;
-export interface VerifiedAccessPayload {
-    accountId: string;
-    accountRole: AccountRole;
-    typ: "access";
-    iss: string;
-    aud: string | string[];
-    iat: number;
-    exp: number;
-    nbf: number;
-    jti: string;
+export interface AuditContext extends Partial<RequestMetadataContext> {
+    actorId: string | null;
 }
-export interface VerifiedRefreshPayload {
-    accountId: string;
-    typ: "refresh";
-    iss: string;
-    aud: string | string[];
-    iat: number;
-    exp: number;
-    nbf: number;
-    jti: string;
+export declare function isAccessToken(payload: VerifiedTokenPayload): payload is AccessTokenPayload;
+export declare function isRefreshToken(payload: VerifiedTokenPayload): payload is RefreshTokenPayload;
+export declare function isMachineToken(payload: VerifiedTokenPayload): payload is MachineTokenPayload;
+export declare function isUserContext(ctx: AuthContext): ctx is UserContext;
+export declare function isMachineContext(ctx: AuthContext): ctx is MachineContext;
+/**
+ * Runtime assertion for service tokens.
+ */
+export declare function assertMachineToken(payload: JWTPayload): asserts payload is MachineTokenPayload;
+export interface ValidatedRequestData {
+    params?: Record<string, unknown>;
+    query?: Record<string, unknown>;
+    body?: Record<string, unknown>;
+    headers?: Record<string, unknown>;
 }
 declare module "express-serve-static-core" {
     interface Request {
         /**
-         * Unique request ID — set by requestId middleware.
-         * Respects upstream x-request-id forwarded by the gateway / load balancer.
-         * Always present after requestId middleware runs.
+         * Request correlation ID.
          */
         id: string;
         /**
-         * Validated + parsed request input (body / params / query / headers).
-         * Typed as unknown — narrow at the route level using z.infer:
-         *
-         *   const body = req.validated as z.infer<typeof CreateOrderSchema>;
-         *
-         * Never cast to any.
+         * Request metadata.
+         */
+        requestContext: RequestMetadataContext;
+        /**
+         * Validated request data.
          */
-        validated?: unknown;
+        validated?: ValidatedRequestData;
         /**
-         * Raw verified internal JWT payload.
-         * Set by RequireAuthMiddleware after InternalJwtVerifier.verifyInternal().
-         *
-         * Prefer req.accessContext in route handlers and controllers.
-         * Access internalAuth only when you need raw JWT claims (e.g. jti).
+         * Raw verified JWT payload.
          */
-        internalAuth?: InternalJwtPayload;
+        authPayload?: VerifiedTokenPayload;
         /**
-         * Clean access context — built from internalAuth + Redis permission cache.
-         * This is what route handlers, controllers, and domain services consume.
-         *
-         *   if (isHumanContext(req.accessContext)) {
-         *     const { accountId, accountRole, perms } = req.accessContext;
-         *   }
+         * Runtime authenticated identity.
          */
-        accessContext?: AccessContext;
+        authContext?: AuthContext;
     }
 }
 export {};

package/dist/types/express.types.js

@@ -1,60 +1,41 @@
 "use strict";
 /**
- * EXPRESS TYPE AUGMENTATION + JWT PAYLOAD TYPES  (@discover-cloud/shared)
- * ──────────────────────────────────────────────────────────────────────────
- * Single source of truth for everything attached to Express's Request object
- * and all internal JWT payload shapes.
- *
- * Import in each service's entrypoint to activate the augmentation:
- *   import "@discover-cloud/shared/types/express";
- *
- * ─── Permission flow ────────────────────────────────────────────────────
- *   JWT carries:       accountId + accountRole    (lean payload, no perms)
- *   Redis derives:     GlobalPermission[]          (role map on cache miss)
- *   AccessContext has: perms                       (resolved by auth middleware)
- *
- *   perms never touch the JWT — they live in the Redis permission cache and
- *   are resolved into req.accessContext by RequireAuthMiddleware per request.
- * ────────────────────────────────────────────────────────────────────────
+ * @file express.types.ts
+ * @description Express Request type augmentations and authentication context definitions.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.isHumanPayload = isHumanPayload;
-exports.isMachinePayload = isMachinePayload;
-exports.assertMachinePayload = assertMachinePayload;
-exports.isHumanContext = isHumanContext;
+exports.isAccessToken = isAccessToken;
+exports.isRefreshToken = isRefreshToken;
+exports.isMachineToken = isMachineToken;
+exports.isUserContext = isUserContext;
 exports.isMachineContext = isMachineContext;
-/* ====================================================================
-   4. TYPE GUARDS
-
-   Use these over raw property checks — TypeScript narrows the union
-   correctly through predicate functions on both InternalJwtPayload
-   and AccessContext.
-==================================================================== */
-function isHumanPayload(payload) {
-    return payload.isMachine === false;
+exports.assertMachineToken = assertMachineToken;
+/* ---------------------------------------------------------------------------
+   Type Guards
+--------------------------------------------------------------------------- */
+function isAccessToken(payload) {
+    return payload.typ === "access";
 }
-function isMachinePayload(payload) {
-    return payload.isMachine === true;
+function isRefreshToken(payload) {
+    return payload.typ === "refresh";
+}
+function isMachineToken(payload) {
+    return payload.typ === "machine";
+}
+function isUserContext(ctx) {
+    return ctx.type === "user";
+}
+function isMachineContext(ctx) {
+    return ctx.type === "machine";
 }
 /**
- * Runtime assertion for jose.jwtVerify() results.
- *
- * jose returns a generic JWTPayload because it cannot know
- * our custom claims. After verification + this assertion,
- * TypeScript safely treats it as MachineInternalJwtPayload.
+ * Runtime assertion for service tokens.
  */
-function assertMachinePayload(payload) {
-    if (payload["typ"] !== "internal" ||
-        payload["isMachine"] !== true ||
+function assertMachineToken(payload) {
+    if (payload["typ"] !== "machine" ||
         typeof payload["serviceId"] !== "string" ||
         typeof payload["jti"] !== "string" ||
-        typeof payload["caller"] !== "string") {
-        throw new Error("Invalid machine JWT payload");
+        !Array.isArray(payload["scopes"])) {
+        throw new Error("Invalid machine token payload");
     }
 }
-function isHumanContext(ctx) {
-    return ctx.kind === "human";
-}
-function isMachineContext(ctx) {
-    return ctx.kind === "machine";
-}

package/dist/utils/date.util.d.ts

@@ -0,0 +1,6 @@
+/**
+ * @file date.util.ts
+ * @description Date formatting and serialization helper utilities.
+ */
+export declare const toIso: (date: Date) => string;
+export declare const toIsoOrNull: (date: Date | null | undefined) => string | null;

package/dist/utils/date.util.js

@@ -0,0 +1,11 @@
+"use strict";
+/**
+ * @file date.util.ts
+ * @description Date formatting and serialization helper utilities.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.toIsoOrNull = exports.toIso = void 0;
+const toIso = (date) => date.toISOString();
+exports.toIso = toIso;
+const toIsoOrNull = (date) => date ? date.toISOString() : null;
+exports.toIsoOrNull = toIsoOrNull;

package/dist/utils/env.util.d.ts

@@ -0,0 +1,6 @@
+/**
+ * @file env.util.ts
+ * @description Helper functions to retrieve and validate environment variable settings safely.
+ */
+export declare function getEnv(name: string): string;
+export declare function getEnvOptional(name: string): string | undefined;

package/dist/utils/env.util.js

@@ -0,0 +1,19 @@
+"use strict";
+/**
+ * @file env.util.ts
+ * @description Helper functions to retrieve and validate environment variable settings safely.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getEnv = getEnv;
+exports.getEnvOptional = getEnvOptional;
+function getEnv(name) {
+    const value = process.env[name];
+    if (!value) {
+        throw new Error(`Missing required environment variable: ${name}. Ensure it is set in your .env file.`);
+    }
+    return value;
+}
+function getEnvOptional(name) {
+    const value = process.env[name];
+    return value === "" ? undefined : value;
+}