@discover-cloud/shared 1.2.9 → 1.4.0

package/dist/authorization/index.d.ts

@@ -1,2 +1,2 @@
-export * from "./permissions";
-export * from "./permission-cache.service";
+export * from './permission-cache.service';
+export * from './permission-checker';

package/dist/authorization/index.js

@@ -14,5 +14,5 @@ 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("./permissions"), exports);
 __exportStar(require("./permission-cache.service"), exports);
+__exportStar(require("./permission-checker"), exports);

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

@@ -1,25 +1,113 @@
-import { GlobalPermission, AccountRole } from "../enums";
+/**
+ * @file permission-cache.service.ts
+ * @description Redis-backed permission cache for RBAC authorization.
+ * Stores resolved permission sets for platform, organization, and workspace scopes.
+ * Does not calculate permissions — RBAC resolution is database-driven.
+ */
+/**
+ * Redis-backed permission cache.
+ *
+ * Source of truth:
+ *
+ * User / Account
+ *      ↓
+ * RoleAssignment
+ *      ↓
+ * Role
+ *      ↓
+ * Permission
+ *
+ * This service only caches the resolved permission keys.
+ */
 export declare class PermissionCacheService {
     private readonly client;
+    /**
+     * Initializes Redis client and connection listeners.
+     */
     constructor();
+    /**
+     * Resolves platform-level permissions.
+     *
+     * @param {string} accountId - Account ID.
+     * @param {Function} resolver - Database permission resolver.
+     * @returns {Promise<string[]>} Permission keys.
+     */
+    resolvePlatformPermissions(accountId: string, resolver: () => Promise<string[]>): Promise<string[]>;
+    /**
+     * Resolves organization-scoped permissions.
+     *
+     * @param {string} userId - User ID.
+     * @param {string} organizationId - Organization ID.
+     * @param {Function} resolver - Database permission resolver.
+     * @returns {Promise<string[]>} Permission keys.
+     */
+    resolveOrganizationPermissions(userId: string, organizationId: string, resolver: () => Promise<string[]>): Promise<string[]>;
+    /**
+     * Resolves workspace-scoped permissions.
+     *
+     * @param {string} userId - User ID.
+     * @param {string} workspaceId - Workspace ID.
+     * @param {Function} resolver - Database permission resolver.
+     * @returns {Promise<string[]>} Permission keys.
+     */
+    resolveWorkspacePermissions(userId: string, workspaceId: string, resolver: () => Promise<string[]>): Promise<string[]>;
+    /**
+     * Invalidates platform permission cache.
+     *
+     * @param {string} accountId - Account ID.
+     */
+    invalidatePlatform(accountId: string): Promise<void>;
+    /**
+     * Invalidates organization permission cache.
+     *
+     * @param {string} userId - User ID.
+     * @param {string} organizationId - Organization ID.
+     */
+    invalidateOrganization(userId: string, organizationId: string): Promise<void>;
+    /**
+     * Invalidates workspace permission cache.
+     *
+     * @param {string} userId - User ID.
+     * @param {string} workspaceId - Workspace ID.
+     */
+    invalidateWorkspace(userId: string, workspaceId: string): Promise<void>;
+    /**
+     * Gracefully closes Redis connection.
+     */
     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.
+     * Resolves permissions using cache-aside pattern.
+     *
+     * Redis hit:
+     * cache → return
+     *
+     * Redis miss:
+     * database → cache → return
+     *
+     * @param {string} key - Cache key.
+     * @param {Function} resolver - Database resolver.
+     */
+    private resolve;
+    /**
+     * Reads permission list from Redis.
+     *
+     * @param {string} key - Cache key.
+     */
+    private get;
+    /**
+     * Stores permission list in Redis.
      *
-     * 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.
+     * @param {string} key - Cache key.
+     * @param {string[]} permissions - Permission keys.
+     */
+    private set;
+    /**
+     * Deletes permission cache.
      *
-     * `client.isReady` is kept current by the client's internal state machine
-     * and is the correct primitive for this guard.
+     * @param {string} key - Cache key.
      */
-    private isReady;
-    private key;
-    private safeGet;
-    private safeSet;
+    private delete;
+    private platformKey;
+    private organizationKey;
+    private workspaceKey;
 }

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

@@ -1,200 +1,229 @@
 "use strict";
+/**
+ * @file permission-cache.service.ts
+ * @description Redis-backed permission cache for RBAC authorization.
+ * Stores resolved permission sets for platform, organization, and workspace scopes.
+ * Does not calculate permissions — RBAC resolution is database-driven.
+ */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.PermissionCacheService = void 0;
 const redis_1 = require("redis");
-const permissions_1 = require("./permissions");
+const env_util_1 = require("../utils/env.util");
+const CACHE_TTL_SECONDS = 24 * 60 * 60; // 24 hours
+const PLATFORM_PREFIX = 'perms:platform';
+const ORG_PREFIX = 'perms:org';
+const WORKSPACE_PREFIX = 'perms:workspace';
 /**
- * PERMISSION CACHE SERVICE  (@discover-cloud/shared)
- * ─────────────────────────────────────────────────────
- * Redis-backed permission cache. Sits between JWT verification and route
- * handlers — loads permissions for a verified accountId + role, caches
- * them, and exposes invalidation for role changes and account lifecycle events.
- *
- * Cache key:   perms:{accountId}
- * Cache value: JSON array of GlobalPermission
- * TTL:         24 hours (auto-evicted; role changes trigger explicit invalidation)
- *
- * Cold cache strategy:
- *   Derive from globalRolePermissions (role → perms map).
- *   No DB call — the role is already verified in the JWT, and all permissions
- *   are statically derived from it.
+ * Redis-backed permission cache.
  *
- * Invalidation triggers:
- *   - Role change      → invalidate(accountId)
- *   - Suspension       → invalidate(accountId)
- *   - Account deletion → invalidate(accountId)
+ * Source of truth:
  *
- * 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.
+ * User / Account
+ *      ↓
+ * RoleAssignment
+ *      ↓
+ * Role
+ *      ↓
+ * Permission
  *
- * 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.
+ * This service only caches the resolved permission keys.
  */
-const CACHE_TTL_SECONDS = 24 * 60 * 60; // 24 hours
-const KEY_PREFIX = "perms";
 class PermissionCacheService {
+    /**
+     * Initializes Redis client and connection listeners.
+     */
     constructor() {
         this.client = (0, redis_1.createClient)({
-            url: process.env["REDIS_URL"] ?? "redis://localhost:6379",
+            url: (0, env_util_1.getEnvOptional)('REDIS_URL') ?? 'redis://localhost:6379',
         });
-        this.client.on("error", (err) => {
-            console.error("[PermissionCache] Redis client error", err);
+        this.client.on('error', (err) => {
+            console.error('[PermissionCache] Redis error', err);
         });
-        this.client.on("ready", () => {
-            console.info("[PermissionCache] Redis connected and ready");
+        this.client.on('ready', () => {
+            console.info('[PermissionCache] Redis ready');
         });
-        this.client.on("reconnecting", () => {
-            console.warn("[PermissionCache] Redis reconnecting...");
+        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 initial connection failed", err);
+            console.error('[PermissionCache] Redis 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);
-        }
+    /* ---------------------------------------------------------------------------
+       Permission Resolution
+    --------------------------------------------------------------------------- */
+    /**
+     * Resolves platform-level permissions.
+     *
+     * @param {string} accountId - Account ID.
+     * @param {Function} resolver - Database permission resolver.
+     * @returns {Promise<string[]>} Permission keys.
+     */
+    async resolvePlatformPermissions(accountId, resolver) {
+        return this.resolve(this.platformKey(accountId), resolver);
     }
-    /* ----------------------------------------------------------------
-       resolve
-       Returns permissions for an account, loading from cache or deriving
-       from the role map on a miss.
-  
-       Never throws — on any Redis failure it falls back to deriving
-       from the role map directly (degraded but functional).
-    ---------------------------------------------------------------- */
-    async resolve(accountId, accountRole) {
-        const cached = await this.safeGet(accountId);
-        if (cached !== null)
-            return cached;
-        // 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;
+    /* --------------------------------------------------------------------------
+     resolveOrganizationPermissions
+  -------------------------------------------------------------------------- */
+    /**
+     * Resolves organization-scoped permissions.
+     *
+     * @param {string} userId - User ID.
+     * @param {string} organizationId - Organization ID.
+     * @param {Function} resolver - Database permission resolver.
+     * @returns {Promise<string[]>} Permission keys.
+     */
+    async resolveOrganizationPermissions(userId, organizationId, resolver) {
+        return this.resolve(this.organizationKey(userId, organizationId), resolver);
     }
-    /* ----------------------------------------------------------------
-       invalidate
-       Removes a specific account's permission cache entry.
-       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.
-            console.error(`[PermissionCache] Failed to invalidate: ${accountId}`, err);
-        }
+    /* --------------------------------------------------------------------------
+     resolveWorkspacePermissions
+  -------------------------------------------------------------------------- */
+    /**
+     * Resolves workspace-scoped permissions.
+     *
+     * @param {string} userId - User ID.
+     * @param {string} workspaceId - Workspace ID.
+     * @param {Function} resolver - Database permission resolver.
+     * @returns {Promise<string[]>} Permission keys.
+     */
+    async resolveWorkspacePermissions(userId, workspaceId, resolver) {
+        return this.resolve(this.workspaceKey(userId, workspaceId), resolver);
     }
-    /* ----------------------------------------------------------------
-       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);
-            console.info(`[PermissionCache] Batch invalidated ${accountIds.length} entries`);
-        }
-        catch (err) {
-            console.error("[PermissionCache] Batch invalidation failed", err);
-        }
+    /* ---------------------------------------------------------------------------
+       Cache Invalidation
+    --------------------------------------------------------------------------- */
+    /**
+     * Invalidates platform permission cache.
+     *
+     * @param {string} accountId - Account ID.
+     */
+    async invalidatePlatform(accountId) {
+        await this.delete(this.platformKey(accountId));
     }
-    /* ----------------------------------------------------------------
-       Private helpers
-    ---------------------------------------------------------------- */
+    /* --------------------------------------------------------------------------
+     invalidateOrganization
+  -------------------------------------------------------------------------- */
     /**
-     * isReady
-     * Authoritative liveness check using the client's own state machine.
+     * Invalidates organization permission cache.
      *
-     * 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.
+     * @param {string} userId - User ID.
+     * @param {string} organizationId - Organization ID.
+     */
+    async invalidateOrganization(userId, organizationId) {
+        await this.delete(this.organizationKey(userId, organizationId));
+    }
+    /* --------------------------------------------------------------------------
+     invalidateWorkspace
+  -------------------------------------------------------------------------- */
+    /**
+     * Invalidates workspace permission cache.
      *
-     * `client.isReady` is kept current by the client's internal state machine
-     * and is the correct primitive for this guard.
+     * @param {string} userId - User ID.
+     * @param {string} workspaceId - Workspace ID.
+     */
+    async invalidateWorkspace(userId, workspaceId) {
+        await this.delete(this.workspaceKey(userId, workspaceId));
+    }
+    /* --------------------------------------------------------------------------
+     disconnect
+  -------------------------------------------------------------------------- */
+    /**
+     * Gracefully closes Redis connection.
      */
-    isReady() {
-        return this.client.isReady;
+    async disconnect() {
+        await this.client.quit();
     }
-    key(accountId) {
-        return `${KEY_PREFIX}:${accountId}`;
+    /* ---------------------------------------------------------------------------
+       Internal Cache Helpers
+    --------------------------------------------------------------------------- */
+    /**
+     * Resolves permissions using cache-aside pattern.
+     *
+     * Redis hit:
+     * cache → return
+     *
+     * Redis miss:
+     * database → cache → return
+     *
+     * @param {string} key - Cache key.
+     * @param {Function} resolver - Database resolver.
+     */
+    async resolve(key, resolver) {
+        const cached = await this.get(key);
+        if (cached !== null) {
+            return cached;
+        }
+        const permissions = await resolver();
+        await this.set(key, permissions);
+        return permissions;
     }
-    async safeGet(accountId) {
-        if (!this.isReady())
+    /**
+     * Reads permission list from Redis.
+     *
+     * @param {string} key - Cache key.
+     */
+    async get(key) {
+        if (!this.client.isReady) {
             return null;
+        }
         try {
-            const raw = await this.client.get(this.key(accountId));
-            if (!raw)
+            const raw = await this.client.get(key);
+            if (!raw) {
                 return null;
+            }
             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);
+            console.warn(`[PermissionCache] Cache read failed: ${key}`, err);
             return null;
         }
     }
-    async safeSet(accountId, perms) {
-        if (!this.isReady())
+    /**
+     * Stores permission list in Redis.
+     *
+     * @param {string} key - Cache key.
+     * @param {string[]} permissions - Permission keys.
+     */
+    async set(key, permissions) {
+        if (!this.client.isReady) {
             return;
+        }
         try {
-            await this.client.set(this.key(accountId), JSON.stringify(perms), {
+            await this.client.set(key, JSON.stringify(permissions), {
                 EX: CACHE_TTL_SECONDS,
             });
         }
         catch (err) {
-            console.warn(`[PermissionCache] Cache set failed for ${accountId}`, err);
+            console.warn(`[PermissionCache] Cache write failed: ${key}`, err);
         }
     }
+    /**
+     * Deletes permission cache.
+     *
+     * @param {string} key - Cache key.
+     */
+    async delete(key) {
+        if (!this.client.isReady) {
+            return;
+        }
+        await this.client.del(key);
+    }
+    /* ---------------------------------------------------------------------------
+       Cache Key Builders
+    --------------------------------------------------------------------------- */
+    platformKey(accountId) {
+        return `${PLATFORM_PREFIX}:${accountId}`;
+    }
+    organizationKey(userId, organizationId) {
+        return `${ORG_PREFIX}:${userId}:${organizationId}`;
+    }
+    workspaceKey(userId, workspaceId) {
+        return `${WORKSPACE_PREFIX}:${userId}:${workspaceId}`;
+    }
 }
 exports.PermissionCacheService = PermissionCacheService;

package/dist/authorization/permission-checker.d.ts

@@ -0,0 +1,30 @@
+/**
+ * @file permission-checker.ts
+ * @description Centralized utility for validating resolved permission string arrays against required permissions.
+ */
+export declare class PermissionChecker {
+    /**
+     * Checks whether the resolved list has the specific permission.
+     *
+     * @param {readonly string[]} permissions - Active resolved permissions.
+     * @param {string} permission - The required permission key.
+     * @returns {boolean} True if the permission exists in the array.
+     */
+    static has(permissions: readonly string[], permission: string): boolean;
+    /**
+     * Checks whether the resolved list contains at least one of the required permissions.
+     *
+     * @param {readonly string[]} permissions - Active resolved permissions.
+     * @param {readonly string[]} required - Allowed keys.
+     * @returns {boolean} True if at least one matches.
+     */
+    static hasAny(permissions: readonly string[], required: readonly string[]): boolean;
+    /**
+     * Checks whether the resolved list contains all of the required permissions.
+     *
+     * @param {readonly string[]} permissions - Active resolved permissions.
+     * @param {readonly string[]} required - Required keys.
+     * @returns {boolean} True if all match.
+     */
+    static hasAll(permissions: readonly string[], required: readonly string[]): boolean;
+}

package/dist/authorization/permission-checker.js

@@ -0,0 +1,40 @@
+"use strict";
+/**
+ * @file permission-checker.ts
+ * @description Centralized utility for validating resolved permission string arrays against required permissions.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PermissionChecker = void 0;
+class PermissionChecker {
+    /**
+     * Checks whether the resolved list has the specific permission.
+     *
+     * @param {readonly string[]} permissions - Active resolved permissions.
+     * @param {string} permission - The required permission key.
+     * @returns {boolean} True if the permission exists in the array.
+     */
+    static has(permissions, permission) {
+        return permissions.includes(permission);
+    }
+    /**
+     * Checks whether the resolved list contains at least one of the required permissions.
+     *
+     * @param {readonly string[]} permissions - Active resolved permissions.
+     * @param {readonly string[]} required - Allowed keys.
+     * @returns {boolean} True if at least one matches.
+     */
+    static hasAny(permissions, required) {
+        return required.some((permission) => permissions.includes(permission));
+    }
+    /**
+     * Checks whether the resolved list contains all of the required permissions.
+     *
+     * @param {readonly string[]} permissions - Active resolved permissions.
+     * @param {readonly string[]} required - Required keys.
+     * @returns {boolean} True if all match.
+     */
+    static hasAll(permissions, required) {
+        return required.every((permission) => permissions.includes(permission));
+    }
+}
+exports.PermissionChecker = PermissionChecker;

package/dist/context/index.d.ts

@@ -1 +1 @@
-export * from "./access-context.js";
+export * from './request-context.storage';

package/dist/context/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("./access-context.js"), exports);
+__exportStar(require("./request-context.storage"), exports);

package/dist/context/request-context.storage.d.ts

@@ -0,0 +1,21 @@
+import { AsyncLocalStorage } from 'async_hooks';
+import { RequestMetadataContext, UserContext, MachineContext } from '../types';
+export type AuditRequestContext = RequestMetadataContext & {
+    actor?: UserContext | MachineContext;
+};
+export declare const requestContextStorage: AsyncLocalStorage<AuditRequestContext>;
+export declare class RequestContextProvider {
+    /**
+     * Retrieves the current context if it exists.
+     */
+    static get(): AuditRequestContext | undefined;
+    /**
+     * Retrieves the current context or throws an error.
+     * Use this in deeper repositories where context is strictly required.
+     */
+    static getOrThrow(): AuditRequestContext;
+    /**
+     * Attaches the authenticated actor to the current request context.
+     */
+    static setActor(actor: UserContext | MachineContext): void;
+}