@flipboxlabs/aws-audit-sdk 1.1.0

package/dist/events/bus.d.ts

@@ -0,0 +1,79 @@
+import type { Logger } from "@aws-lambda-powertools/logger";
+import { type PutEventsRequestEntry, type PutEventsResultEntry } from "@aws-sdk/client-eventbridge";
+import type { UpsertAudit } from "../schema/service.js";
+import { BatchHandler } from "./batch-handler.js";
+/**
+ * Event detail payload structure for audit events.
+ *
+ * Wraps the audit data in a consistent structure for EventBridge events.
+ */
+export interface AuditEventDetail {
+    /** The audit record being published */
+    audit: UpsertAudit;
+}
+/**
+ * Publishes audit events to AWS EventBridge.
+ *
+ * Provides a high-level interface for publishing audit-related events
+ * to EventBridge, with automatic event formatting and batching.
+ *
+ * Events are published to the configured audit event bus with the
+ * appropriate source and detail type for downstream consumers.
+ *
+ * @example
+ * ```typescript
+ * const eventBus = new AuditEventBus(logger);
+ *
+ * // Publish audit upsert events
+ * await eventBus.upserted([
+ *   { id: 'audit-1', operation: 'createUser', ... },
+ *   { id: 'audit-2', operation: 'updateUser', ... },
+ * ]);
+ * ```
+ */
+export declare class AuditEventBus {
+    protected readonly handler: BatchHandler;
+    /**
+     * Creates a new AuditEventBus instance.
+     *
+     * @param logger - Logger instance for the underlying BatchHandler
+     * @param handler - BatchHandler for EventBridge operations (defaults to new instance with EventBridgeClient)
+     */
+    constructor(logger: Logger, handler?: BatchHandler);
+    /**
+     * Serializes an audit record into an EventBridge detail string.
+     *
+     * Wraps the audit in an AuditEventDetail structure and converts to JSON.
+     *
+     * @param audit - The audit record to serialize
+     * @returns JSON string containing the event detail
+     *
+     * @internal
+     */
+    protected createDetail(audit: UpsertAudit): string;
+    /**
+     * Publishes audit "upserted" events to EventBridge.
+     *
+     * Creates EventBridge events for each audit item with:
+     * - EventBusName: Configured audit event bus
+     * - DetailType: "Upserted" event type
+     * - Source: Configured audit source
+     * - Detail: JSON-serialized audit data
+     *
+     * Additional events can be included via the extraEvents parameter.
+     *
+     * @param items - Array of audit records to publish as upserted events
+     * @param extraEvents - Optional additional EventBridge events to include in the batch
+     * @returns Array of result entries from EventBridge
+     *
+     * @example
+     * ```typescript
+     * // Publish audit events with additional custom events
+     * const results = await eventBus.upserted(audits, [
+     *   { DetailType: 'CustomEvent', Detail: '{}', Source: 'custom' },
+     * ]);
+     * ```
+     */
+    upserted(items: Array<UpsertAudit>, extraEvents?: PutEventsRequestEntry[]): Promise<PutEventsResultEntry[]>;
+}
+//# sourceMappingURL=bus.d.ts.map

package/dist/events/bus.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bus.d.ts","sourceRoot":"","sources":["../../src/events/bus.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,+BAA+B,CAAC;AAC5D,OAAO,EAEN,KAAK,qBAAqB,EAC1B,KAAK,oBAAoB,EACzB,MAAM,6BAA6B,CAAC;AAErC,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,sBAAsB,CAAC;AACxD,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAElD;;;;GAIG;AACH,MAAM,WAAW,gBAAgB;IAChC,uCAAuC;IACvC,KAAK,EAAE,WAAW,CAAC;CACnB;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,qBAAa,aAAa;IASxB,SAAS,CAAC,QAAQ,CAAC,OAAO,EAAE,YAAY;IARzC;;;;;OAKG;gBAEF,MAAM,EAAE,MAAM,EACK,OAAO,GAAE,YAM3B;IAGF;;;;;;;;;OASG;IACH,SAAS,CAAC,YAAY,CAAC,KAAK,EAAE,WAAW,GAAG,MAAM;IAQlD;;;;;;;;;;;;;;;;;;;;;;OAsBG;IACU,QAAQ,CACpB,KAAK,EAAE,KAAK,CAAC,WAAW,CAAC,EACzB,WAAW,CAAC,EAAE,qBAAqB,EAAE,GACnC,OAAO,CAAC,oBAAoB,EAAE,CAAC;CAUlC"}

package/dist/events/bus.js

@@ -0,0 +1,86 @@
+import { EventBridgeClient, } from "@aws-sdk/client-eventbridge";
+import { EventBridge } from "../constants.js";
+import { BatchHandler } from "./batch-handler.js";
+/**
+ * Publishes audit events to AWS EventBridge.
+ *
+ * Provides a high-level interface for publishing audit-related events
+ * to EventBridge, with automatic event formatting and batching.
+ *
+ * Events are published to the configured audit event bus with the
+ * appropriate source and detail type for downstream consumers.
+ *
+ * @example
+ * ```typescript
+ * const eventBus = new AuditEventBus(logger);
+ *
+ * // Publish audit upsert events
+ * await eventBus.upserted([
+ *   { id: 'audit-1', operation: 'createUser', ... },
+ *   { id: 'audit-2', operation: 'updateUser', ... },
+ * ]);
+ * ```
+ */
+export class AuditEventBus {
+    handler;
+    /**
+     * Creates a new AuditEventBus instance.
+     *
+     * @param logger - Logger instance for the underlying BatchHandler
+     * @param handler - BatchHandler for EventBridge operations (defaults to new instance with EventBridgeClient)
+     */
+    constructor(logger, handler = new BatchHandler(logger, new EventBridgeClient({
+        region: process.env.AWS_REGION,
+        logger,
+    }))) {
+        this.handler = handler;
+    }
+    /**
+     * Serializes an audit record into an EventBridge detail string.
+     *
+     * Wraps the audit in an AuditEventDetail structure and converts to JSON.
+     *
+     * @param audit - The audit record to serialize
+     * @returns JSON string containing the event detail
+     *
+     * @internal
+     */
+    createDetail(audit) {
+        const props = {
+            audit,
+        };
+        return JSON.stringify(props);
+    }
+    /**
+     * Publishes audit "upserted" events to EventBridge.
+     *
+     * Creates EventBridge events for each audit item with:
+     * - EventBusName: Configured audit event bus
+     * - DetailType: "Upserted" event type
+     * - Source: Configured audit source
+     * - Detail: JSON-serialized audit data
+     *
+     * Additional events can be included via the extraEvents parameter.
+     *
+     * @param items - Array of audit records to publish as upserted events
+     * @param extraEvents - Optional additional EventBridge events to include in the batch
+     * @returns Array of result entries from EventBridge
+     *
+     * @example
+     * ```typescript
+     * // Publish audit events with additional custom events
+     * const results = await eventBus.upserted(audits, [
+     *   { DetailType: 'CustomEvent', Detail: '{}', Source: 'custom' },
+     * ]);
+     * ```
+     */
+    async upserted(items, extraEvents) {
+        const events = items.map((audit) => ({
+            EventBusName: EventBridge.Bus.Name(),
+            Detail: this.createDetail(audit),
+            DetailType: EventBridge.DetailType.UPSERTED,
+            Source: EventBridge.Source,
+        }));
+        return await this.handler.putEvents([...events, ...(extraEvents || [])]);
+    }
+}

package/dist/events/index.d.ts

@@ -0,0 +1,3 @@
+export * from "./batch-handler.js";
+export * from "./bus.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/events/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/events/index.ts"],"names":[],"mappings":"AAAA,cAAc,oBAAoB,CAAC;AACnC,cAAc,UAAU,CAAC"}

package/dist/events/index.js

@@ -0,0 +1,2 @@
+export * from "./batch-handler.js";
+export * from "./bus.js";

package/dist/index.d.ts

@@ -0,0 +1,9 @@
+export * from "./audits.js";
+export * from "./config.js";
+export { type AnyEventBridgeDetailType, AUDIT_LOG_IDENTIFIER, DynamoDB, EventBridge, SDK_VERSION, } from "./constants.js";
+export * from "./events/index.js";
+export * from "./schema/index.js";
+export * from "./service.js";
+export * from "./types.js";
+export { buildAudit, buildAuditFromSQSRecord, getReceiveCount, getRecordId, isRetry, normalizeEventBridgetInput, } from "./utils.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,aAAa,CAAC;AAC5B,cAAc,aAAa,CAAC;AAC5B,OAAO,EACN,KAAK,wBAAwB,EAC7B,oBAAoB,EACpB,QAAQ,EACR,WAAW,EACX,WAAW,GACX,MAAM,gBAAgB,CAAC;AACxB,cAAc,mBAAmB,CAAC;AAClC,cAAc,mBAAmB,CAAC;AAClC,cAAc,cAAc,CAAC;AAC7B,cAAc,YAAY,CAAC;AAC3B,OAAO,EACN,UAAU,EACV,uBAAuB,EACvB,eAAe,EACf,WAAW,EACX,OAAO,EACP,0BAA0B,GAC1B,MAAM,YAAY,CAAC"}

package/dist/index.js

@@ -0,0 +1,8 @@
+export * from "./audits.js";
+export * from "./config.js";
+export { AUDIT_LOG_IDENTIFIER, DynamoDB, EventBridge, SDK_VERSION, } from "./constants.js";
+export * from "./events/index.js";
+export * from "./schema/index.js";
+export * from "./service.js";
+export * from "./types.js";
+export { buildAudit, buildAuditFromSQSRecord, getReceiveCount, getRecordId, isRetry, normalizeEventBridgetInput, } from "./utils.js";

package/dist/middleware/middy.d.ts

@@ -0,0 +1,66 @@
+import type { MiddlewareLikeObj } from "@aws-lambda-powertools/commons/types";
+import type { Audits } from "../audits.js";
+import type { AuditConfig } from "../config.js";
+/**
+ * Type alias for any Audits instance regardless of config type.
+ */
+type AnyAudits = Audits<AuditConfig>;
+/**
+ * Creates a Middy.js middleware for automatic audit log management.
+ *
+ * This middleware integrates with the AWS Lambda Powertools pattern and is
+ * compatible with `@middy/core@3.x` and above. It automates the lifecycle
+ * of audit log collection and emission.
+ *
+ * **Behavior:**
+ * - **Before hook**: Registers a cleanup function on `request.internal` that
+ *   can be invoked by other middlewares for early termination scenarios
+ * - **After hook**: Logs the Lambda event and publishes all buffered audits
+ * - **OnError hook**: Same as after hook - ensures audits are published even
+ *   when the handler throws an error
+ *
+ * The cleanup function is stored at `audits` in `request.internal`,
+ * following the Powertools convention for middleware coordination.
+ *
+ * @param handler - The Audits instance to use for audit management
+ * @returns A Middy-compatible middleware object with before, after, and onError hooks
+ *
+ * @example
+ * ```typescript
+ * import middy from '@middy/core';
+ * import { Audits, defineAuditConfig } from '@flipboxlabs/aws-audit-sdk';
+ * import { logAudits } from '@flipboxlabs/aws-audit-sdk/middleware';
+ *
+ * const config = defineAuditConfig({
+ *   apps: ['Orders'] as const,
+ *   resourceTypes: ['Order'] as const,
+ * });
+ *
+ * const audits = new Audits({ config });
+ *
+ * const handler = middy(async (event, context) => {
+ *   audits.addAudit({
+ *     operation: 'processOrder',
+ *     target: { app: 'Orders', type: 'Order', id: event.orderId },
+ *     status: 'success',
+ *   });
+ *
+ *   return { statusCode: 200 };
+ * }).use(logAudits(audits));
+ *
+ * export { handler };
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // With multiple middlewares - cleanup function ensures audits
+ * // are published even if another middleware returns early
+ * const handler = middy(lambdaHandler)
+ *   .use(logAudits(audits))
+ *   .use(httpErrorHandler())
+ *   .use(cors());
+ * ```
+ */
+declare const logAudits: (handler: AnyAudits) => MiddlewareLikeObj;
+export { logAudits };
+//# sourceMappingURL=middy.d.ts.map

package/dist/middleware/middy.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"middy.d.ts","sourceRoot":"","sources":["../../src/middleware/middy.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACX,iBAAiB,EAEjB,MAAM,sCAAsC,CAAC;AAC9C,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,cAAc,CAAC;AAC3C,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAEhD;;GAEG;AACH,KAAK,SAAS,GAAG,MAAM,CAAC,WAAW,CAAC,CAAC;AAErC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuDG;AACH,QAAA,MAAM,SAAS,GAAI,SAAS,SAAS,KAAG,iBAoDvC,CAAC;AAEF,OAAO,EAAE,SAAS,EAAE,CAAC"}

package/dist/middleware/middy.js

@@ -0,0 +1,105 @@
+/**
+ * Creates a Middy.js middleware for automatic audit log management.
+ *
+ * This middleware integrates with the AWS Lambda Powertools pattern and is
+ * compatible with `@middy/core@3.x` and above. It automates the lifecycle
+ * of audit log collection and emission.
+ *
+ * **Behavior:**
+ * - **Before hook**: Registers a cleanup function on `request.internal` that
+ *   can be invoked by other middlewares for early termination scenarios
+ * - **After hook**: Logs the Lambda event and publishes all buffered audits
+ * - **OnError hook**: Same as after hook - ensures audits are published even
+ *   when the handler throws an error
+ *
+ * The cleanup function is stored at `audits` in `request.internal`,
+ * following the Powertools convention for middleware coordination.
+ *
+ * @param handler - The Audits instance to use for audit management
+ * @returns A Middy-compatible middleware object with before, after, and onError hooks
+ *
+ * @example
+ * ```typescript
+ * import middy from '@middy/core';
+ * import { Audits, defineAuditConfig } from '@flipboxlabs/aws-audit-sdk';
+ * import { logAudits } from '@flipboxlabs/aws-audit-sdk/middleware';
+ *
+ * const config = defineAuditConfig({
+ *   apps: ['Orders'] as const,
+ *   resourceTypes: ['Order'] as const,
+ * });
+ *
+ * const audits = new Audits({ config });
+ *
+ * const handler = middy(async (event, context) => {
+ *   audits.addAudit({
+ *     operation: 'processOrder',
+ *     target: { app: 'Orders', type: 'Order', id: event.orderId },
+ *     status: 'success',
+ *   });
+ *
+ *   return { statusCode: 200 };
+ * }).use(logAudits(audits));
+ *
+ * export { handler };
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // With multiple middlewares - cleanup function ensures audits
+ * // are published even if another middleware returns early
+ * const handler = middy(lambdaHandler)
+ *   .use(logAudits(audits))
+ *   .use(httpErrorHandler())
+ *   .use(cors());
+ * ```
+ */
+const logAudits = (handler) => {
+    const instance = handler;
+    /**
+     * Registers the cleanup function on the request's internal state.
+     *
+     * This allows other middlewares to invoke the audit flush if they
+     * need to return early, following the Powertools middleware pattern.
+     *
+     * @param request - The Middy request object
+     * @internal
+     */
+    const setCleanupFunction = (request) => {
+        request.internal = {
+            ...request.internal,
+            ["audits"]: afterOrError,
+        };
+    };
+    /**
+     * Before hook - runs before the Lambda handler.
+     *
+     * Registers the cleanup function for middleware coordination.
+     *
+     * @param request - The Middy request object
+     * @internal
+     */
+    const before = async (request) => {
+        setCleanupFunction(request);
+    };
+    /**
+     * After/Error hook - runs after the Lambda handler completes or throws.
+     *
+     * Logs the original event for debugging and publishes all buffered
+     * audit entries. This ensures audits are always emitted regardless
+     * of whether the handler succeeded or failed.
+     *
+     * @param request - The Middy request object containing the event
+     * @internal
+     */
+    const afterOrError = async (request) => {
+        instance.logger.info(request.event);
+        instance.publishStoredAudits();
+    };
+    return {
+        before,
+        after: afterOrError,
+        onError: afterOrError,
+    };
+};
+export { logAudits };