@digitraffic/common 2026.3.17-1 → 2026.3.26-1-beta

package/dist/aws/infra/acl-builder.js

@@ -0,0 +1,407 @@
+import { CfnIPSet, CfnWebACL } from "aws-cdk-lib/aws-wafv2";
+import { range, zipWith } from "es-toolkit";
+import { logger } from "../runtime/dt-logger-default.js";
+/**
+ * Builder class for building CfnWebACL.
+ *
+ * Currently supports:
+ * * Some AWS managed WAF rules
+ * * IP blacklisting/whitelisting
+ */
+export class AclBuilder {
+    _construct;
+    _countRules = [];
+    _blockRules = [];
+    _name = "WebACL";
+    _scope = "CLOUDFRONT";
+    _customResponseBodies = {};
+    constructor(construct, name = "WebACL") {
+        this._construct = construct;
+        this._name = name;
+    }
+    isRuleDefined(rules, rule) {
+        return rules === "all" || rules.includes(rule);
+    }
+    withAWSManagedRules(rules = "all", excludedRules = {}) {
+        if (this.isRuleDefined(rules, "CommonRuleSet")) {
+            this._blockRules.push(createAWSCommonRuleSet(excludedRules?.CommonRuleSet));
+        }
+        if (this.isRuleDefined(rules, "AmazonIpReputationList")) {
+            this._blockRules.push(createAWSReputationList(excludedRules?.AmazonIpReputationList));
+        }
+        if (this.isRuleDefined(rules, "KnownBadInputsRuleSet")) {
+            this._blockRules.push(createAWSKnownBadInput(excludedRules?.KnownBadInputsRuleSet));
+        }
+        if (this.isRuleDefined(rules, "SQLiRuleSet")) {
+            this._blockRules.push(createAWSAntiSQLInjection(excludedRules?.SQLiRuleSet));
+        }
+        return this;
+    }
+    /**
+     * Block access from given addresses
+     */
+    withIpBlacklistRule(addresses) {
+        const blocklistIpSet = new CfnIPSet(this._construct, "BlocklistIpSet", {
+            ipAddressVersion: "IPV4",
+            scope: this._scope,
+            addresses,
+        });
+        this._blockRules.push({
+            name: "IpBlocklist",
+            action: { block: {} },
+            statement: {
+                ipSetReferenceStatement: {
+                    arn: blocklistIpSet.attrArn,
+                },
+            },
+            visibilityConfig: {
+                sampledRequestsEnabled: false,
+                cloudWatchMetricsEnabled: true,
+                metricName: "IpBlocklist",
+            },
+        });
+        return this;
+    }
+    /**
+     * Allow access only from the given addresses
+     */
+    withIpWhitelistRule(addresses) {
+        const blocklistIpSet = new CfnIPSet(this._construct, "AllowlistIpSet", {
+            ipAddressVersion: "IPV4",
+            scope: this._scope,
+            addresses,
+        });
+        this._blockRules.push({
+            name: "IpAllowlist",
+            action: { block: {} },
+            statement: {
+                notStatement: {
+                    statement: {
+                        ipSetReferenceStatement: {
+                            arn: blocklistIpSet.attrArn,
+                        },
+                    },
+                },
+            },
+            visibilityConfig: {
+                sampledRequestsEnabled: false,
+                cloudWatchMetricsEnabled: true,
+                metricName: "IpAllowlist",
+            },
+        });
+        return this;
+    }
+    withThrottleRule(name, limit, isHeaderRequired, isBasedOnIpAndUriPath, customResponseBodyKey, path) {
+        const isBlockRule = !!customResponseBodyKey;
+        const rules = isBlockRule ? this._blockRules : this._countRules;
+        const action = isBlockRule
+            ? {
+                block: {
+                    customResponse: {
+                        responseCode: 429,
+                        customResponseBodyKey,
+                    },
+                },
+            }
+            : {
+                count: {},
+            };
+        rules.push({
+            name,
+            visibilityConfig: {
+                sampledRequestsEnabled: true,
+                cloudWatchMetricsEnabled: true,
+                metricName: name,
+            },
+            action,
+            statement: createThrottleStatement(limit, isHeaderRequired, isBasedOnIpAndUriPath, path),
+        });
+        return this;
+    }
+    withCustomResponseBody(key, customResponseBody) {
+        if (key in this._customResponseBodies) {
+            logger.warn({
+                method: "acl-builder.withCustomResponseBody",
+                message: `Overriding custom response body with key ${key} for distribution ${this._name}`,
+            });
+        }
+        this._customResponseBodies[key] = customResponseBody;
+        return this;
+    }
+    withThrottleDigitrafficUserIp(limit) {
+        if (limit === undefined) {
+            return this;
+        }
+        const customResponseBodyKey = `IP_THROTTLE_DIGITRAFFIC_USER_${limit}`;
+        this._addThrottleResponseBody(customResponseBodyKey, limit);
+        return this.withThrottleRule("ThrottleRuleWithDigitrafficUser", limit, true, false, customResponseBodyKey);
+    }
+    withThrottleDigitrafficUserIpAndUriPath(limit) {
+        if (limit === undefined) {
+            return this;
+        }
+        const customResponseBodyKey = `IP_PATH_THROTTLE_DIGITRAFFIC_USER_${limit}`;
+        this._addThrottleResponseBody(customResponseBodyKey, limit);
+        return this.withThrottleRule("ThrottleRuleIPQueryWithDigitrafficUser", limit, true, true, customResponseBodyKey);
+    }
+    withThrottleAnonymousUserIp(limit) {
+        if (limit === undefined) {
+            return this;
+        }
+        const customResponseBodyKey = `IP_THROTTLE_ANONYMOUS_USER_${limit}`;
+        this._addThrottleResponseBody(customResponseBodyKey, limit);
+        return this.withThrottleRule("ThrottleRuleWithAnonymousUser", limit, false, false, customResponseBodyKey);
+    }
+    withThrottleAnonymousUserIpByUriPath(limit, path) {
+        if (limit === undefined || path === undefined) {
+            return this;
+        }
+        const customResponseBodyKey = `IP_THROTTLE_ANONYMOUS_USER_BY_PATH_${limit}`;
+        this._addThrottleResponseBody(customResponseBodyKey, limit);
+        return this.withThrottleRule("ThrottleRuleWithAnonymousUserByPath", limit, false, false, customResponseBodyKey, path);
+    }
+    withThrottleAnonymousUserIpAndUriPath(limit) {
+        if (limit === undefined) {
+            return this;
+        }
+        const customResponseBodyKey = `IP_PATH_THROTTLE_ANONYMOUS_USER_${limit}`;
+        this._addThrottleResponseBody(customResponseBodyKey, limit);
+        return this.withThrottleRule("ThrottleRuleIPQueryWithAnonymousUser", limit, false, true, customResponseBodyKey);
+    }
+    withCountDigitrafficUserIp(limit) {
+        if (limit === undefined) {
+            return this;
+        }
+        return this.withThrottleRule(`CountRuleWithDigitrafficUser${limit}`, limit, true, false);
+    }
+    withCountDigitrafficUserIpAndUriPath(limit) {
+        if (limit === undefined) {
+            return this;
+        }
+        return this.withThrottleRule(`CountRuleIPQueryWithDigitrafficUser${limit}`, limit, true, true);
+    }
+    withCountAnonymousUserIp(limit) {
+        if (limit === undefined) {
+            return this;
+        }
+        return this.withThrottleRule(`CountRuleWithAnonymousUser${limit}`, limit, false, false);
+    }
+    withCountAnonymousUserIpAndUriPath(limit) {
+        if (limit === undefined) {
+            return this;
+        }
+        return this.withThrottleRule(`CountRuleIPQueryWithAnonymousUser${limit}`, limit, false, true);
+    }
+    /**
+     * Block requests with a query string larger than the specified size.
+     */
+    withQueryStringSizeRestriction(limit) {
+        this._blockRules.push({
+            name: "QueryStringSizeRestriction",
+            action: { block: {} },
+            statement: {
+                sizeConstraintStatement: {
+                    fieldToMatch: {
+                        queryString: {},
+                    },
+                    comparisonOperator: "GT",
+                    size: limit,
+                    textTransformations: [{ priority: 0, type: "NONE" }],
+                },
+            },
+            visibilityConfig: {
+                sampledRequestsEnabled: true,
+                cloudWatchMetricsEnabled: true,
+                metricName: "QueryStringSizeRestriction",
+            },
+        });
+        return this;
+    }
+    _isCustomResponseBodyKeySet(key) {
+        return key in this._customResponseBodies;
+    }
+    _addThrottleResponseBody(customResponseBodyKey, limit) {
+        if (!this._isCustomResponseBodyKeySet(customResponseBodyKey)) {
+            this.withCustomResponseBody(customResponseBodyKey, {
+                content: `Request rate is limited to ${limit} requests in a 5 minute window.`,
+                contentType: "TEXT_PLAIN",
+            });
+        }
+    }
+    build() {
+        const addPriority = (rule, priority) => ({
+            ...rule,
+            priority,
+        });
+        const rules = [
+            ...zipWith(this._countRules, range(this._countRules.length), addPriority),
+            ...zipWith(this._blockRules, range(this._blockRules.length).map((n) => n + this._countRules.length), addPriority),
+        ];
+        if (rules.length === 0) {
+            throw new Error("No rules defined for WebACL");
+        }
+        const uniqueRuleNames = new Set(rules.map((rule) => rule.name));
+        if (uniqueRuleNames.size !== rules.length) {
+            throw new Error("Tried to create an Access Control List with multiple rules having the same name");
+        }
+        return new CfnWebACL(this._construct, this._name, {
+            defaultAction: { allow: {} },
+            scope: this._scope,
+            visibilityConfig: {
+                cloudWatchMetricsEnabled: true,
+                metricName: "WAF-Blocked",
+                sampledRequestsEnabled: false,
+            },
+            rules,
+            ...(this._customResponseBodies && {
+                customResponseBodies: this._customResponseBodies,
+            }),
+        });
+    }
+}
+const CUSTOM_KEYS_IP_AND_URI_PATH = [
+    {
+        uriPath: {
+            textTransformations: [
+                {
+                    priority: 1,
+                    type: "LOWERCASE",
+                },
+                {
+                    priority: 2,
+                    type: "NORMALIZE_PATH",
+                },
+                {
+                    priority: 3,
+                    type: "MD5",
+                },
+            ],
+        },
+    },
+    {
+        ip: {},
+    },
+];
+function notStatement(statement) {
+    return {
+        notStatement: {
+            statement,
+        },
+    };
+}
+function createThrottleStatement(limit, isHeaderRequired, isBasedOnIpAndUriPath, path) {
+    // this statement matches empty digitraffic-user -header
+    const matchStatement = {
+        sizeConstraintStatement: {
+            comparisonOperator: isHeaderRequired ? "GT" : "GE",
+            fieldToMatch: {
+                singleHeader: {
+                    Name: "digitraffic-user",
+                },
+            },
+            textTransformations: [{ priority: 0, type: "NONE" }],
+            size: 0,
+        },
+    };
+    // header present       -> size > 0
+    // header not present   -> NOT(size >= 0)
+    let scopeDownStatement = isHeaderRequired
+        ? matchStatement
+        : notStatement(matchStatement);
+    if (path) {
+        const pathMatchStatement = {
+            regexMatchStatement: {
+                fieldToMatch: {
+                    uriPath: {},
+                },
+                regexString: path.source,
+                textTransformations: [{ priority: 0, type: "NONE" }],
+            },
+        };
+        scopeDownStatement = {
+            andStatement: {
+                statements: [scopeDownStatement, pathMatchStatement],
+            },
+        };
+    }
+    if (isBasedOnIpAndUriPath) {
+        return {
+            rateBasedStatement: {
+                aggregateKeyType: "CUSTOM_KEYS",
+                customKeys: CUSTOM_KEYS_IP_AND_URI_PATH,
+                limit: limit,
+                scopeDownStatement,
+            },
+        };
+    }
+    return {
+        rateBasedStatement: {
+            aggregateKeyType: "IP",
+            limit: limit,
+            scopeDownStatement,
+        },
+    };
+}
+function createAWSCommonRuleSet(excludedRules = []) {
+    return createRuleProperty("AWS-AWSManagedRulesCommonRuleSet", {
+        statement: {
+            managedRuleGroupStatement: {
+                vendorName: "AWS",
+                name: "AWSManagedRulesCommonRuleSet",
+                excludedRules: [
+                    { name: "NoUserAgent_HEADER" },
+                    { name: "SizeRestrictions_BODY" },
+                    { name: "GenericRFI_BODY" },
+                ].concat((excludedRules ?? []).map((rule) => ({ name: rule }))),
+            },
+        },
+    });
+}
+function createAWSReputationList(excludedRules = []) {
+    return createRuleProperty("AWS-AWSManagedRulesAmazonIpReputationList", {
+        statement: {
+            managedRuleGroupStatement: {
+                vendorName: "AWS",
+                name: "AWSManagedRulesAmazonIpReputationList",
+                excludedRules: (excludedRules ?? []).map((rule) => ({ name: rule })),
+            },
+        },
+    });
+}
+function createAWSKnownBadInput(excludedRules = []) {
+    return createRuleProperty("AWS-AWSManagedRulesKnownBadInputsRuleSet", {
+        statement: {
+            managedRuleGroupStatement: {
+                vendorName: "AWS",
+                name: "AWSManagedRulesKnownBadInputsRuleSet",
+                excludedRules: (excludedRules ?? []).map((rule) => ({ name: rule })),
+            },
+        },
+    });
+}
+function createAWSAntiSQLInjection(excludedRules = []) {
+    return createRuleProperty("AWS-AWSManagedRulesSQLiRuleSet", {
+        statement: {
+            managedRuleGroupStatement: {
+                vendorName: "AWS",
+                name: "AWSManagedRulesSQLiRuleSet",
+                excludedRules: (excludedRules ?? []).map((rule) => ({ name: rule })),
+            },
+        },
+    });
+}
+function createRuleProperty(name, rule, overrideAction = true) {
+    return {
+        ...{
+            name,
+            visibilityConfig: {
+                sampledRequestsEnabled: true,
+                cloudWatchMetricsEnabled: true,
+                metricName: name,
+            },
+        },
+        ...rule,
+        ...(overrideAction ? { overrideAction: { none: {} } } : {}),
+    };
+}
+//# sourceMappingURL=acl-builder.js.map

package/dist/aws/infra/api/handler-factory.d.ts

@@ -0,0 +1,22 @@
+import type { DtLogger } from "../../runtime/dt-logger.js";
+import type { LambdaResponse } from "../../types/lambda-response.js";
+export type LoggingHandler = (method: () => Promise<LambdaResponse>, logger: DtLogger) => Promise<LambdaResponse>;
+export type ErrorHandler = (error: unknown, logger: DtLogger) => LambdaResponse;
+/**
+ * Factory class for creating lambda-handler functions.  You can set functionality to handle logging and error-handling,
+ * with the defaults:
+ * * No error handling
+ * * Execution time logging
+ *
+ * You should instantiate HandlerFactory in your project with desired error handling and use the factory instance for
+ * creating handler-functions for your lambdas.
+ */
+export declare class HandlerFactory {
+    private loggingHandler;
+    private errorHandler;
+    constructor();
+    withLoggingHandler(loggingHandler: LoggingHandler): HandlerFactory;
+    withErrorHandler(errorHandler: ErrorHandler): HandlerFactory;
+    createEventHandler(handler: (event: unknown) => Promise<LambdaResponse>, logger: DtLogger): (event: unknown) => Promise<LambdaResponse>;
+}
+export declare function createJsonLoggingHandler(): LoggingHandler;

package/dist/aws/infra/api/handler-factory.js

@@ -0,0 +1,68 @@
+import { getEnvVariableOrElse } from "../../../utils/utils.js";
+import { logger } from "../../runtime/dt-logger-default.js";
+const functionName = getEnvVariableOrElse("AWS_LAMBDA_FUNCTION_NAME", "test");
+/**
+ * Factory class for creating lambda-handler functions.  You can set functionality to handle logging and error-handling,
+ * with the defaults:
+ * * No error handling
+ * * Execution time logging
+ *
+ * You should instantiate HandlerFactory in your project with desired error handling and use the factory instance for
+ * creating handler-functions for your lambdas.
+ */
+export class HandlerFactory {
+    loggingHandler;
+    errorHandler;
+    constructor() {
+        this.loggingHandler = async (method) => {
+            const start = Date.now();
+            try {
+                return await method();
+            }
+            finally {
+                logger.info({
+                    method: `${functionName}.handler`,
+                    tookMs: Date.now() - start,
+                });
+            }
+        };
+        this.errorHandler = (error) => {
+            throw error;
+        };
+    }
+    withLoggingHandler(loggingHandler) {
+        this.loggingHandler = loggingHandler;
+        return this;
+    }
+    withErrorHandler(errorHandler) {
+        this.errorHandler = errorHandler;
+        return this;
+    }
+    createEventHandler(handler, logger) {
+        return async (event) => {
+            return await this.loggingHandler(async () => {
+                try {
+                    return await handler(event);
+                }
+                catch (error) {
+                    return this.errorHandler(error, logger);
+                }
+            }, logger);
+        };
+    }
+}
+export function createJsonLoggingHandler() {
+    return async (method, logger) => {
+        const start = Date.now();
+        try {
+            return await method();
+        }
+        finally {
+            logger.info({
+                method: `${functionName}.handler`,
+                tookMs: Date.now() - start,
+            });
+        }
+    };
+}
+//# sourceMappingURL=handler-factory.js.map

package/dist/aws/infra/api/integration.d.ts

@@ -0,0 +1,49 @@
+import type { IntegrationResponse } from "aws-cdk-lib/aws-apigateway";
+import { LambdaIntegration } from "aws-cdk-lib/aws-apigateway";
+import type { IFunction } from "aws-cdk-lib/aws-lambda";
+import { MediaType } from "../../types/mediatypes.js";
+type ParameterType = "path" | "querystring" | "multivaluequerystring" | "context" | "header";
+interface ApiParameter {
+    type: ParameterType;
+    name: string;
+}
+export declare class DigitrafficIntegration<T extends string> {
+    readonly lambda: IFunction;
+    readonly mediaType: MediaType;
+    readonly parameters: ApiParameter[];
+    readonly deprecation: boolean;
+    readonly sunset?: string;
+    _passAllQueryParameters: boolean;
+    _passBody: boolean;
+    constructor(lambda: IFunction, mediaType?: MediaType, deprecation?: boolean, sunset?: string);
+    passAllQueryParameters(): this;
+    /**
+     * Body is passed as an base64-encoded string, so broken input should't break anything.  You should
+     * decode, parse and validate the input in the lambda.
+     *
+     * The encoded body will be passed to handler with name payload!!
+     */
+    passBody(): this;
+    addParameter(type: ParameterType, name: string): this;
+    addPathParameter(...names: T[]): this;
+    addQueryParameter(...names: T[]): this;
+    addMultiValueQueryParameter(...names: T[]): this;
+    /**
+     * Note that context parameter values needs to be in json format as they will be parsed in template as json.
+     * See createRequestTemplates below.
+     * @param names for the parameters
+     * @returns
+     */
+    addContextParameter(...names: T[]): this;
+    /**
+     * Do not use Authorization header as that will be consumed by ApiGW.
+     * If Authorization header is needed, use lambda authorizers.
+     * @param names for the headers
+     */
+    addHeaderParameter(...names: T[]): this;
+    build(): LambdaIntegration;
+    createRequestParameters(): Record<string, string>;
+    createRequestTemplates(): Record<string, string>;
+    createResponses(): IntegrationResponse[];
+}
+export {};