@cloud-copilot/iam-lens 0.1.108 → 0.1.109

package/dist/cjs/whoCan/WhoCanProcessor.d.ts

@@ -0,0 +1,371 @@
+import { type TopLevelConfig } from '@cloud-copilot/iam-collect';
+import { type ClientFactoryPlugin } from '../collect/collect.js';
+import { type S3AbacOverride } from '../utils/s3Abac.js';
+import { type LightRequestAnalysis } from './requestAnalysis.js';
+import { type WhoCanPrincipalScope, type WhoCanResponse } from './whoCan.js';
+/**
+ * Configuration for creating a WhoCanProcessor. These settings are fixed
+ * for the lifetime of the processor and baked into worker threads at creation time.
+ */
+export interface WhoCanProcessorConfig {
+    /** The collect configurations for loading IAM data. */
+    collectConfigs: TopLevelConfig[];
+    /** The AWS partition to use (e.g. 'aws', 'aws-cn'). */
+    partition: string;
+    tuning?: {
+        /**
+         * The number of worker threads to use beyond the main thread. Defaults to number of CPUs - 1.
+         */
+        workerThreads?: number;
+        /**
+         * The concurrency level for processing simulations on the main thread. Defaults to 50.
+         */
+        mainThreadConcurrency?: number;
+        /**
+         * The concurrency level for processing simulations on worker threads.
+         * This is the value for EACH worker.
+         * Defaults to 50.
+         */
+        perWorkerConcurrency?: number;
+        /**
+         * The concurrency level for the shared preparation queue (account/principal fetches
+         * across all active requests). Defaults to min(50, max(1, number of CPUs * 2)).
+         */
+        preparationConcurrency?: number;
+        /**
+         * The maximum number of requests that may be actively expanded into scenarios
+         * at once. Later requests remain as lightweight entries in pendingRequests.
+         * Defaults to 30.
+         */
+        maxRequestsInProgress?: number;
+    };
+    /** Optional plugin to wrap the collect client with a custom implementation. */
+    clientFactoryPlugin?: ClientFactoryPlugin;
+    /** An override for S3 ABAC being enabled when checking access to S3 Bucket resources. */
+    s3AbacOverride?: S3AbacOverride;
+    /** Whether workers should collect grant details for allowed simulations. */
+    collectGrantDetails?: boolean;
+    /**
+     * Async callback invoked when a request settles (succeeds or fails). The processor
+     * awaits this callback before removing the request from active state and admitting
+     * the next pending request. This allows consumers to perform async work with backpressure.
+     *
+     * @param event - The settlement event containing the request ID, original request,
+     *   status, and either the result or the error.
+     */
+    onRequestSettled: (event: WhoCanSettledEvent) => Promise<void>;
+    /**
+     * Whether the processor should ignore an existing principal index. Use this with testing.
+     */
+    ignorePrincipalIndex?: boolean;
+}
+/**
+ * Request parameters that vary per whoCan call on a processor.
+ */
+export interface WhoCanProcessorRequest {
+    /** The ARN of the resource to check access for. */
+    resource?: string;
+    /** The account ID the resource belongs to. */
+    resourceAccount?: string;
+    /** The actions to check access for. */
+    actions: string[];
+    /** Whether to sort the results for consistent output. */
+    sort?: boolean;
+    /**
+     * Optional callback to filter which denied simulations should include detailed
+     * denial analysis. If provided, deny details are collected for this request.
+     * If the callback returns true for a given denial, the full deny details are
+     * included in the response. If omitted, no deny details are collected for this request.
+     *
+     * @param details - A lightweight summary of the denied simulation.
+     * @returns true to include full deny details for this denial.
+     */
+    denyDetailsCallback?: (details: LightRequestAnalysis) => boolean;
+    /** Optional scope to limit the set of principals tested. */
+    principalScope?: WhoCanPrincipalScope;
+    /** Optional context keys to consider strict when running simulations. */
+    strictContextKeys?: string[];
+}
+/**
+ * Event delivered to the onRequestSettled callback when a request completes
+ * (either successfully or with an error).
+ */
+export type WhoCanSettledEvent = WhoCanSettledSuccess | WhoCanSettledError;
+/**
+ * Settlement event for a successfully completed request.
+ */
+export interface WhoCanSettledSuccess {
+    /** Discriminator for the settlement outcome. */
+    status: 'fulfilled';
+    /** The unique ID assigned when the request was enqueued. */
+    requestId: string;
+    /** The original request that was enqueued. */
+    request: WhoCanProcessorRequest;
+    /** The whoCan result for this request. */
+    result: WhoCanResponse;
+}
+/**
+ * Settlement event for a request that failed during preparation or simulation.
+ */
+export interface WhoCanSettledError {
+    /** Discriminator for the settlement outcome. */
+    status: 'rejected';
+    /** The unique ID assigned when the request was enqueued. */
+    requestId: string;
+    /** The original request that was enqueued. */
+    request: WhoCanProcessorRequest;
+    /** The error that caused the request to fail. */
+    error: Error;
+}
+/**
+ * A queue-first bulk processor that accepts many whoCan requests, expands
+ * scenarios on the main thread, and feeds a shared simulation scheduler used
+ * by worker threads and an optional main-thread runner.
+ *
+ * Results are delivered through the {@link WhoCanProcessorConfig.onRequestSettled}
+ * callback as each request completes — they are not stored inside the processor.
+ *
+ * Use {@link enqueueWhoCan} to submit requests, then {@link waitForIdle} to
+ * wait for all work to complete. Call {@link shutdown} when done to terminate
+ * worker threads.
+ */
+export declare class WhoCanProcessor {
+    private workers;
+    private collectClient;
+    private config;
+    private isShutdown;
+    private workersDead;
+    private pendingRequests;
+    private activeRequestOrder;
+    private requestStates;
+    private admissionPumpRunning;
+    private draining;
+    private preparationQueue;
+    private idleWaiters;
+    private settledCallbackErrors;
+    private mainThreadWorker;
+    private fatalError?;
+    private shutdownPromise?;
+    private constructor();
+    /**
+     * Creates a new WhoCanProcessor with worker threads, a shared cache, and
+     * lifetime-scoped message routing. The processor is ready to accept requests
+     * immediately after creation.
+     *
+     * @param config - The configuration for the processor, including collect configs,
+     *   partition, simulation options, tuning, and the onRequestSettled callback.
+     * @returns a new WhoCanProcessor instance
+     */
+    static create(config: WhoCanProcessorConfig): Promise<WhoCanProcessor>;
+    /**
+     * Enqueues a whoCan request for processing. Returns a unique request ID
+     * that will appear in the corresponding {@link WhoCanSettledEvent}.
+     *
+     * This method never activates a request directly — it appends to
+     * pendingRequests and signals the admission pump.
+     *
+     * @param request - The whoCan request parameters.
+     * @returns the unique request ID assigned to this request.
+     * @throws if the processor is shut down or draining via waitForIdle.
+     */
+    enqueueWhoCan(request: WhoCanProcessorRequest): string;
+    /**
+     * Returns a promise that resolves when all pending and active work has
+     * completed and all onRequestSettled callbacks have finished.
+     *
+     * While draining, new calls to {@link enqueueWhoCan} will throw. Once
+     * the drain completes, the processor re-opens for new enqueues.
+     *
+     * @returns a promise that resolves when idle, or rejects if a worker crashes
+     *   or an onRequestSettled callback throws/rejects.
+     */
+    waitForIdle(): Promise<void>;
+    /**
+     * Shuts down the processor by rejecting all pending requests, waiting for
+     * active requests to settle, and terminating all worker threads.
+     *
+     * This method is idempotent — calling it multiple times is safe.
+     */
+    shutdown(): Promise<void>;
+    /**
+     * Internal shutdown implementation. Rejects pending requests, waits for
+     * active requests to drain, then terminates workers.
+     */
+    private executeShutdown;
+    /**
+     * Installs lifetime-scoped message, error, and exit listeners on all workers.
+     * Message listeners route simulation results and deny-detail checks to the
+     * correct request state using requestId. Error/exit listeners detect crashes
+     * and mark the processor as fatally failed.
+     */
+    private installLifetimeWorkerListeners;
+    /**
+     * Routes a message from a worker thread to the appropriate handler based
+     * on message type and requestId.
+     *
+     * @param msg - The message received from the worker.
+     * @param worker - The worker that sent the message.
+     */
+    private handleWorkerMessage;
+    /**
+     * Creates the main-thread simulation runner if mainThreadConcurrency > 0.
+     * The runner pulls from the FIFO scheduler and routes results by requestId.
+     */
+    private createMainThreadRunner;
+    /**
+     * Dequeues the next simulation scenario using FIFO request priority.
+     * Prefers the oldest active request that has ready scenarios. If the oldest
+     * is temporarily empty (still preparing), falls back to the next request
+     * with ready scenarios so cores do not idle.
+     *
+     * @returns the next work item, or undefined if no scenarios are ready.
+     */
+    private dequeueNextScenario;
+    /**
+     * Notifies all simulation consumers (workers and main thread) that new
+     * work may be available in the scheduler.
+     */
+    private notifySimulationConsumers;
+    /**
+     * Wakes the admission pump to process pending requests. If the pump is
+     * already running, this is a no-op — the running pump will pick up new
+     * pending requests on its next iteration.
+     */
+    private wakeAdmissionPump;
+    /**
+     * The admission pump loop. Drains pendingRequests into active processing
+     * up to maxRequestsInProgress. Only one instance of this loop runs at a time,
+     * guarded by admissionPumpRunning.
+     */
+    private runAdmissionPump;
+    /**
+     * Creates a fresh RequestState for an admitted request.
+     *
+     * @param submitted - The submitted request to create state for.
+     * @returns the new RequestState.
+     */
+    private createRequestState;
+    /**
+     * Enqueues the root preparation job for a request. This job performs resource
+     * account resolution, resource policy lookup, action expansion, principal scope
+     * handling, and then enqueues follow-up preparation jobs to enumerate principals.
+     *
+     * @param state - The request state to prepare.
+     */
+    private enqueueRootPreparation;
+    /**
+     * Executes the root preparation for a request: resolves the resource account,
+     * fetches the resource policy, expands actions, determines which accounts and
+     * principals to check, and enqueues follow-up preparation jobs.
+     *
+     * @param state - The request state to prepare.
+     */
+    private executeRootPreparation;
+    /**
+     * Handles a simulation result from a worker or the main thread runner.
+     * Routes the result to the correct request state and checks for completion.
+     *
+     * @param requestId - The ID of the request this result belongs to.
+     * @param result - The simulation job result.
+     */
+    private handleSimulationResult;
+    /**
+     * Handles a checkDenyDetails request from a worker thread. Looks up the
+     * request's denyDetailsCallback and responds.
+     *
+     * @param requestId - The ID of the request.
+     * @param checkId - The unique check ID for this deny-details round trip.
+     * @param lightAnalysis - The light analysis to pass to the callback.
+     * @param worker - The worker to respond to.
+     */
+    private handleCheckDenyDetails;
+    /**
+     * Handles a deny details result from a worker thread. Decrements the
+     * pending deny-details counter and checks for request completion.
+     *
+     * @param requestId - The ID of the request.
+     * @param denyDetail - The deny detail to store.
+     */
+    private handleDenyDetailsResult;
+    /**
+     * Checks whether a request has completed all preparation and simulation work.
+     * If so, settles the request as successful.
+     *
+     * @param state - The request state to check.
+     */
+    private checkRequestCompletion;
+    /**
+     * Settles a request as successful: builds the WhoCanResponse, awaits
+     * onRequestSettled, removes the request from active state, and wakes
+     * the admission pump.
+     *
+     * @param state - The request state to settle.
+     */
+    private settleRequestAsSuccess;
+    /**
+     * Settles a request as failed: invokes onRequestSettled with the error
+     * immediately, but keeps the request in active state until all in-flight
+     * work drains (created === completed). Late results for settled requests
+     * are discarded but still counted so the drain completes.
+     *
+     * @param state - The request state to settle.
+     * @param error - The error that caused the failure.
+     */
+    private settleRequestAsError;
+    /**
+     * Invokes the onRequestSettled callback and accumulates any errors for
+     * later surfacing via waitForIdle.
+     *
+     * @param event - The settlement event to deliver.
+     */
+    private invokeSettledCallback;
+    /**
+     * Awaits the onRequestSettled callback, then removes the request from
+     * active state and wakes the admission pump. Used for successful settlements
+     * where all work is already complete.
+     *
+     * @param state - The request state being settled.
+     * @param event - The settlement event to deliver.
+     */
+    private invokeSettledCallbackAndCleanup;
+    /**
+     * Checks whether a settled request has fully drained: the onRequestSettled
+     * callback has been awaited, all preparation jobs have finished, all
+     * simulation results have been received, and all deny-detail round trips
+     * have completed. Only then is the request removed from active state.
+     *
+     * @param state - The request state to check.
+     */
+    private checkRequestDrain;
+    /**
+     * Removes a request from active state, wakes the admission pump to fill
+     * the freed slot, and checks if the processor is now idle.
+     *
+     * @param state - The request state to remove.
+     */
+    private removeFromActiveState;
+    /**
+     * Returns true if the processor has no pending, active, or in-flight work.
+     *
+     * @returns true if fully idle.
+     */
+    private isIdle;
+    /**
+     * Checks whether the processor has become idle and resolves or rejects the
+     * waitForIdle promise if so.
+     */
+    private checkIdle;
+    /**
+     * If any onRequestSettled callbacks threw, throws the first error.
+     * Called after waitForIdle resolves to surface callback errors.
+     */
+    private rejectIfSettledCallbackErrors;
+    /**
+     * Handles an unexpected worker failure by marking the processor as dead,
+     * terminating remaining workers, and rejecting all active and pending requests.
+     *
+     * @param error - The error that caused the worker failure.
+     */
+    private handleWorkerFailure;
+}
+//# sourceMappingURL=WhoCanProcessor.d.ts.map

package/dist/cjs/whoCan/WhoCanProcessor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"WhoCanProcessor.d.ts","sourceRoot":"","sources":["../../../src/whoCan/WhoCanProcessor.ts"],"names":[],"mappings":"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"}