@discover-cloud/shared 1.0.0 → 1.0.1

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

@@ -0,0 +1,148 @@
+/**
+ * EXPRESS TYPE AUGMENTATION + JWT PAYLOAD TYPES
+ * ───────────────────────────────────────────────
+ * Single source of truth for everything attached to Express's Request object
+ * and all internal JWT payload shapes.
+ *
+ * Belongs in @discover-cloud/shared — import in each service's entrypoint:
+ *   import "@discover-cloud/shared/types/express";
+ *
+ * ─── Permission flow ────────────────────────────────────────────────
+ *   JWT carries:        accountId + accountRole   (lean, no perms)
+ *   Cache derives:      GlobalPermission[]         (Redis → role map on miss)
+ *   AccessContext has:  perms                      (populated by auth middleware)
+ *
+ *   perms never touch the JWT — they live in the permission cache and are
+ *   resolved into req.accessContext by RequireAuthMiddleware on every request.
+ */
+import "express-serve-static-core";
+import { JWTPayload } from "jose";
+import { AccountRole } from "../enums";
+import { 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 required.
+     */
+    jti: string;
+    /** typ discriminator — guards against token type confusion attacks */
+    typ: "internal";
+    /**
+     * The entity that last minted or forwarded this token.
+     *   "api-gateway"   → direct user-initiated request
+     *   "order-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.
+     */
+    requestId?: string;
+    iss: string;
+    aud: string | string[];
+    iat: number;
+    exp: number;
+    nbf: number;
+}
+/**
+ * Human JWT payload — issued on behalf of an authenticated user.
+ * Minted by the gateway after verifying an external JWT.
+ *
+ * accountRole is carried so the permission cache can derive perms
+ * from globalRolePermissions on a cold cache miss — without a DB call.
+ */
+export interface HumanInternalJwtPayload extends BaseInternalJwtPayload {
+    isMachine: false;
+    accountId: string;
+    accountRole: AccountRole;
+}
+/**
+ * Machine JWT payload — service-to-service calls with no user context.
+ * Intentionally carries NO user fields — absence is enforced by the type.
+ */
+export interface MachineInternalJwtPayload extends BaseInternalJwtPayload {
+    isMachine: true;
+    serviceId: string;
+}
+/** The full internal JWT payload union — use this in verifiers and auth middleware */
+export type InternalJwtPayload = HumanInternalJwtPayload | MachineInternalJwtPayload;
+export interface HumanAccessContext {
+    kind: "human";
+    accountId: string;
+    accountRole: AccountRole;
+    /**
+     * Resolved from Redis permission cache — NOT from the JWT.
+     * Always present by the time req.accessContext is set.
+     * Invalidated on role change, suspension, and account deletion.
+     */
+    perms: GlobalPermission[];
+}
+export interface MachineAccessContext {
+    kind: "machine";
+    serviceId: string;
+}
+export type AccessContext = HumanAccessContext | MachineAccessContext;
+export declare function isHumanPayload(payload: InternalJwtPayload): payload is HumanInternalJwtPayload;
+export declare function isMachinePayload(payload: InternalJwtPayload): 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 VerifiedRefreshPayload {
+    accountId: string;
+    typ: "refresh";
+    iss: string;
+    aud: string | string[];
+    iat: number;
+    exp: number;
+    nbf: number;
+    jti: string;
+}
+declare module "express-serve-static-core" {
+    interface Request {
+        /**
+         * Unique request ID — set by requestId middleware.
+         * Respects upstream x-request-id from the gateway / load balancer.
+         * Always present after requestId middleware runs.
+         */
+        id: string;
+        /**
+         * Validated + parsed request body/query/params/headers.
+         * Typed as unknown — narrow at the route level:
+         *
+         *   const body = req.validated as z.infer<typeof CreateOrderSchema>;
+         *
+         * Never cast to any.
+         */
+        validated?: unknown;
+        /**
+         * Raw verified internal JWT payload.
+         * Set by RequireAuthMiddleware after InternalJwtVerifier.verifyInternal().
+         *
+         * Prefer req.accessContext in route handlers.
+         * Access this only when you need raw JWT claims (e.g. jti for blacklisting).
+         */
+        internalAuth?: InternalJwtPayload;
+        /**
+         * Clean access context — built from internalAuth + permission cache.
+         * This is what route handlers, controllers, and domain services use.
+         *
+         *   if (isHumanContext(req.accessContext)) {
+         *     const { accountId, accountRole, perms } = req.accessContext;
+         *   }
+         */
+        accessContext?: AccessContext;
+    }
+}
+export {};

package/dist/types/express.types.js

@@ -0,0 +1,42 @@
+"use strict";
+/**
+ * EXPRESS TYPE AUGMENTATION + JWT PAYLOAD TYPES
+ * ───────────────────────────────────────────────
+ * Single source of truth for everything attached to Express's Request object
+ * and all internal JWT payload shapes.
+ *
+ * Belongs in @discover-cloud/shared — import in each service's entrypoint:
+ *   import "@discover-cloud/shared/types/express";
+ *
+ * ─── Permission flow ────────────────────────────────────────────────
+ *   JWT carries:        accountId + accountRole   (lean, no perms)
+ *   Cache derives:      GlobalPermission[]         (Redis → role map on miss)
+ *   AccessContext has:  perms                      (populated by auth middleware)
+ *
+ *   perms never touch the JWT — they live in the permission cache and are
+ *   resolved into req.accessContext by RequireAuthMiddleware on every request.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isHumanPayload = isHumanPayload;
+exports.isMachinePayload = isMachinePayload;
+exports.isHumanContext = isHumanContext;
+exports.isMachineContext = isMachineContext;
+require("express-serve-static-core");
+/* ====================================================================
+   4. TYPE GUARDS
+
+   Use these over raw property checks — TypeScript narrows correctly
+   through them on both InternalJwtPayload and AccessContext.
+==================================================================== */
+function isHumanPayload(payload) {
+    return payload.isMachine === false;
+}
+function isMachinePayload(payload) {
+    return payload.isMachine === true;
+}
+function isHumanContext(ctx) {
+    return ctx.kind === "human";
+}
+function isMachineContext(ctx) {
+    return ctx.kind === "machine";
+}

package/dist/types/index.d.ts

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

package/dist/types/index.js

@@ -14,4 +14,4 @@ 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("./express"), exports);
+__exportStar(require("./express.types"), exports);

package/dist/utils/response.d.ts

@@ -1,3 +1,4 @@
 import { Response } from "express";
 export declare const success: <T>(res: Response, data: T, statusCode?: number) => Response<any, Record<string, any>>;
-export declare const failure: (res: Response, message: string, statusCode?: number, details?: unknown) => Response<any, Record<string, any>>;
+export declare const failure: (res: Response, message: string, code: string, // <-- Added to match the DTO requirement
+statusCode?: number, details?: unknown) => Response<any, Record<string, any>>;

package/dist/utils/response.js

@@ -2,28 +2,31 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.failure = exports.success = void 0;
 const success = (res, data, statusCode = 200) => {
+    // Cast to Request to access properties safely, assuming module augmentation
     const req = res.req;
     const response = {
         success: true,
         data,
         meta: {
-            requestId: req?.id ?? null,
+            requestId: req.id ?? "unknown", // Fallback if middleware failed
             timestamp: new Date().toISOString()
         }
     };
     return res.status(statusCode).json(response);
 };
 exports.success = success;
-const failure = (res, message, statusCode = 400, details) => {
+const failure = (res, message, code, // <-- Added to match the DTO requirement
+statusCode = 400, details) => {
     const req = res.req;
     const response = {
         success: false,
         error: {
+            code, // <-- Added here
             message,
             details: details ?? null
         },
         meta: {
-            requestId: req?.id ?? null,
+            requestId: req.id ?? "unknown",
             timestamp: new Date().toISOString()
         }
     };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@discover-cloud/shared",
-  "version": "1.0.0",
+  "version": "1.0.1",
   "private": false,
   "type": "commonjs",
   "main": "dist/index.js",
@@ -17,7 +17,8 @@
   },
   "dependencies": {
     "axios-retry": "^4.5.0",
-    "jose": "^6.1.3"
+    "jose": "^6.1.3",
+    "redis": "^5.11.0"
   },
   "peerDependencies": {
     "axios": "^1.13.5",