@flipboxlabs/aws-audit-sdk 1.1.0

package/dist/repository.js

@@ -0,0 +1,486 @@
+import { BatchWriteItemCommand, DynamoDBClient, GetItemCommand, QueryCommand, } from "@aws-sdk/client-dynamodb";
+import { marshall, unmarshall } from "@aws-sdk/util-dynamodb";
+import { DynamoDB } from "./constants.js";
+import { decodeNextPageToken, encodeNextPageToken, } from "./repository.utils.js";
+import { AuditListItemPayloadSchema, AuditPayloadSchema, AuditSchema, } from "./schema/audit.js";
+import { PaginationCollectionSchema } from "./schema/model.js";
+import { AuditStorageSchema } from "./schema/storage.js";
+import { getTraceParts } from "./utils.js";
+/**
+ * Default TTL for audit records in seconds (90 days).
+ * Records will be automatically deleted by DynamoDB after this period.
+ */
+const DEFAULT_TTL = 60 * 60 * 24 * 90; // 90 days
+/**
+ * Repository for managing audit records in DynamoDB.
+ *
+ * Provides CRUD operations for audit records with support for:
+ * - Single item retrieval by identifiers
+ * - Batch upsert operations with automatic batching
+ * - Paginated listing by resource
+ * - Paginated listing by trace ID for distributed tracing
+ *
+ * The repository uses a single-table design with composite keys and
+ * multiple GSI/LSI indexes for efficient query patterns.
+ *
+ * @typeParam C - The audit config type for type inference
+ *
+ * @example
+ * ```typescript
+ * const config = defineAuditConfig({
+ *   apps: ['Orders', 'Inventory'] as const,
+ *   resourceTypes: ['Order', 'Product'] as const,
+ * });
+ * const repository = new AuditRepository(logger, config);
+ *
+ * // Get a single audit record - typed!
+ * const audit = await repository.getItem({
+ *   id: 'audit-123',
+ *   app: 'Orders',           // TypeScript knows valid values
+ *   resourceType: 'Order',   // Autocomplete works
+ * });
+ *
+ * // Upsert multiple audit records
+ * await repository.upsertBatch([
+ *   { operation: 'createUser', status: 'success', ... },
+ *   { operation: 'updateUser', status: 'success', ... },
+ * ]);
+ *
+ * // List audits for a specific resource
+ * const { items, pagination } = await repository.listItems({
+ *   app: 'Orders',
+ *   resource: { type: 'Order', id: 'user-123' },
+ * });
+ * ```
+ */
+export class AuditRepository {
+    logger;
+    config;
+    client;
+    /**
+     * Creates a new AuditRepository instance.
+     *
+     * @param logger - Logger instance for error reporting and debugging
+     * @param config - Audit configuration for type inference
+     * @param client - DynamoDB client (defaults to new instance with AWS_REGION from environment)
+     */
+    constructor(logger, config, client = new DynamoDBClient({
+        region: process.env.AWS_REGION ?? "us-east-1",
+        logger,
+    })) {
+        this.logger = logger;
+        this.config = config;
+        this.client = client;
+    }
+    /**
+     * Retrieves a single audit record by its identifiers.
+     *
+     * Performs a DynamoDB GetItem operation using the constructed primary key.
+     * Returns undefined if the item is not found or if an error occurs.
+     *
+     * @param identifiers - Object containing id, app, and resourceType to locate the record
+     * @returns The audit record if found, undefined otherwise
+     *
+     * @example
+     * ```typescript
+     * const audit = await repository.getItem({
+     *   id: 'audit-123',
+     *   app: 'Orders',
+     *   resourceType: 'Order',
+     * });
+     *
+     * if (audit) {
+     *   console.log('Found audit:', audit.operation);
+     * }
+     * ```
+     */
+    async getItem(identifiers) {
+        try {
+            const { Item: item } = await this.client.send(new GetItemCommand({
+                TableName: DynamoDB.Table.Name(),
+                Key: marshall(this.constructPrimaryKey(identifiers), {
+                    removeUndefinedValues: true,
+                    convertEmptyValues: true,
+                    convertClassInstanceToMap: true,
+                }),
+            }));
+            return item
+                ? this.transformItem(unmarshall(item))
+                : undefined;
+        }
+        catch (error) {
+            this.logger.error("Unable to find audit item in the repository", {
+                identifiers,
+                error,
+            });
+            return undefined;
+        }
+    }
+    /**
+     * Upserts multiple audit records in batch.
+     *
+     * Performs a DynamoDB BatchWriteItem operation, automatically chunking
+     * items into batches of 25 (DynamoDB's maximum batch size).
+     * Each item is enriched with:
+     * - Primary keys (PK, SK)
+     * - Secondary index keys (GSI1_SS, GSI1_SN, LSI1_N)
+     * - TTL attribute (90 days from creation)
+     * - Timestamps (createdAt, updatedAt)
+     *
+     * @param items - Array of audit records to upsert
+     * @returns True when the operation completes (does not check for unprocessed items)
+     *
+     * @example
+     * ```typescript
+     * await repository.upsertBatch([
+     *   {
+     *     operation: 'createUser',
+     *     status: 'success',
+     *     tier: 2,
+     *     target: { app: App.App1, type: ResourceType.USER, id: 'user-123' },
+     *   },
+     *   {
+     *     operation: 'updateUser',
+     *     status: 'success',
+     *     tier: 2,
+     *     target: { app: App.App1, type: ResourceType.USER, id: 'user-456' },
+     *   },
+     * ]);
+     * ```
+     */
+    async upsertBatch(items) {
+        const BATCH_SIZE = 25;
+        const updatedAt = new Date();
+        const Items = await Promise.all(items.map((item) => {
+            const payload = AuditStorageSchema.parse({
+                createdAt: updatedAt,
+                ...item,
+                updatedAt: updatedAt,
+            });
+            return {
+                PutRequest: {
+                    Item: marshall({
+                        ...this.constructPrimaryKey({
+                            tenantId: payload.tenantId,
+                            id: payload.id,
+                            resourceType: payload.target.type,
+                            app: payload.target.app,
+                        }),
+                        ...this.constructSecondaryKeys(payload),
+                        ...this.constructTTLAttribute(DEFAULT_TTL),
+                        ...payload,
+                    }, {
+                        removeUndefinedValues: true,
+                        convertEmptyValues: true,
+                        convertClassInstanceToMap: true,
+                    }),
+                },
+            };
+        }));
+        const ItemBatches = [];
+        // Chunk into batches of 25 (DynamoDB BatchWriteItem limit)
+        for (let i = 0, j = Items.length; i < j; i += BATCH_SIZE) {
+            ItemBatches.push(Items.slice(i, i + BATCH_SIZE));
+        }
+        await Promise.all(ItemBatches.map((ItemBatch) => this.client.send(new BatchWriteItemCommand({
+            RequestItems: {
+                [DynamoDB.Table.Name()]: ItemBatch,
+            },
+        }))));
+        return true;
+    }
+    /**
+     * Lists audit records for a specific resource with pagination.
+     *
+     * Queries the GSI1_SS index to efficiently retrieve all audits
+     * associated with a specific app/resource combination.
+     * Results are returned in reverse chronological order.
+     *
+     * @param params - Query parameters including app and resource identifiers
+     * @param pagination - Optional pagination settings (pageSize, nextToken)
+     * @returns Paginated collection of audit records
+     *
+     * @example
+     * ```typescript
+     * // Get first page
+     * const page1 = await repository.listItems({
+     *   app: 'Orders',
+     *   resource: { type: 'Order', id: 'user-123' },
+     * });
+     *
+     * // Get next page using the pagination token
+     * const page2 = await repository.listItems(
+     *   { app: 'Orders', resource: { type: 'Order', id: 'user-123' } },
+     *   { nextToken: page1.pagination?.nextToken },
+     * );
+     * ```
+     */
+    async listItems(params, pagination) {
+        const startKey = decodeNextPageToken(pagination?.nextToken);
+        const pageSize = Number(pagination?.pageSize || 100);
+        const pkBase = `${params.app}.${params.resource.type}#${params.resource.id}`;
+        const pk = params.tenantId ? `${params.tenantId}#${pkBase}` : pkBase;
+        const { Items: items, LastEvaluatedKey: lastEvaluatedKey } = await this.client.send(new QueryCommand({
+            ScanIndexForward: false,
+            IndexName: DynamoDB.Indexes.GSI1_SS,
+            ExpressionAttributeValues: marshall({
+                ":PK": pk,
+            }),
+            ExpressionAttributeNames: {
+                "#PK": DynamoDB.Keys.GSI1_SS_PARTITION_KEY,
+            },
+            KeyConditionExpression: "#PK=:PK",
+            TableName: DynamoDB.Table.Name(),
+            Limit: pageSize,
+            ExclusiveStartKey: startKey
+                ? marshall(startKey, {
+                    removeUndefinedValues: true,
+                    convertEmptyValues: true,
+                    convertClassInstanceToMap: true,
+                })
+                : undefined,
+        }));
+        return PaginationCollectionSchema(AuditPayloadSchema).parse({
+            items: items?.map((i) => this.transformListItem(unmarshall(i))),
+            pagination: {
+                nextToken: lastEvaluatedKey
+                    ? encodeNextPageToken(unmarshall(lastEvaluatedKey))
+                    : undefined,
+            },
+        });
+    }
+    /**
+     * Lists audit records by trace ID for distributed tracing.
+     *
+     * Queries the GSI1_SN index to retrieve all audits sharing
+     * the same trace ID, ordered by trace stage/depth.
+     * Supports optional filtering by app, resource type, and resource ID.
+     *
+     * This is useful for viewing the complete audit trail of a
+     * distributed operation across multiple services or resources.
+     *
+     * @param params - Query parameters including trace ID and optional filters
+     * @param pagination - Optional pagination settings (pageSize, nextToken)
+     * @returns Paginated collection of audit records in trace order
+     *
+     * @example
+     * ```typescript
+     * // Get all audits for a trace
+     * const trace = await repository.listTraceItems({
+     *   trace: 'trace-abc-123',
+     * });
+     *
+     * // Filter by app and resource type
+     * const filtered = await repository.listTraceItems({
+     *   trace: 'trace-abc-123',
+     *   app: 'Orders',
+     *   resource: { type: 'Order' },
+     * });
+     * ```
+     */
+    async listTraceItems(params, pagination) {
+        const startKey = decodeNextPageToken(pagination?.nextToken);
+        const pageSize = Number(pagination?.pageSize || 100);
+        const pkBase = params.trace;
+        const pk = params.tenantId ? `${params.tenantId}#${pkBase}` : pkBase;
+        const filters = [];
+        const ExpressionAttributeValues = {
+            ":PK": pk,
+        };
+        if (params?.resource?.id) {
+            Object.assign(ExpressionAttributeValues, {
+                ":resourceId": params?.resource?.id,
+            });
+            filters.push("resourceId=:resourceId");
+        }
+        if (params?.resource?.type) {
+            Object.assign(ExpressionAttributeValues, {
+                ":resourceType": params?.resource?.type,
+            });
+            filters.push("resourceType=:resourceType");
+        }
+        if (params?.app) {
+            Object.assign(ExpressionAttributeValues, {
+                ":app": params.app,
+            });
+            filters.push("app=:app");
+        }
+        // Audits with other resources will have a compound id - filter these out
+        Object.assign(ExpressionAttributeValues, { ":isParent": "#" });
+        filters.push("not contains(SK, :isParent)");
+        const { Items: items, LastEvaluatedKey: lastEvaluatedKey } = await this.client.send(new QueryCommand({
+            ScanIndexForward: true,
+            IndexName: DynamoDB.Indexes.GSI1_SN,
+            ExpressionAttributeValues: marshall(ExpressionAttributeValues),
+            ExpressionAttributeNames: {
+                "#PK": DynamoDB.Keys.GSI1_SN_PARTITION_KEY,
+            },
+            KeyConditionExpression: "#PK=:PK",
+            TableName: DynamoDB.Table.Name(),
+            Limit: pageSize,
+            ExclusiveStartKey: startKey ? marshall(startKey) : undefined,
+            FilterExpression: filters.join(" AND "),
+        }));
+        return PaginationCollectionSchema(AuditPayloadSchema).parse({
+            items: items?.map((i) => this.transformTraceListItem(unmarshall(i))),
+            pagination: {
+                nextToken: lastEvaluatedKey
+                    ? encodeNextPageToken(unmarshall(lastEvaluatedKey))
+                    : undefined,
+            },
+        });
+    }
+    /**
+     * Constructs the DynamoDB primary key from identifiers.
+     *
+     * When tenantId is provided, it prefixes the partition key for multi-tenant isolation.
+     *
+     * @param identifiers - Object containing tenantId (optional), app, id, and resourceType
+     * @returns Primary key object with PK and SK attributes
+     * @internal
+     */
+    constructPrimaryKey({ tenantId, app, id, resourceType, }) {
+        const pkBase = `${app}.${resourceType}`;
+        return {
+            [DynamoDB.Keys.PARTITION_KEY]: (tenantId
+                ? `${tenantId}#${pkBase}`
+                : pkBase),
+            [DynamoDB.Keys.SORT_KEY]: `${id}`,
+        };
+    }
+    /**
+     * Constructs all secondary index keys for an audit item.
+     *
+     * Includes:
+     * - LSI1_N: Tier-based sort key for priority ordering
+     * - GSI1_SS: Resource-based index keys
+     * - GSI1_SN: Trace-based index keys (if trace exists)
+     *
+     * @param item - The audit storage item
+     * @returns Object containing all secondary key attributes
+     * @internal
+     */
+    constructSecondaryKeys(item) {
+        return {
+            [DynamoDB.Keys.LSI1_N_SORT_KEY]: Number(`${item.tier}${Date.now()}`),
+            ...this.constructGSI1_SS({
+                tenantId: item.tenantId,
+                id: item.id,
+                resourceType: item.target.type,
+                resourceId: item.target.id,
+                app: item.target.app,
+            }),
+            ...this.constructGSI1_SN(item),
+        };
+    }
+    /**
+     * Constructs GSI1_SS (String-String) index keys for resource-based queries.
+     *
+     * The partition key combines app, resourceType, and resourceId for
+     * efficient querying of all audits for a specific resource.
+     * When tenantId is provided, it prefixes the partition key for multi-tenant isolation.
+     *
+     * @param identifiers - Full identifiers including resourceId and optional tenantId
+     * @returns GSI1_SS key attributes
+     * @internal
+     */
+    constructGSI1_SS({ tenantId, app, id, resourceType, resourceId, }) {
+        const pkBase = [`${app}.${resourceType}`, resourceId]
+            .filter(Boolean)
+            .join("#");
+        return {
+            [DynamoDB.Keys.GSI1_SS_PARTITION_KEY]: (tenantId
+                ? `${tenantId}#${pkBase}`
+                : pkBase),
+            [DynamoDB.Keys.GSI1_SS_SORT_KEY]: String(id),
+        };
+    }
+    /**
+     * Constructs GSI1_SN (String-Number) index keys for trace-based queries.
+     *
+     * Parses the trace string to extract the trace ID and stage number,
+     * enabling efficient querying of all audits in a distributed trace.
+     * When tenantId is provided, it prefixes the partition key for multi-tenant isolation.
+     *
+     * @param item - The audit storage item
+     * @returns GSI1_SN key attributes, or empty object if no trace
+     * @internal
+     */
+    constructGSI1_SN(item) {
+        if (!item.trace) {
+            return {};
+        }
+        const { id, stage } = getTraceParts(item.trace);
+        const pkBase = `${id}`;
+        return {
+            [DynamoDB.Keys.GSI1_SN_PARTITION_KEY]: (item.tenantId
+                ? `${item.tenantId}#${pkBase}`
+                : pkBase),
+            [DynamoDB.Keys.GSI1_SN_SORT_KEY]: stage,
+        };
+    }
+    /**
+     * Constructs the TTL attribute for automatic item expiration.
+     *
+     * @param ttlSeconds - Seconds until expiration (defaults to 90 days)
+     * @param date - Base date for TTL calculation (defaults to now)
+     * @returns TTL attribute with Unix timestamp in seconds
+     * @internal
+     */
+    constructTTLAttribute(ttlSeconds = DEFAULT_TTL, date) {
+        const ttl = date || new Date();
+        if (ttlSeconds) {
+            ttl.setSeconds(ttl.getSeconds() + ttlSeconds);
+        }
+        return {
+            ttl: Math.floor(ttl.valueOf() / 1000),
+        };
+    }
+    /**
+     * Transforms a raw DynamoDB item into an Audit object.
+     *
+     * Reconstructs the trace string and extracts the clean ID
+     * from compound keys.
+     *
+     * @param item - Raw DynamoDB item with all keys
+     * @returns Parsed and validated Audit object
+     * @internal
+     */
+    transformItem(item) {
+        return Promise.resolve(AuditSchema.parse({
+            trace: `${item.GSI1_SN_PK}:${item.GSI1_SN_SK}`,
+            ...item,
+            id: item.id.split("#").pop(),
+        }));
+    }
+    /**
+     * Transforms a trace listing item into an audit list item payload.
+     *
+     * @param item - Raw trace listing item from GSI1_SN query
+     * @returns Parsed audit list item payload
+     * @internal
+     */
+    transformTraceListItem(item) {
+        const [id] = item.SK.split("#");
+        return AuditListItemPayloadSchema.parse({
+            trace: `${item.GSI1_SN_PK}:${item.GSI1_SN_SK}`,
+            ...item,
+            id: id,
+        });
+    }
+    /**
+     * Transforms a resource listing item into an audit list item payload.
+     *
+     * @param item - Raw listing item from GSI1_SS query
+     * @returns Parsed audit list item payload
+     * @internal
+     */
+    transformListItem(item) {
+        const [id] = item.SK.split("#");
+        return AuditListItemPayloadSchema.parse({
+            trace: `${item.GSI1_SN_PK}:${item.GSI1_SN_SK}`,
+            ...item,
+            id: id,
+        });
+    }
+}

package/dist/repository.utils.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Encodes a pagination object into an encrypted token string.
+ *
+ * Uses AES-256-CTR encryption to obfuscate the DynamoDB LastEvaluatedKey,
+ * preventing clients from tampering with pagination state.
+ *
+ * The token format is: `{iv}:{encryptedData}` where both parts are hex-encoded.
+ *
+ * @param nextPageObject - DynamoDB LastEvaluatedKey object to encode
+ * @returns Encrypted pagination token string, or undefined if input is null/undefined
+ *
+ * @example
+ * ```typescript
+ * const lastKey = { PK: 'App1.USER', SK: 'audit-123' };
+ * const token = encodeNextPageToken(lastKey);
+ * // Returns something like: "a1b2c3d4...:e5f6g7h8..."
+ * ```
+ */
+export declare function encodeNextPageToken(nextPageObject?: Record<string, string>): string | undefined;
+/**
+ * Decodes an encrypted pagination token back into a DynamoDB key object.
+ *
+ * Reverses the encryption performed by {@link encodeNextPageToken} to
+ * restore the original LastEvaluatedKey for DynamoDB queries.
+ *
+ * @param nextPageString - Encrypted pagination token from a previous response
+ * @returns Decoded DynamoDB key object, or undefined if input is null/undefined/invalid
+ *
+ * @example
+ * ```typescript
+ * const token = "a1b2c3d4...:e5f6g7h8...";
+ * const lastKey = decodeNextPageToken(token);
+ * // Returns: { PK: 'App1.USER', SK: 'audit-123' }
+ * ```
+ */
+export declare function decodeNextPageToken(nextPageString?: string | null | undefined): Record<string, string> | undefined;
+//# sourceMappingURL=repository.utils.d.ts.map

package/dist/repository.utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"repository.utils.d.ts","sourceRoot":"","sources":["../src/repository.utils.ts"],"names":[],"mappings":"AAaA;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,mBAAmB,CAClC,cAAc,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GACrC,MAAM,GAAG,SAAS,CAgBpB;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,mBAAmB,CAClC,cAAc,CAAC,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GACxC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,SAAS,CAuBpC"}

package/dist/repository.utils.js

@@ -0,0 +1,70 @@
+import * as crypto from "node:crypto";
+/**
+ * Encryption algorithm used for pagination tokens.
+ * AES-256-CTR provides symmetric encryption with counter mode.
+ */
+const ENCRYPTION_ALGORITHM = "aes-256-ctr";
+/**
+ * Key size in bytes for AES-256 encryption.
+ */
+const KEY_SIZE = 32;
+/**
+ * Encodes a pagination object into an encrypted token string.
+ *
+ * Uses AES-256-CTR encryption to obfuscate the DynamoDB LastEvaluatedKey,
+ * preventing clients from tampering with pagination state.
+ *
+ * The token format is: `{iv}:{encryptedData}` where both parts are hex-encoded.
+ *
+ * @param nextPageObject - DynamoDB LastEvaluatedKey object to encode
+ * @returns Encrypted pagination token string, or undefined if input is null/undefined
+ *
+ * @example
+ * ```typescript
+ * const lastKey = { PK: 'App1.USER', SK: 'audit-123' };
+ * const token = encodeNextPageToken(lastKey);
+ * // Returns something like: "a1b2c3d4...:e5f6g7h8..."
+ * ```
+ */
+export function encodeNextPageToken(nextPageObject) {
+    if (nextPageObject == null) {
+        return undefined;
+    }
+    const nextPageString = JSON.stringify(nextPageObject);
+    const iv = crypto.randomBytes(16);
+    const cipher = crypto.createCipheriv(ENCRYPTION_ALGORITHM, Buffer.concat([Buffer.alloc(KEY_SIZE)], KEY_SIZE), iv);
+    const encrypted = cipher.update(nextPageString);
+    return [iv.toString("hex"), encrypted.toString("hex")].join(":");
+}
+/**
+ * Decodes an encrypted pagination token back into a DynamoDB key object.
+ *
+ * Reverses the encryption performed by {@link encodeNextPageToken} to
+ * restore the original LastEvaluatedKey for DynamoDB queries.
+ *
+ * @param nextPageString - Encrypted pagination token from a previous response
+ * @returns Decoded DynamoDB key object, or undefined if input is null/undefined/invalid
+ *
+ * @example
+ * ```typescript
+ * const token = "a1b2c3d4...:e5f6g7h8...";
+ * const lastKey = decodeNextPageToken(token);
+ * // Returns: { PK: 'App1.USER', SK: 'audit-123' }
+ * ```
+ */
+export function decodeNextPageToken(nextPageString) {
+    if (nextPageString == null) {
+        return undefined;
+    }
+    const textParts = nextPageString.split(":");
+    const iv = textParts.shift();
+    if (!iv) {
+        return undefined;
+    }
+    const decipher = crypto.createDecipheriv(ENCRYPTION_ALGORITHM, Buffer.concat([Buffer.alloc(KEY_SIZE)], KEY_SIZE), Buffer.from(iv, "hex"));
+    const decrypted = Buffer.concat([
+        decipher.update(Buffer.from(textParts.join(":"), "hex")),
+        decipher.final(),
+    ]);
+    return JSON.parse(decrypted.toString());
+}