@discover-cloud/shared 1.0.11 → 1.2.0

package/dist/errors/http-errors.js

@@ -3,65 +3,87 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.ServiceUnavailableError = exports.InternalServerError = exports.TooManyRequestsError = exports.UnprocessableEntityError = exports.ConflictError = exports.NotFoundError = exports.ForbiddenError = exports.UnauthorizedError = exports.BadRequestError = void 0;
 const app_error_1 = require("./app-error");
 /**
- * HTTP ERRORS
- * ────────────
+ * HTTP ERRORS  (@discover-cloud/shared)
+ * ───────────────────────────────────────
  * Typed subclasses of AppError for every common HTTP error status.
- * GlobalErrorHandler catches these via instanceof AppError and maps
- * statusCode + code directly to the response.
+ *
+ * GlobalErrorHandler catches these via `instanceof AppError` and maps
+ * statusCode + code directly to the response — no additional switch/if needed.
  *
  * Usage:
  *   throw new NotFoundError("Account not found");
  *   throw new ConflictError("Email already in use");
- *   throw new BadRequestError("Invalid input", { field: "email" });
+ *   throw new BadRequestError("Validation failed", { field: "email" });
+ *
+ * Adding a new error type:
+ *   1. Add a subclass here following the existing pattern.
+ *   2. Pick the correct HTTP status code.
+ *   3. Choose a SCREAMING_SNAKE_CASE code that is stable across versions
+ *      (clients may key on it for error handling).
  */
+// 400 — The request is malformed or contains invalid input.
 class BadRequestError extends app_error_1.AppError {
     constructor(message = "Bad Request", details) {
         super("BAD_REQUEST", 400, message, details);
     }
 }
 exports.BadRequestError = BadRequestError;
+// 401 — No valid credentials were supplied (missing or expired token).
+//        Distinct from 403: the client may retry after authenticating.
 class UnauthorizedError extends app_error_1.AppError {
     constructor(message = "Unauthorized", details) {
         super("UNAUTHORIZED", 401, message, details);
     }
 }
 exports.UnauthorizedError = UnauthorizedError;
+// 403 — Valid credentials were supplied but the caller lacks permission.
+//        Retrying with the same credentials will not help.
 class ForbiddenError extends app_error_1.AppError {
     constructor(message = "Forbidden", details) {
         super("FORBIDDEN", 403, message, details);
     }
 }
 exports.ForbiddenError = ForbiddenError;
+// 404 — The requested resource does not exist.
 class NotFoundError extends app_error_1.AppError {
     constructor(message = "Not Found", details) {
         super("NOT_FOUND", 404, message, details);
     }
 }
 exports.NotFoundError = NotFoundError;
+// 409 — The request conflicts with the current state of the resource
+//        (e.g. duplicate email, concurrent edit conflict).
 class ConflictError extends app_error_1.AppError {
     constructor(message = "Conflict", details) {
         super("CONFLICT", 409, message, details);
     }
 }
 exports.ConflictError = ConflictError;
+// 422 — The request is well-formed but semantically invalid
+//        (e.g. Zod validation passed structurally but business rules failed).
 class UnprocessableEntityError extends app_error_1.AppError {
     constructor(message = "Unprocessable Entity", details) {
         super("UNPROCESSABLE_ENTITY", 422, message, details);
     }
 }
 exports.UnprocessableEntityError = UnprocessableEntityError;
+// 429 — The caller has exceeded the rate limit. Clients should back off.
 class TooManyRequestsError extends app_error_1.AppError {
     constructor(message = "Too Many Requests", details) {
         super("TOO_MANY_REQUESTS", 429, message, details);
     }
 }
 exports.TooManyRequestsError = TooManyRequestsError;
+// 500 — An unexpected internal error occurred. Should never be thrown
+//        intentionally — use more specific errors wherever possible.
 class InternalServerError extends app_error_1.AppError {
     constructor(message = "Internal Server Error", details) {
         super("INTERNAL_SERVER_ERROR", 500, message, details);
     }
 }
 exports.InternalServerError = InternalServerError;
+// 503 — The service (or a dependency) is temporarily unavailable.
+//        Clients may retry after the indicated delay.
 class ServiceUnavailableError extends app_error_1.AppError {
     constructor(message = "Service Unavailable", details) {
         super("SERVICE_UNAVAILABLE", 503, message, details);

package/dist/http/service-client.d.ts

@@ -1,24 +1,33 @@
 import { AxiosInstance, AxiosRequestConfig, AxiosResponse } from "axios";
 import { Request } from "express";
 /**
- * SERVICE CLIENT
- * ───────────────
+ * SERVICE CLIENT  (@discover-cloud/shared)
+ * ─────────────────────────────────────────
  * HTTP client for service-to-service communication.
  *
  * Two call patterns:
  *
- * 1. JWT-forwarding (user-initiated requests)
- *    Pass the current Express Request — Authorization + x-request-id
- *    are forwarded automatically.
- *    Use: getWithAuth, postWithAuth, patchWithAuth, deleteWithAuth
+ * Pattern 1 — JWT-forwarding (user-initiated requests)
+ *   Pass the current Express Request — Authorization + x-request-id are
+ *   forwarded automatically. Used when the downstream service needs to
+ *   act on behalf of the authenticated user.
+ *   Methods: getWithAuth, postWithAuth, patchWithAuth, deleteWithAuth
  *
- * 2. Internal calls (service-to-service, no incoming request)
- *    Pass explicit headers — used by UserServiceClient in auth service
- *    where calls originate from service logic, not from an HTTP handler.
- *    Use: get, post, patch, delete
+ * Pattern 2 — Internal calls (service-initiated, no incoming request)
+ *   Pass explicit headers — used when calls originate from service logic
+ *   rather than from an HTTP handler (e.g. auth service → user service
+ *   during account creation). Caller is responsible for providing the
+ *   X-Internal-Secret header.
+ *   Methods: get, post, patch, delete
  *
- * Retry strategy: network errors + 5xx only. Never retries 4xx —
- * those are deterministic caller errors.
+ * Retry strategy:
+ *   - Retries on network errors and 5xx responses only (up to 3 attempts,
+ *     exponential backoff). 4xx responses are never retried — they are
+ *     deterministic caller errors that won't resolve on retry.
+ *
+ * Timeout:
+ *   - 8 seconds per request (covers retry delays separately via axiosRetry).
+ *     Adjust per-call via config.timeout if a specific route needs more.
  */
 export declare class ServiceClient {
     readonly http: AxiosInstance;
@@ -31,6 +40,22 @@ export declare class ServiceClient {
     post<T = unknown>(url: string, data: unknown, headers: Record<string, string>, config?: AxiosRequestConfig): Promise<AxiosResponse<T>>;
     patch<T = unknown>(url: string, data: unknown, headers: Record<string, string>, config?: AxiosRequestConfig): Promise<AxiosResponse<T>>;
     delete<T = unknown>(url: string, headers: Record<string, string>, config?: AxiosRequestConfig): Promise<AxiosResponse<T>>;
+    /**
+     * mergeAuth
+     * Extracts Authorization and x-request-id from the Express request
+     * and merges them into the Axios config headers.
+     *
+     * x-request-id precedence:
+     *   1. req.id — set by express-request-id or equivalent middleware
+     *   2. x-request-id header forwarded from the upstream caller
+     *   3. Synthetic fallback (timestamp) — should not appear in production
+     *      if request-id middleware is wired correctly in the gateway
+     */
     private mergeAuth;
+    /**
+     * mergeHeaders
+     * Merges caller-supplied headers into the Axios config.
+     * Caller-supplied headers take precedence over config.headers.
+     */
     private mergeHeaders;
 }

package/dist/http/service-client.js

@@ -7,24 +7,33 @@ exports.ServiceClient = void 0;
 const axios_1 = __importDefault(require("axios"));
 const axios_retry_1 = __importDefault(require("axios-retry"));
 /**
- * SERVICE CLIENT
- * ───────────────
+ * SERVICE CLIENT  (@discover-cloud/shared)
+ * ─────────────────────────────────────────
  * HTTP client for service-to-service communication.
  *
  * Two call patterns:
  *
- * 1. JWT-forwarding (user-initiated requests)
- *    Pass the current Express Request — Authorization + x-request-id
- *    are forwarded automatically.
- *    Use: getWithAuth, postWithAuth, patchWithAuth, deleteWithAuth
+ * Pattern 1 — JWT-forwarding (user-initiated requests)
+ *   Pass the current Express Request — Authorization + x-request-id are
+ *   forwarded automatically. Used when the downstream service needs to
+ *   act on behalf of the authenticated user.
+ *   Methods: getWithAuth, postWithAuth, patchWithAuth, deleteWithAuth
  *
- * 2. Internal calls (service-to-service, no incoming request)
- *    Pass explicit headers — used by UserServiceClient in auth service
- *    where calls originate from service logic, not from an HTTP handler.
- *    Use: get, post, patch, delete
+ * Pattern 2 — Internal calls (service-initiated, no incoming request)
+ *   Pass explicit headers — used when calls originate from service logic
+ *   rather than from an HTTP handler (e.g. auth service → user service
+ *   during account creation). Caller is responsible for providing the
+ *   X-Internal-Secret header.
+ *   Methods: get, post, patch, delete
  *
- * Retry strategy: network errors + 5xx only. Never retries 4xx —
- * those are deterministic caller errors.
+ * Retry strategy:
+ *   - Retries on network errors and 5xx responses only (up to 3 attempts,
+ *     exponential backoff). 4xx responses are never retried — they are
+ *     deterministic caller errors that won't resolve on retry.
+ *
+ * Timeout:
+ *   - 8 seconds per request (covers retry delays separately via axiosRetry).
+ *     Adjust per-call via config.timeout if a specific route needs more.
  */
 class ServiceClient {
     constructor(baseURL) {
@@ -36,8 +45,10 @@ class ServiceClient {
             retries: 3,
             retryDelay: axios_retry_1.default.exponentialDelay,
             retryCondition: (err) => {
+                // Retry network-level errors (no response received)
                 if (axios_retry_1.default.isNetworkError(err))
                     return true;
+                // Retry transient server errors; never retry client errors
                 const status = err.response?.status ?? 0;
                 return status >= 500;
             },
@@ -46,6 +57,7 @@ class ServiceClient {
     /* ----------------------------------------------------------------
        Pattern 1 — JWT-forwarding (pass Express req)
        Forwards Authorization header + x-request-id automatically.
+       Use for endpoints that require a user identity downstream.
     ---------------------------------------------------------------- */
     async getWithAuth(url, req, config) {
         return this.http.get(url, this.mergeAuth(req, config));
@@ -61,8 +73,8 @@ class ServiceClient {
     }
     /* ----------------------------------------------------------------
        Pattern 2 — Internal calls (explicit headers, no Express req)
-       Used for service-initiated calls (e.g. auth service → user service)
-       where there is no incoming HTTP request to forward from.
+       Used for service-initiated calls where there is no incoming HTTP
+       request to forward from. Caller must supply X-Internal-Secret.
     ---------------------------------------------------------------- */
     async get(url, headers, config) {
         return this.http.get(url, this.mergeHeaders(headers, config));
@@ -79,12 +91,21 @@ class ServiceClient {
     /* ----------------------------------------------------------------
        Private helpers
     ---------------------------------------------------------------- */
+    /**
+     * mergeAuth
+     * Extracts Authorization and x-request-id from the Express request
+     * and merges them into the Axios config headers.
+     *
+     * x-request-id precedence:
+     *   1. req.id — set by express-request-id or equivalent middleware
+     *   2. x-request-id header forwarded from the upstream caller
+     *   3. Synthetic fallback (timestamp) — should not appear in production
+     *      if request-id middleware is wired correctly in the gateway
+     */
     mergeAuth(req, config) {
         const authHeader = req.headers.authorization;
         const upstream = req.headers["x-request-id"];
-        const requestId = req.id
-            ?? (Array.isArray(upstream) ? upstream[0] : upstream)
-            ?? `fallback-${Date.now()}`;
+        const requestId = req.id ?? (Array.isArray(upstream) ? upstream[0] : upstream) ?? `fallback-${Date.now()}`;
         return {
             ...config,
             headers: {
@@ -94,6 +115,11 @@ class ServiceClient {
             },
         };
     }
+    /**
+     * mergeHeaders
+     * Merges caller-supplied headers into the Axios config.
+     * Caller-supplied headers take precedence over config.headers.
+     */
     mergeHeaders(headers, config) {
         return {
             ...config,

package/dist/jwt/internal-jwt-verifier.d.ts

@@ -13,23 +13,29 @@ export declare class InternalJwtVerifier {
         context: AccessContext;
     }>;
     /**
-     * Returns true if the context has the given permission.
+     * hasPermission
+     * Returns true if the context carries the given GlobalPermission.
      * Machine contexts always return false — they carry no user permissions.
      */
     static hasPermission(ctx: AccessContext, permission: GlobalPermission): boolean;
     /**
-     * Throws JWTClaimValidationFailed if the permission is missing.
+     * requirePermission
+     * Throws JWTClaimValidationFailed if the permission is absent.
      * Use in middleware for a one-liner gate:
      *   InternalJwtVerifier.requirePermission(ctx, GlobalPermission.MANAGE_ACCOUNTS);
      */
     static requirePermission(ctx: AccessContext, permission: GlobalPermission): void;
     /**
-     * Returns true if the context carries the given role.
+     * hasRole
+     * Returns true if the context carries the given AccountRole.
      * Machine contexts always return false.
      */
     static hasRole(ctx: AccessContext, role: AccountRole): boolean;
     /**
+     * requireRole
      * Throws JWTClaimValidationFailed if the role doesn't match.
+     * Prefer requirePermission() for most gates — role checks are for the rare
+     * cases where a specific role (not just a permission) must be enforced.
      */
     static requireRole(ctx: AccessContext, role: AccountRole): void;
 }

package/dist/jwt/internal-jwt-verifier.js

@@ -38,17 +38,29 @@ const jose = __importStar(require("jose"));
 /**
  * INTERNAL JWT VERIFIER  (@discover-cloud/shared)
  * ──────────────────────────────────────────────────
- * Verifies the internal JWT forwarded by the API Gateway, resolves
- * permissions from Redis, and builds the AccessContext for req.accessContext.
+ * Verifies the internal JWT minted by the API Gateway, resolves permissions
+ * from Redis, and builds the AccessContext attached to req.accessContext.
  *
- * Key source: Gateway JWKS
- *   GET http://api-gateway:3000/.well-known/jwks.json
+ * Key source:
+ *   Remote JWKS — fetched from the Gateway at startup and cached for 10 minutes.
+ *   Requests made during a JWKS cache miss are blocked until the fetch completes
+ *   (jose handles this internally with a deduplication lock).
  *
- * Flow per request:
- *   1. Verify JWT signature, iss, aud, exp, nbf, typ   (jose.jwtVerify)
- *   2. Guard typ === "internal"                         (token confusion protection)
- *   3. For human tokens: resolve perms from Redis       (derive from role on miss)
- *   4. Build and return AccessContext
+ * Token flow per request:
+ *   1. Extract Bearer token from Authorization header (caller's responsibility)
+ *   2. Verify JWT signature, iss, aud, exp, nbf, typ   → verifyInternal()
+ *   3. Guard typ === "internal"                         (token confusion protection)
+ *   4. For human tokens: resolve perms from Redis       (derive from role on miss)
+ *   5. Build and return AccessContext                   → buildAccessContext()
+ *
+ * Token kinds:
+ *   - Human  (isMachine: false) — carries accountId, accountRole, perms
+ *   - Machine (isMachine: true) — carries serviceId only; no perms
+ *
+ * Static helpers:
+ *   InternalJwtVerifier.hasPermission / requirePermission / hasRole / requireRole
+ *   are pure functions over AccessContext — safe to call anywhere after
+ *   auth middleware has run and populated req.accessContext.
  */
 const CLOCK_TOLERANCE_SECONDS = 30;
 const JWKS_CACHE_MAX_AGE_MS = 10 * 60 * 1000; // 10 minutes
@@ -56,10 +68,9 @@ const JWKS_FETCH_TIMEOUT_MS = 5000;
 class InternalJwtVerifier {
     constructor(permissionCache) {
         this.permissionCache = permissionCache;
-        const gatewayJwksUri = process.env.GATEWAY_JWKS_URI ??
-            "http://api-gateway:3000/.well-known/jwks.json";
-        this.issuer = process.env.INTERNAL_JWT_ISSUER ?? "discover-cloud:api-gateway";
-        this.audience = process.env.INTERNAL_JWT_AUDIENCE ?? "discover-cloud:internal";
+        const gatewayJwksUri = process.env["GATEWAY_JWKS_URI"] ?? "http://api-gateway:3000/.well-known/jwks.json";
+        this.issuer = process.env["INTERNAL_JWT_ISSUER"] ?? "discover-cloud:api-gateway";
+        this.audience = process.env["INTERNAL_JWT_AUDIENCE"] ?? "discover-cloud:internal";
         this.jwks = jose.createRemoteJWKSet(new URL(gatewayJwksUri), {
             cacheMaxAge: JWKS_CACHE_MAX_AGE_MS,
             timeoutDuration: JWKS_FETCH_TIMEOUT_MS,
@@ -70,20 +81,21 @@ class InternalJwtVerifier {
        Full cryptographic verification + typ guard + clock skew tolerance.
        Returns the raw verified payload.
   
-       Use when you need raw JWT claims (e.g. jti for blacklisting).
-       For everything else, use buildAccessContext().
+       Use this directly when you need raw JWT claims (e.g. jti for
+       blacklisting). For all other cases, use buildAccessContext() which
+       layers permission resolution on top.
     ---------------------------------------------------------------- */
     async verifyInternal(token) {
-        // jose.jwtVerify accepts string directly — the Uint8Array overload is
-        // for raw JWS. The type error comes from jose's union overloads; casting
-        // to the correct overload signature resolves it.
         const { payload } = await jose.jwtVerify(token, this.jwks, {
             issuer: this.issuer,
             audience: this.audience,
             algorithms: ["RS256"],
             clockTolerance: CLOCK_TOLERANCE_SECONDS,
         });
-        // typ guard — rejects external tokens accidentally forwarded downstream
+        // Explicit typ guard — rejects external tokens (e.g. user-facing access
+        // tokens) that were accidentally forwarded past the gateway. This is a
+        // token confusion defence: even if an external token passes signature
+        // verification (same key pair), it will be rejected here.
         if (payload.typ !== "internal") {
             throw new jose.errors.JWTClaimValidationFailed(`Token type mismatch: expected "internal", got "${String(payload.typ)}". ` +
                 `Ensure clients are not forwarding external tokens past the gateway.`, payload, "typ", "check_failed");
@@ -103,7 +115,9 @@ class InternalJwtVerifier {
     ---------------------------------------------------------------- */
     async buildAccessContext(token) {
         const payload = await this.verifyInternal(token);
-        // Machine token — no user context, no permission cache lookup
+        // Machine token — no user context, no permission cache lookup.
+        // Machine services are authorised by their serviceId + X-Internal-Secret,
+        // not by role-based permissions.
         if (payload.isMachine === true) {
             const machinePayload = payload;
             const context = {
@@ -112,29 +126,34 @@ class InternalJwtVerifier {
             };
             return { payload, context };
         }
-        // Human token — resolve permissions from Redis (derive from role on miss)
+        // Human token — resolve permissions from Redis.
+        // On a cache miss, permissions are derived from the static role map
+        // (no DB call — the role is already verified in the JWT payload).
         const humanPayload = payload;
         const perms = await this.permissionCache.resolve(humanPayload.accountId, humanPayload.accountRole);
         const context = {
             kind: "human",
             accountId: humanPayload.accountId,
             accountRole: humanPayload.accountRole,
-            perms, // populated from cache — never from the JWT
+            perms, // always from cache — never read from the JWT directly
         };
         return { payload, context };
     }
     /* ----------------------------------------------------------------
-       Static helpers — use on req.accessContext after auth middleware runs
+       Static helpers — call on req.accessContext after auth middleware runs.
+       These are pure functions; they do not touch Redis or the JWT verifier.
     ---------------------------------------------------------------- */
     /**
-     * Returns true if the context has the given permission.
+     * hasPermission
+     * Returns true if the context carries the given GlobalPermission.
      * Machine contexts always return false — they carry no user permissions.
      */
     static hasPermission(ctx, permission) {
         return ctx.kind === "human" && ctx.perms.includes(permission);
     }
     /**
-     * Throws JWTClaimValidationFailed if the permission is missing.
+     * requirePermission
+     * Throws JWTClaimValidationFailed if the permission is absent.
      * Use in middleware for a one-liner gate:
      *   InternalJwtVerifier.requirePermission(ctx, GlobalPermission.MANAGE_ACCOUNTS);
      */
@@ -144,14 +163,18 @@ class InternalJwtVerifier {
         }
     }
     /**
-     * Returns true if the context carries the given role.
+     * hasRole
+     * Returns true if the context carries the given AccountRole.
      * Machine contexts always return false.
      */
     static hasRole(ctx, role) {
         return ctx.kind === "human" && ctx.accountRole === role;
     }
     /**
+     * requireRole
      * Throws JWTClaimValidationFailed if the role doesn't match.
+     * Prefer requirePermission() for most gates — role checks are for the rare
+     * cases where a specific role (not just a permission) must be enforced.
      */
     static requireRole(ctx, role) {
         if (!InternalJwtVerifier.hasRole(ctx, role)) {

package/dist/middleware/authorize.middleware.d.ts

@@ -1,22 +1,54 @@
 import { Request, Response, NextFunction } from "express";
 import { GlobalPermission } from "../enums";
 /**
- * AUTHORIZE MIDDLEWARE
- * ─────────────────────
- * Permission-gates a route. Must run AFTER require-auth (depends on req.accessContext).
+ * AUTHORIZE MIDDLEWARE  (@discover-cloud/shared)
+ * ───────────────────────────────────────────────
+ * Permission-gates a route. Must run AFTER requireAuth middleware, which
+ * populates req.accessContext from the verified internal JWT + Redis cache.
+ *
  * Uses InternalJwtVerifier.hasPermission — permissions come from the Redis
- * permission cache loaded by RequireAuthMiddleware, not from the JWT itself.
+ * permission cache loaded by RequireAuthMiddleware, never from the JWT itself.
+ *
+ * All error responses go through the shared failure() util to ensure a
+ * consistent ApiErrorResponse shape across every service. The error is
+ * returned directly (not passed to next()) because these are deterministic
+ * middleware guards — there is nothing to recover from downstream.
  *
  * Usage:
- *   router.delete("/accounts/:id",
+ *   router.delete(
+ *     "/accounts/:id",
  *     requireAuth,
  *     authorize(GlobalPermission.DELETE_ACCOUNT),
- *     controller.delete
+ *     controller.delete,
  *   );
  */
 export declare const authorize: (permission: GlobalPermission) => (req: Request, res: Response, next: NextFunction) => void;
 /**
  * authorizeAny
  * Passes if the context has AT LEAST ONE of the provided permissions.
+ * Useful for routes accessible by multiple roles (e.g. SUPPORT_VIEW or VIEW_ANY_ACCOUNT).
+ *
+ * Usage:
+ *   router.get(
+ *     "/accounts/:id",
+ *     requireAuth,
+ *     authorizeAny(GlobalPermission.VIEW_ANY_ACCOUNT, GlobalPermission.SUPPORT_VIEW),
+ *     controller.getById,
+ *   );
  */
 export declare const authorizeAny: (...permissions: GlobalPermission[]) => (req: Request, res: Response, next: NextFunction) => void;
+/**
+ * authorizeAll
+ * Passes only if the context has ALL of the provided permissions.
+ * Use for routes that require a conjunction of permissions (rare — prefer
+ * composing authorize() calls in series if the permissions are independent).
+ *
+ * Usage:
+ *   router.post(
+ *     "/accounts/:id/impersonate",
+ *     requireAuth,
+ *     authorizeAll(GlobalPermission.IMPERSONATE_ACCOUNT, GlobalPermission.MANAGE_ACCOUNTS),
+ *     controller.impersonate,
+ *   );
+ */
+export declare const authorizeAll: (...permissions: GlobalPermission[]) => (req: Request, res: Response, next: NextFunction) => void;

package/dist/middleware/authorize.middleware.js

@@ -1,45 +1,42 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.authorizeAny = exports.authorize = void 0;
+exports.authorizeAll = exports.authorizeAny = exports.authorize = void 0;
 const internal_jwt_verifier_1 = require("../jwt/internal-jwt-verifier");
+const utils_1 = require("../utils");
 /**
- * AUTHORIZE MIDDLEWARE
- * ─────────────────────
- * Permission-gates a route. Must run AFTER require-auth (depends on req.accessContext).
+ * AUTHORIZE MIDDLEWARE  (@discover-cloud/shared)
+ * ───────────────────────────────────────────────
+ * Permission-gates a route. Must run AFTER requireAuth middleware, which
+ * populates req.accessContext from the verified internal JWT + Redis cache.
+ *
  * Uses InternalJwtVerifier.hasPermission — permissions come from the Redis
- * permission cache loaded by RequireAuthMiddleware, not from the JWT itself.
+ * permission cache loaded by RequireAuthMiddleware, never from the JWT itself.
+ *
+ * All error responses go through the shared failure() util to ensure a
+ * consistent ApiErrorResponse shape across every service. The error is
+ * returned directly (not passed to next()) because these are deterministic
+ * middleware guards — there is nothing to recover from downstream.
  *
  * Usage:
- *   router.delete("/accounts/:id",
+ *   router.delete(
+ *     "/accounts/:id",
  *     requireAuth,
  *     authorize(GlobalPermission.DELETE_ACCOUNT),
- *     controller.delete
+ *     controller.delete,
  *   );
  */
 const authorize = (permission) => {
     return (req, res, next) => {
-        // 1. Ensure RequireAuthMiddleware has already run
+        // Ensure RequireAuthMiddleware has already run and populated accessContext.
+        // This is a programming error (wrong middleware order), not a client error,
+        // but we surface it as 401 so it doesn't silently pass through.
         if (!req.accessContext) {
-            res.status(401).json({
-                success: false,
-                error: {
-                    message: "Unauthorized: No access context",
-                    code: "UNAUTHORIZED",
-                    requestId: req.id,
-                },
-            });
+            (0, utils_1.failure)(res, req, "Unauthorized: No access context", "UNAUTHORIZED", 401);
             return;
         }
-        // 2. Check permission against accessContext.perms (loaded from Redis)
+        // Check permission against accessContext.perms (populated from Redis cache).
         if (!internal_jwt_verifier_1.InternalJwtVerifier.hasPermission(req.accessContext, permission)) {
-            res.status(403).json({
-                success: false,
-                error: {
-                    message: `Forbidden: Missing permission ${permission}`,
-                    code: "FORBIDDEN",
-                    requestId: req.id,
-                },
-            });
+            (0, utils_1.failure)(res, req, `Forbidden: Missing permission ${permission}`, "FORBIDDEN", 403);
             return;
         }
         next();
@@ -49,29 +46,57 @@ exports.authorize = authorize;
 /**
  * authorizeAny
  * Passes if the context has AT LEAST ONE of the provided permissions.
+ * Useful for routes accessible by multiple roles (e.g. SUPPORT_VIEW or VIEW_ANY_ACCOUNT).
+ *
+ * Usage:
+ *   router.get(
+ *     "/accounts/:id",
+ *     requireAuth,
+ *     authorizeAny(GlobalPermission.VIEW_ANY_ACCOUNT, GlobalPermission.SUPPORT_VIEW),
+ *     controller.getById,
+ *   );
  */
 const authorizeAny = (...permissions) => {
     return (req, res, next) => {
         if (!req.accessContext) {
-            res.status(401).json({
-                success: false,
-                error: { message: "Unauthorized: No access context", code: "UNAUTHORIZED", requestId: req.id },
-            });
+            (0, utils_1.failure)(res, req, "Unauthorized: No access context", "UNAUTHORIZED", 401);
             return;
         }
         const hasAny = permissions.some((p) => internal_jwt_verifier_1.InternalJwtVerifier.hasPermission(req.accessContext, p));
         if (!hasAny) {
-            res.status(403).json({
-                success: false,
-                error: {
-                    message: `Forbidden: Missing one of [${permissions.join(", ")}]`,
-                    code: "FORBIDDEN",
-                    requestId: req.id,
-                },
-            });
+            (0, utils_1.failure)(res, req, `Forbidden: Missing one of [${permissions.join(", ")}]`, "FORBIDDEN", 403);
             return;
         }
         next();
     };
 };
 exports.authorizeAny = authorizeAny;
+/**
+ * authorizeAll
+ * Passes only if the context has ALL of the provided permissions.
+ * Use for routes that require a conjunction of permissions (rare — prefer
+ * composing authorize() calls in series if the permissions are independent).
+ *
+ * Usage:
+ *   router.post(
+ *     "/accounts/:id/impersonate",
+ *     requireAuth,
+ *     authorizeAll(GlobalPermission.IMPERSONATE_ACCOUNT, GlobalPermission.MANAGE_ACCOUNTS),
+ *     controller.impersonate,
+ *   );
+ */
+const authorizeAll = (...permissions) => {
+    return (req, res, next) => {
+        if (!req.accessContext) {
+            (0, utils_1.failure)(res, req, "Unauthorized: No access context", "UNAUTHORIZED", 401);
+            return;
+        }
+        const missingPermissions = permissions.filter((p) => !internal_jwt_verifier_1.InternalJwtVerifier.hasPermission(req.accessContext, p));
+        if (missingPermissions.length > 0) {
+            (0, utils_1.failure)(res, req, `Forbidden: Missing permissions [${missingPermissions.join(", ")}]`, "FORBIDDEN", 403);
+            return;
+        }
+        next();
+    };
+};
+exports.authorizeAll = authorizeAll;