@discover-cloud/shared 1.2.9 → 1.4.0

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

@@ -1,49 +1,11 @@
 /**
- * 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.
-     */
+import { JWTPayload } from 'jose';
+import { ResourceQueryScope } from '../contracts';
+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 +13,122 @@ 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 HumanInternalJwtPayload extends BaseInternalJwtPayload {
-    isMachine: false;
+export interface AccessTokenPayload extends BaseTokenPayload {
+    typ: 'access';
+    /** Account identifier. */
     accountId: string;
-    accountRole: AccountRole;
-    externalJti: string;
-    externalExp: number;
+    /** Active session identifier. */
+    sessionId: string;
+    /** Token/version invalidation marker. */
+    ver: number;
+    /** Whether the session was generated via impersonation. */
+    impersonated?: boolean;
 }
 /**
- * MachineInternalJwtPayload
- * Issued for service-to-service calls with no user context.
- * Intentionally carries no user fields — their absence is enforced by the type.
+ * Long-lived refresh token payload.
+ *
+ * Refresh tokens are only used for rotation.
  */
-export interface MachineInternalJwtPayload extends BaseInternalJwtPayload {
-    isMachine: true;
+export interface RefreshTokenPayload extends BaseTokenPayload {
+    typ: 'refresh';
+    accountId: string;
+}
+/**
+ * Service-to-service authentication token.
+ */
+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" {
+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?: ValidatedRequestData;
+        /**
+         * Raw verified JWT payload.
          */
-        validated?: unknown;
+        authPayload?: VerifiedTokenPayload;
         /**
-         * 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).
+         * Runtime authenticated identity.
          */
-        internalAuth?: InternalJwtPayload;
+        authContext?: AuthContext;
         /**
-         * 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;
-         *   }
+         * Resolved resource query scope for insights queries.
          */
-        accessContext?: AccessContext;
+        visibilityScope?: ResourceQueryScope;
     }
 }
 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';
 }
-/**
- * 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.
- */
-function assertMachinePayload(payload) {
-    if (payload["typ"] !== "internal" ||
-        payload["isMachine"] !== true ||
-        typeof payload["serviceId"] !== "string" ||
-        typeof payload["jti"] !== "string" ||
-        typeof payload["caller"] !== "string") {
-        throw new Error("Invalid machine JWT payload");
-    }
+function isMachineToken(payload) {
+    return payload.typ === 'machine';
 }
-function isHumanContext(ctx) {
-    return ctx.kind === "human";
+function isUserContext(ctx) {
+    return ctx.type === 'user';
 }
 function isMachineContext(ctx) {
-    return ctx.kind === "machine";
+    return ctx.type === 'machine';
+}
+/**
+ * Runtime assertion for service tokens.
+ */
+function assertMachineToken(payload) {
+    if (payload['typ'] !== 'machine' ||
+        typeof payload['serviceId'] !== 'string' ||
+        typeof payload['jti'] !== 'string' ||
+        !Array.isArray(payload['scopes'])) {
+        throw new Error('Invalid machine token payload');
+    }
 }

package/dist/types/index.d.ts

@@ -1 +1 @@
-export * from "./express.types";
+export * from './express.types';

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;
+}

package/dist/utils/index.d.ts

@@ -1,4 +1,5 @@
-export * from "./response.utils";
-export * from "./logger.utils";
-export * from "./date.utils";
-export * from "./env.utils";
+export * from './response.util';
+export * from './logger.util';
+export * from './date.util';
+export * from './env.util';
+export * from './pagination.util';

package/dist/utils/index.js

@@ -14,7 +14,8 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
     for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-__exportStar(require("./response.utils"), exports);
-__exportStar(require("./logger.utils"), exports);
-__exportStar(require("./date.utils"), exports);
-__exportStar(require("./env.utils"), exports);
+__exportStar(require("./response.util"), exports);
+__exportStar(require("./logger.util"), exports);
+__exportStar(require("./date.util"), exports);
+__exportStar(require("./env.util"), exports);
+__exportStar(require("./pagination.util"), exports);

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

@@ -0,0 +1,31 @@
+/**
+ * @file logger.utils.ts
+ * @description Minimal logger contract interface and common logger implementations (console, silent no-op).
+ */
+/**
+ * Standard logger interface that components can depend on to avoid coupling to
+ * specific third-party logging engines.
+ */
+export interface ILogger {
+    debug(obj: object, msg?: string): void;
+    debug(msg: string): void;
+    info(obj: object, msg?: string): void;
+    info(msg: string): void;
+    warn(obj: object, msg?: string): void;
+    warn(msg: string): void;
+    error(obj: object, msg?: string): void;
+    error(msg: string): void;
+}
+/**
+ * Silent no-op implementation discarded all log payloads.
+ */
+export declare const noopLogger: ILogger;
+/**
+ * Console logger implementing the ILogger interface mapping to native console output.
+ */
+export declare const consoleLogger: ILogger;
+/**
+ * Creates an ILogger adapter for a given Pino logger instance.
+ * @param pinoLogger Any Pino logger instance.
+ */
+export declare function createPinoAdapter(pinoLogger: any): ILogger;

package/dist/utils/logger.util.js

@@ -0,0 +1,91 @@
+"use strict";
+/**
+ * @file logger.utils.ts
+ * @description Minimal logger contract interface and common logger implementations (console, silent no-op).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.consoleLogger = exports.noopLogger = void 0;
+exports.createPinoAdapter = createPinoAdapter;
+/**
+ * Silent no-op implementation discarded all log payloads.
+ */
+exports.noopLogger = {
+    debug: () => { },
+    info: () => { },
+    warn: () => { },
+    error: () => { },
+};
+/**
+ * Console logger implementing the ILogger interface mapping to native console output.
+ */
+exports.consoleLogger = {
+    debug: (objOrMsg, msg) => {
+        if (typeof objOrMsg === 'string') {
+            console.debug(objOrMsg);
+        }
+        else {
+            console.debug(msg ?? '', objOrMsg);
+        }
+    },
+    info: (objOrMsg, msg) => {
+        if (typeof objOrMsg === 'string') {
+            console.info(objOrMsg);
+        }
+        else {
+            console.info(msg ?? '', objOrMsg);
+        }
+    },
+    warn: (objOrMsg, msg) => {
+        if (typeof objOrMsg === 'string') {
+            console.warn(objOrMsg);
+        }
+        else {
+            console.warn(msg ?? '', objOrMsg);
+        }
+    },
+    error: (objOrMsg, msg) => {
+        if (typeof objOrMsg === 'string') {
+            console.error(objOrMsg);
+        }
+        else {
+            console.error(msg ?? '', objOrMsg);
+        }
+    },
+};
+/**
+ * Creates an ILogger adapter for a given Pino logger instance.
+ * @param pinoLogger Any Pino logger instance.
+ */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+function createPinoAdapter(pinoLogger) {
+    return {
+        debug(objOrMsg, msg) {
+            if (typeof objOrMsg === 'string') {
+                pinoLogger.debug(objOrMsg);
+                return;
+            }
+            pinoLogger.debug(objOrMsg, msg);
+        },
+        info(objOrMsg, msg) {
+            if (typeof objOrMsg === 'string') {
+                pinoLogger.info(objOrMsg);
+                return;
+            }
+            pinoLogger.info(objOrMsg, msg);
+        },
+        warn(objOrMsg, msg) {
+            if (typeof objOrMsg === 'string') {
+                pinoLogger.warn(objOrMsg);
+                return;
+            }
+            pinoLogger.warn(objOrMsg, msg);
+        },
+        error(objOrMsg, msg) {
+            if (typeof objOrMsg === 'string') {
+                pinoLogger.error(objOrMsg);
+                return;
+            }
+            pinoLogger.error(objOrMsg, msg);
+        },
+    };
+}

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

@@ -0,0 +1,6 @@
+/**
+ * @file pagination.utils.ts
+ * @description Helper functions to calculate pagination metadata from repository outputs.
+ */
+import { PaginationMeta } from '../dtos';
+export declare function buildPaginationMeta(totalItems: number, limit: number, offset: number): PaginationMeta;

package/dist/utils/pagination.util.js

@@ -0,0 +1,20 @@
+"use strict";
+/**
+ * @file pagination.utils.ts
+ * @description Helper functions to calculate pagination metadata from repository outputs.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildPaginationMeta = buildPaginationMeta;
+function buildPaginationMeta(totalItems, limit, offset) {
+    const pageSize = limit > 0 ? limit : 1;
+    const totalPages = Math.ceil(totalItems / pageSize);
+    const currentPage = Math.floor(offset / pageSize) + 1;
+    return {
+        page: currentPage,
+        pageSize,
+        totalItems,
+        totalPages,
+        hasNext: currentPage < totalPages,
+        hasPrev: currentPage > 1,
+    };
+}

package/dist/utils/request-context.als.d.ts

@@ -0,0 +1,10 @@
+import { AsyncLocalStorage } from 'async_hooks';
+import { AuditActorType } from '../types/audit.types';
+export interface RequestContextData {
+    requestId: string;
+    ipAddress: string | null;
+    userAgent: string | null;
+    actorId?: string | null;
+    actorType?: AuditActorType;
+}
+export declare const requestContextStorage: AsyncLocalStorage<RequestContextData>;

package/dist/utils/request-context.als.js

@@ -0,0 +1,5 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.requestContextStorage = void 0;
+const async_hooks_1 = require("async_hooks");
+exports.requestContextStorage = new async_hooks_1.AsyncLocalStorage();

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

@@ -0,0 +1,27 @@
+/**
+ * @file response.utils.ts
+ * @description Helper functions to construct and send standardized API success and error response envelopes.
+ */
+import { Response, Request } from 'express';
+/**
+ * Sends a successful standardized API response containing the data payload.
+ *
+ * @param {Response} res        - Express response object.
+ * @param {Request}  req        - Express request object.
+ * @param {T}        data       - The payload data.
+ * @param {number}   [statusCode=200] - HTTP status code.
+ * @returns {void}
+ */
+export declare const success: <T>(res: Response, req: Request, data: T, statusCode?: number) => void;
+/**
+ * Sends a failed standardized API response containing error details.
+ *
+ * @param {Response} res        - Express response object.
+ * @param {Request}  req        - Express request object.
+ * @param {string}   message    - Human-readable error message.
+ * @param {string}   code       - Error code mapping.
+ * @param {number}   [statusCode=400] - HTTP status code.
+ * @param {unknown}  [details]    - Optional error metadata details.
+ * @returns {void}
+ */
+export declare const failure: (res: Response, req: Request, message: string, code: string, statusCode?: number, details?: unknown) => void;