@discover-cloud/shared 1.0.11 → 1.2.1

package/dist/authorization/permission-cache.service.d.ts

@@ -1,11 +1,24 @@
 import { GlobalPermission, AccountRole } from "../enums";
 export declare class PermissionCacheService {
     private readonly client;
-    private connected;
     constructor();
+    disconnect(): Promise<void>;
     resolve(accountId: string, accountRole: AccountRole): Promise<GlobalPermission[]>;
     invalidate(accountId: string): Promise<void>;
     invalidateMany(accountIds: string[]): Promise<void>;
+    /**
+     * isReady
+     * Authoritative liveness check using the client's own state machine.
+     *
+     * Replaces a manually tracked `connected` boolean, which could drift
+     * after reconnect cycles — the node-redis client reconnects automatically
+     * after a transient failure, but a boolean set only on the first "ready"
+     * event would not reflect subsequent disconnects and reconnects.
+     *
+     * `client.isReady` is kept current by the client's internal state machine
+     * and is the correct primitive for this guard.
+     */
+    private isReady;
     private key;
     private safeGet;
     private safeSet;

package/dist/authorization/permission-cache.service.js

@@ -24,6 +24,20 @@ const permissions_1 = require("./permissions");
  *   - Suspension       → invalidate(accountId)
  *   - Account deletion → invalidate(accountId)
  *
+ * Connection lifecycle:
+ *   - isReady() is the authoritative liveness check — it reflects the actual
+ *     client state (ready / connecting / reconnecting / closing) rather than a
+ *     manually tracked boolean that can drift after automatic reconnects.
+ *   - Call disconnect() in your SIGTERM handler to drain in-flight commands
+ *     and release the TCP socket before the process exits.
+ *
+ * Fault tolerance:
+ *   - All read/write paths guard via isReady() and fall back gracefully.
+ *   - On a cold-cache miss during Redis unavailability, permissions are derived
+ *     from the static role map (degraded but functional — no request is blocked).
+ *   - safeGet validates the parsed cache value shape before returning it;
+ *     malformed entries are treated as cache misses rather than runtime errors.
+ *
  * NOTE: Uses console.* for logging — shared cannot depend on a service-specific
  * logger (pino, winston, etc.). Each service's own logger will capture these
  * via stdout in production.
@@ -32,21 +46,39 @@ const CACHE_TTL_SECONDS = 24 * 60 * 60; // 24 hours
 const KEY_PREFIX = "perms";
 class PermissionCacheService {
     constructor() {
-        this.connected = false;
         this.client = (0, redis_1.createClient)({
-            url: process.env.REDIS_URL ?? "redis://localhost:6379",
+            url: process.env["REDIS_URL"] ?? "redis://localhost:6379",
         });
         this.client.on("error", (err) => {
             console.error("[PermissionCache] Redis client error", err);
         });
         this.client.on("ready", () => {
-            this.connected = true;
-            console.info("[PermissionCache] Redis connected");
+            console.info("[PermissionCache] Redis connected and ready");
         });
+        this.client.on("reconnecting", () => {
+            console.warn("[PermissionCache] Redis reconnecting...");
+        });
+        // Connect asynchronously — all read/write methods guard via isReady()
+        // and fall back gracefully, so startup is non-blocking.
         this.client.connect().catch((err) => {
-            console.error("[PermissionCache] Redis connection failed", err);
+            console.error("[PermissionCache] Redis initial connection failed", err);
         });
     }
+    /* ----------------------------------------------------------------
+       disconnect
+       Gracefully closes the Redis connection. Call during service shutdown
+       (SIGTERM handler) to drain in-flight commands and release the TCP
+       socket before the process exits.
+    ---------------------------------------------------------------- */
+    async disconnect() {
+        try {
+            await this.client.quit();
+            console.info("[PermissionCache] Redis connection closed");
+        }
+        catch (err) {
+            console.error("[PermissionCache] Error during disconnect", err);
+        }
+    }
     /* ----------------------------------------------------------------
        resolve
        Returns permissions for an account, loading from cache or deriving
@@ -59,12 +91,12 @@ class PermissionCacheService {
         const cached = await this.safeGet(accountId);
         if (cached !== null)
             return cached;
-        // Cache miss — derive from role map (no DB call)
-        const perms = [
-            ...(permissions_1.globalRolePermissions[accountRole] ?? []),
-        ];
-        // Write back (fire-and-forget — don't block the request)
-        this.safeSet(accountId, perms).catch(() => { });
+        // Cache miss — derive from role map (no DB call needed; the role is
+        // already verified in the JWT payload by the time we get here).
+        const perms = [...(permissions_1.globalRolePermissions[accountRole] ?? [])];
+        // Write back fire-and-forget — safeSet swallows errors internally,
+        // so we don't await or attach a catch here.
+        void this.safeSet(accountId, perms);
         return perms;
     }
     /* ----------------------------------------------------------------
@@ -73,22 +105,32 @@ class PermissionCacheService {
        Call on: role change, suspension, account deletion.
     ---------------------------------------------------------------- */
     async invalidate(accountId) {
+        if (!this.isReady()) {
+            // Skip deletion — the stale entry will expire via TTL at worst.
+            console.warn(`[PermissionCache] Skipping invalidation for ${accountId} — Redis not ready`);
+            return;
+        }
         try {
             await this.client.del(this.key(accountId));
             console.info(`[PermissionCache] Invalidated: ${accountId}`);
         }
         catch (err) {
-            // Log but don't throw — stale entry expires via TTL at worst
+            // Log but don't throw — stale entry expires via TTL at worst.
             console.error(`[PermissionCache] Failed to invalidate: ${accountId}`, err);
         }
     }
     /* ----------------------------------------------------------------
        invalidateMany
        Batch invalidation — use when a role definition changes globally.
+       Sends a single DEL with multiple keys (O(n) in Redis, one round-trip).
     ---------------------------------------------------------------- */
     async invalidateMany(accountIds) {
         if (accountIds.length === 0)
             return;
+        if (!this.isReady()) {
+            console.warn(`[PermissionCache] Skipping batch invalidation (${accountIds.length} entries) — Redis not ready`);
+            return;
+        }
         try {
             const keys = accountIds.map((id) => this.key(id));
             await this.client.del(keys);
@@ -101,28 +143,54 @@ class PermissionCacheService {
     /* ----------------------------------------------------------------
        Private helpers
     ---------------------------------------------------------------- */
+    /**
+     * isReady
+     * Authoritative liveness check using the client's own state machine.
+     *
+     * Replaces a manually tracked `connected` boolean, which could drift
+     * after reconnect cycles — the node-redis client reconnects automatically
+     * after a transient failure, but a boolean set only on the first "ready"
+     * event would not reflect subsequent disconnects and reconnects.
+     *
+     * `client.isReady` is kept current by the client's internal state machine
+     * and is the correct primitive for this guard.
+     */
+    isReady() {
+        return this.client.isReady;
+    }
     key(accountId) {
         return `${KEY_PREFIX}:${accountId}`;
     }
     async safeGet(accountId) {
-        if (!this.connected)
+        if (!this.isReady())
             return null;
         try {
             const raw = await this.client.get(this.key(accountId));
             if (!raw)
                 return null;
-            return JSON.parse(raw);
+            const parsed = JSON.parse(raw);
+            // Validate shape before trusting the cached value. A malformed entry
+            // (e.g. from a prior schema change or a manual key mutation) should
+            // produce a cache miss, not a silent type error downstream.
+            if (!Array.isArray(parsed)) {
+                console.warn(`[PermissionCache] Unexpected cache shape for ${accountId}, treating as miss`);
+                return null;
+            }
+            return parsed;
         }
         catch (err) {
+            // JSON.parse failure or Redis error — bypass the cache gracefully.
             console.warn(`[PermissionCache] Cache get failed for ${accountId}, bypassing`, err);
             return null;
         }
     }
     async safeSet(accountId, perms) {
-        if (!this.connected)
+        if (!this.isReady())
             return;
         try {
-            await this.client.set(this.key(accountId), JSON.stringify(perms), { EX: CACHE_TTL_SECONDS });
+            await this.client.set(this.key(accountId), JSON.stringify(perms), {
+                EX: CACHE_TTL_SECONDS,
+            });
         }
         catch (err) {
             console.warn(`[PermissionCache] Cache set failed for ${accountId}`, err);

package/dist/authorization/permissions.d.ts

@@ -8,10 +8,11 @@ import { AccessContext } from "../types";
  * derives from this map on a cold cache miss.
  *
  * Design principles:
- *   - SUPERADMIN gets all permissions (dynamically, not hardcoded list)
+ *   - SUPERADMIN gets all permissions (dynamically via Object.values, not a
+ *     hardcoded list — so new permissions are automatically granted on addition)
  *   - Each role has only the minimum permissions it needs (least privilege)
  *   - Permissions are additive — no role inherits from another at runtime
- *   - Adding a new permission: add to the enum above, then grant it here
+ *   - Adding a new permission: add to GlobalPermission enum, then grant it here
  *
  * ┌─────────────┬──────────────────────────────────────────────────────┐
  * │ Role        │ Key permissions                                       │
@@ -27,7 +28,7 @@ export declare const globalRolePermissions: Record<AccountRole, readonly GlobalP
 /**
  * ORG ROLE PERMISSION MAP  (future work)
  * ────────────────────────────────────────
- * Org permissions are NOT in the JWT — they're fetched from the DB
+ * Org permissions are NOT embedded in the JWT — they're fetched from the DB
  * by tenant middleware within each service because:
  *   1. Org membership changes frequently (invites, role changes, removal)
  *   2. A user can be in multiple orgs with different roles
@@ -35,15 +36,20 @@ export declare const globalRolePermissions: Record<AccountRole, readonly GlobalP
  *
  * This map is used by tenant middleware for the DB-free fast path:
  * if the org role is already known (e.g. from a prior DB fetch cached in
- * Redis), derive permissions from here rather than re-querying the DB.
+ * Redis), derive permissions here rather than re-querying the DB.
+ *
+ * NOTE: All entries use OrgPermission values only — no cross-namespace mixing
+ * with GlobalPermission. Org admin membership management is expressed via
+ * the dedicated OrgPermission.* values below.
  */
 export declare const orgRolePermissions: Record<OrganizationRole, readonly OrgPermission[]>;
 /**
  * hasGlobalPermission
- * Checks if a GlobalPermission is in the AccessContext's perms array.
- * Perms come from the Redis permission cache, not from the JWT directly.
+ * Checks if a GlobalPermission is present in the AccessContext's perms array.
+ * Perms are populated from the Redis permission cache (derived from the role
+ * map on a miss) — never read directly from the JWT.
  *
- * This is the primary check for platform-level authorization.
+ * Machine contexts always return false — they carry no user permissions.
  */
 export declare const hasGlobalPermission: (ctx: AccessContext, permission: GlobalPermission) => boolean;
 /**
@@ -51,18 +57,16 @@ export declare const hasGlobalPermission: (ctx: AccessContext, permission: Globa
  * Unified permission check for both GlobalPermission and OrgPermission.
  *
  * GlobalPermission → checked against ctx.perms (Redis cache, derived from role)
- * OrgPermission    → returns false here; handled by tenant middleware in each
- *                    service via DB lookup. This function is intentionally not
- *                    the place for org permission checks.
- *
- * This makes the boundary explicit: callers that need org permission checks
- * should use their service's tenant middleware, not isAllowed().
+ * OrgPermission    → intentionally returns false here; handled by tenant
+ *                    middleware in each service via DB lookup. This function
+ *                    is not the place for org permission checks — the boundary
+ *                    is explicit by design.
  */
 export declare const isAllowed: (ctx: AccessContext, permission: GlobalPermission | OrgPermission) => boolean;
 /**
  * isSuperAdmin
- * Convenience guard for the rare cases where superadmin-only logic
- * is needed beyond a single permission check.
+ * Convenience guard for cases where superadmin-only logic is needed
+ * beyond a single permission check (e.g. bypassing org scoping entirely).
  */
 export declare const isSuperAdmin: (ctx: AccessContext) => boolean;
 /**

package/dist/authorization/permissions.js

@@ -10,10 +10,11 @@ const enums_1 = require("../enums");
  * derives from this map on a cold cache miss.
  *
  * Design principles:
- *   - SUPERADMIN gets all permissions (dynamically, not hardcoded list)
+ *   - SUPERADMIN gets all permissions (dynamically via Object.values, not a
+ *     hardcoded list — so new permissions are automatically granted on addition)
  *   - Each role has only the minimum permissions it needs (least privilege)
  *   - Permissions are additive — no role inherits from another at runtime
- *   - Adding a new permission: add to the enum above, then grant it here
+ *   - Adding a new permission: add to GlobalPermission enum, then grant it here
  *
  * ┌─────────────┬──────────────────────────────────────────────────────┐
  * │ Role        │ Key permissions                                       │
@@ -44,25 +45,25 @@ exports.globalRolePermissions = {
         enums_1.GlobalPermission.SUPPORT_WRITE,
     ],
     [enums_1.AccountRole.SUPPORT]: [
-        // Read-only access to user data and cost data for support purposes
-        // Cannot write, cannot manage accounts, cannot access system internals
+        // Read-only access to user data and cost data for support purposes.
+        // Cannot write, cannot manage accounts, cannot access system internals.
         enums_1.GlobalPermission.VIEW_ANY_ACCOUNT,
         enums_1.GlobalPermission.VIEW_ANY_COST_DATA,
         enums_1.GlobalPermission.SUPPORT_VIEW,
     ],
     [enums_1.AccountRole.MODERATOR]: [
-        // Only content moderation — no access to user accounts or cost data
+        // Content moderation only — no access to user accounts or cost data.
         enums_1.GlobalPermission.MODERATE_CONTENT,
     ],
-    // Standard users have zero global permissions.
-    // All their data access is handled at the service level
+    // Standard users carry zero global permissions.
+    // All their data access is gated at the service layer
     // (they can only see their own cost data, their own account, etc.)
     [enums_1.AccountRole.USER]: [],
 };
 /**
  * ORG ROLE PERMISSION MAP  (future work)
  * ────────────────────────────────────────
- * Org permissions are NOT in the JWT — they're fetched from the DB
+ * Org permissions are NOT embedded in the JWT — they're fetched from the DB
  * by tenant middleware within each service because:
  *   1. Org membership changes frequently (invites, role changes, removal)
  *   2. A user can be in multiple orgs with different roles
@@ -70,12 +71,15 @@ exports.globalRolePermissions = {
  *
  * This map is used by tenant middleware for the DB-free fast path:
  * if the org role is already known (e.g. from a prior DB fetch cached in
- * Redis), derive permissions from here rather than re-querying the DB.
+ * Redis), derive permissions here rather than re-querying the DB.
+ *
+ * NOTE: All entries use OrgPermission values only — no cross-namespace mixing
+ * with GlobalPermission. Org admin membership management is expressed via
+ * the dedicated OrgPermission.* values below.
  */
 exports.orgRolePermissions = {
     [enums_1.OrganizationRole.OWNER]: Object.values(enums_1.OrgPermission), // Full org control
     [enums_1.OrganizationRole.ADMIN]: [
-        enums_1.GlobalPermission.MANAGE_ACCOUNTS, // intentional re-use shape — org admin manages org members
         enums_1.OrgPermission.MANAGE_ORG_SETTINGS,
         enums_1.OrgPermission.INVITE_MEMBERS,
         enums_1.OrgPermission.REMOVE_MEMBERS,
@@ -114,10 +118,11 @@ exports.orgRolePermissions = {
 ==================================================================== */
 /**
  * hasGlobalPermission
- * Checks if a GlobalPermission is in the AccessContext's perms array.
- * Perms come from the Redis permission cache, not from the JWT directly.
+ * Checks if a GlobalPermission is present in the AccessContext's perms array.
+ * Perms are populated from the Redis permission cache (derived from the role
+ * map on a miss) — never read directly from the JWT.
  *
- * This is the primary check for platform-level authorization.
+ * Machine contexts always return false — they carry no user permissions.
  */
 const hasGlobalPermission = (ctx, permission) => {
     if (ctx.kind !== "human")
@@ -130,12 +135,10 @@ exports.hasGlobalPermission = hasGlobalPermission;
  * Unified permission check for both GlobalPermission and OrgPermission.
  *
  * GlobalPermission → checked against ctx.perms (Redis cache, derived from role)
- * OrgPermission    → returns false here; handled by tenant middleware in each
- *                    service via DB lookup. This function is intentionally not
- *                    the place for org permission checks.
- *
- * This makes the boundary explicit: callers that need org permission checks
- * should use their service's tenant middleware, not isAllowed().
+ * OrgPermission    → intentionally returns false here; handled by tenant
+ *                    middleware in each service via DB lookup. This function
+ *                    is not the place for org permission checks — the boundary
+ *                    is explicit by design.
  */
 const isAllowed = (ctx, permission) => {
     if (ctx.kind !== "human")
@@ -150,8 +153,8 @@ const isAllowed = (ctx, permission) => {
 exports.isAllowed = isAllowed;
 /**
  * isSuperAdmin
- * Convenience guard for the rare cases where superadmin-only logic
- * is needed beyond a single permission check.
+ * Convenience guard for cases where superadmin-only logic is needed
+ * beyond a single permission check (e.g. bypassing org scoping entirely).
  */
 const isSuperAdmin = (ctx) => {
     if (ctx.kind !== "human")

package/dist/dtos/auth-service.dto.d.ts

@@ -1,4 +1,17 @@
 import { AccountStatus } from "../enums";
+/**
+ * AUTH SERVICE DTOs  (@discover-cloud/shared)
+ * ─────────────────────────────────────────────
+ * Internal data shapes produced by the auth service.
+ *
+ * SECURITY RULE: DTOs containing secrets (token, hash fields) must NEVER
+ * be returned directly in HTTP responses. They exist so internal service
+ * methods have typed return values — mappers are responsible for stripping
+ * secrets before anything reaches the wire.
+ *
+ * Secret fields are annotated with  // SECRET — internal use only
+ * to make accidental exposure visible at a glance during code review.
+ */
 export interface AccountDto {
     id: string;
     email: string;

package/dist/dtos/cloud-service.dto.d.ts

@@ -1,18 +1,27 @@
 import { CloudProvider, CloudAccountStatus, AwsAuthMethod, GcpAuthMethod, AzureAuthMethod, SyncStatus, SyncType } from "../enums";
 /**
- * CLOUD SERVICE DTOs
- * ───────────────────
- * Shapes returned by the cloud service over HTTP.
+ * CLOUD SERVICE DTOs  (@discover-cloud/shared)
+ * ─────────────────────────────────────────────
+ * Shapes produced and consumed by the cloud service.
  *
- * Date fields are ISO 8601 strings at the HTTP boundary —
- * JSON has no Date type. Domain models use Date internally;
- * these DTOs are the serialized form sent to clients.
+ * Date handling:
+ *   JSON has no Date type. Domain models use Date internally; these DTOs
+ *   are the serialised form at the HTTP boundary — all timestamps are ISO 8601 strings.
  *
- * CloudAccountDto never includes encryptedCredentials —
- * credentials are write-only.
+ * Credential handling:
+ *   CloudAccountDto intentionally omits encryptedCredentials — credentials
+ *   are write-only. The connect DTOs accept credentials as `unknown` because
+ *   the shape differs per provider and per authMethod; Zod schemas in the
+ *   cloud service validate the concrete shape at runtime.
  *
- * SyncJobDto is read-only — sync jobs are created internally
- * by the orchestrator and exposed for status polling only.
+ * SyncJobDto:
+ *   Read-only. Sync jobs are created internally by the scheduler and exposed
+ *   for status polling only — clients never POST a sync job directly.
+ *
+ * Provider push DTOs (CloudCostRecordDto, CloudResourceDto, CloudBudgetDto):
+ *   Used when cloud-service pushes collected data to insights-service.
+ *   They include cloudAccountId for scoping — insights-service uses this to
+ *   associate records with the correct account without re-fetching.
  */
 export interface CloudAccountDto {
     id: string;
@@ -27,16 +36,19 @@ export interface CloudAccountDto {
     createdAt: string;
     updatedAt: string;
 }
+/** Credential payload for a new AWS cloud account connection. */
 export interface ConnectAwsAccountDto {
     alias: string;
     authMethod: AwsAuthMethod;
     credentials: unknown;
 }
+/** Credential payload for a new GCP cloud account connection. */
 export interface ConnectGcpAccountDto {
     alias: string;
     authMethod: GcpAuthMethod;
     credentials: unknown;
 }
+/** Credential payload for a new Azure cloud account connection. */
 export interface ConnectAzureAccountDto {
     alias: string;
     authMethod: AzureAuthMethod;
@@ -57,6 +69,7 @@ export interface SyncJobDto {
     updatedAt: string;
 }
 export interface CloudCostRecordDto {
+    cloudAccountId: string;
     provider: CloudProvider;
     service: string;
     region: string;
@@ -67,6 +80,7 @@ export interface CloudCostRecordDto {
     usageType: string;
 }
 export interface CloudResourceDto {
+    cloudAccountId: string;
     provider: CloudProvider;
     resourceType: string;
     resourceId: string;
@@ -77,6 +91,7 @@ export interface CloudResourceDto {
     metadata: Record<string, unknown>;
 }
 export interface CloudBudgetDto {
+    cloudAccountId: string;
     name: string;
     limitAmount: number;
     currency: string;

package/dist/dtos/insights-service.dto.d.ts

@@ -1,11 +1,21 @@
 import { CloudProvider } from "../enums";
 /**
- * INSIGHTS SERVICE DTOs
- * ──────────────────────
- * Push payloads: cloud-service → insights-service (internal, over HTTP)
- * Record DTOs:   insights-service → frontend (public, over HTTP)
- * Query DTOs:    internal query params (never cross HTTP, Date is fine)
- * Summary DTOs:  assembled aggregations (no domain model, no mapper)
+ * INSIGHTS SERVICE DTOs  (@discover-cloud/shared)
+ * ─────────────────────────────────────────────────
+ * Four groups of types, each with a distinct role:
+ *
+ * Push payloads   — cloud-service → insights-service (internal HTTP).
+ *                   Carry raw provider data collected during a sync job.
+ *
+ * Record DTOs     — insights-service → frontend (public HTTP).
+ *                   Stored/enriched records returned to clients.
+ *                   All timestamps are ISO 8601 strings (JSON has no Date).
+ *
+ * Query DTO       — internal query params passed between service layers.
+ *                   Never crosses an HTTP boundary — Date is fine here.
+ *
+ * Summary DTOs    — assembled aggregations with no corresponding domain
+ *                   model or mapper. Built directly from DB query results.
  */
 export interface PushCostItem {
     service: string;
@@ -54,7 +64,7 @@ export interface CostRecordDto {
     id: string;
     cloudAccountId: string;
     userId: string;
-    provider: string;
+    provider: CloudProvider;
     service: string;
     region: string;
     amount: number;
@@ -68,7 +78,7 @@ export interface ResourceRecordDto {
     id: string;
     cloudAccountId: string;
     userId: string;
-    provider: string;
+    provider: CloudProvider;
     resourceType: string;
     resourceId: string;
     region: string;
@@ -93,6 +103,12 @@ export interface BudgetRecordDto {
     isForecastOver: boolean;
     recordedAt: string;
 }
+/**
+ * CostQueryDto
+ * Used by the insights-service query layer internally.
+ * Date fields are fine here — this never reaches JSON serialisation.
+ * If this ever needs to cross HTTP, convert from/to to ISO 8601 strings.
+ */
 export interface CostQueryDto {
     userId?: string;
     cloudAccountId?: string;

package/dist/dtos/response.dto.d.ts

@@ -1,3 +1,26 @@
+/**
+ * RESPONSE DTOs  (@discover-cloud/shared)
+ * ─────────────────────────────────────────
+ * Shared HTTP response shapes used across all services.
+ * Every response — success or error — is wrapped in the ApiSuccessResponse
+ * or ApiErrorResponse envelope so clients have a consistent shape to key on.
+ *
+ * Envelope shape:
+ *   {
+ *     success: true,
+ *     data: T,
+ *     meta: { requestId, timestamp }
+ *   }
+ *   or
+ *   {
+ *     success: false,
+ *     error: { code, message, details? },
+ *     meta: { requestId, timestamp }
+ *   }
+ *
+ * The success() and failure() utils in shared/utils construct these
+ * envelopes — don't build them manually in controllers.
+ */
 export interface ApiMeta {
     requestId: string;
     timestamp: string;
@@ -17,25 +40,37 @@ export interface ApiErrorResponse {
     meta: ApiMeta;
 }
 /**
- * Returned on login / token refresh.
- * accessToken goes in the response body.
- * refreshToken goes in an HttpOnly cookie — not in the body.
- * Only include refreshToken here if your client explicitly needs it
- * (e.g. mobile clients that can't use cookies).
+ * TokensResponseDto
+ * Returned on successful login or token refresh.
+ *
+ * accessToken  — short-lived JWT returned in the response body.
+ * refreshToken — long-lived token sent as an HttpOnly cookie by the auth
+ *                service; it is intentionally absent from this DTO.
+ *                Mobile clients that cannot use cookies should request a
+ *                separate endpoint that returns the refresh token explicitly.
  */
 export interface TokensResponseDto {
     accessToken: string;
 }
-/** Generic message — use for simple confirmations */
+/**
+ * MessageResponseDto
+ * Use for simple confirmations where no structured data is needed.
+ * Example: { message: "Email verification sent" }
+ */
 export interface MessageResponseDto {
     message: string;
 }
 /**
- * Generic action confirmation — use when the client needs to know
- * which action was performed (e.g. in a polling or event-driven context).
+ * ActionResponseDto
+ * Use when the client needs a machine-readable signal of what happened,
+ * e.g. for polling loops, event-driven UIs, or audit trails.
  *
- * action: machine-readable string, e.g. "account.suspended", "session.revoked"
- * message: human-readable description
+ * action  — stable machine-readable identifier, e.g. "account.suspended"
+ * message — human-readable description for display or logging
+ *
+ * Boolean-only DTOs (LoggedOutResponseDto, SuspendedResponseDto, etc.)
+ * are intentionally collapsed into this shape — a boolean that is always
+ * true on a 200 response carries no additional information.
  */
 export interface ActionResponseDto {
     action: string;
@@ -49,7 +84,42 @@ export interface PaginationMeta {
     hasNext: boolean;
     hasPrev: boolean;
 }
+/**
+ * PaginatedResponseDto
+ * Wrap paginated list results in this before passing to success().
+ *
+ * Usage:
+ *   success<PaginatedResponseDto<CloudAccountDto>>(res, req, {
+ *     items: accounts,
+ *     pagination: { page, pageSize, totalItems, totalPages, hasNext, hasPrev },
+ *   });
+ */
 export interface PaginatedResponseDto<T> {
     items: T[];
     pagination: PaginationMeta;
 }
+/**
+ * LoginResultDto
+ * Internal auth service response returned after successful login.
+ *
+ * The optional cookie metadata allows controllers or gateways
+ * to apply refresh-token cookies without coupling shared DTOs
+ * to a specific HTTP framework.
+ */
+export interface CookieMetadataDto {
+    httpOnly?: boolean;
+    secure?: boolean;
+    sameSite?: "strict" | "lax" | "none";
+    maxAge?: number;
+    path?: string;
+    domain?: string;
+}
+export interface LoginResultCookieDto {
+    name: string;
+    value: string;
+    options: CookieMetadataDto;
+}
+export interface LoginResultDto {
+    tokens: TokensResponseDto;
+    cookie?: LoginResultCookieDto;
+}