sailfork / t3code-github / .repos/ alchemy-effect/ packages/ aws/ src/ WAFv2/ LoggingConfiguration.ts

import type * as WAFV2 from "@distilled.cloud/aws/wafv2";
import * as wafv2 from "@distilled.cloud/aws/wafv2";
import { deepEqual, isResolved } from "alchemy/Diff";
import * as Provider from "alchemy/Provider";
import { Resource } from "alchemy/Resource";
import * as Effect from "effect/Effect";
import * as Schedule from "effect/Schedule";
import type { Providers } from "../Providers.ts";
import { type WafScope, withWafScope } from "./internal.ts";

export interface LoggingConfigurationProps {
  /**
   * ARN of the {@link WebACL} to enable logging for. Changing the web ACL
   * replaces the logging configuration.
   */
  resourceArn: string;
  /**
   * ARNs of the log destinations — an Amazon Kinesis Data Firehose delivery
   * stream, a CloudWatch Logs log group, or an S3 bucket. The destination
   * name must begin with `aws-waf-logs-`. A trailing `:*` on a CloudWatch
   * Logs log group ARN is stripped automatically (WAF rejects it).
   */
  logDestinationConfigs: string[];
  /**
   * Parts of each logged request to redact (e.g. a specific header or the
   * query string). Only `SingleHeader`, `UriPath`, `QueryString`, and
   * `Method` are supported by WAF. Raw WAFv2 API shapes.
   */
  redactedFields?: WAFV2.FieldToMatch[];
  /**
   * Filter which requests are logged based on rule action and labels.
   */
  loggingFilter?: WAFV2.LoggingFilter;
}

export interface LoggingConfiguration extends Resource<
  "AWS.WAFv2.LoggingConfiguration",
  LoggingConfigurationProps,
  {
    /**
     * ARN of the web ACL the logging configuration applies to.
     */
    resourceArn: string;
    /**
     * Scope of the web ACL (derived from its ARN).
     */
    scope: WafScope;
    /**
     * ARNs of the configured log destinations.
     */
    logDestinationConfigs: string[];
  },
  never,
  Providers
> {}

/**
 * The logging configuration of an AWS WAFv2 {@link WebACL} — streams full
 * web request logs to a Kinesis Data Firehose delivery stream, a CloudWatch
 * Logs log group, or an S3 bucket.
 *
 * The destination must be named with the `aws-waf-logs-` prefix. A web ACL
 * has at most one logging configuration; deleting this resource disables
 * logging.
 *
 * ### Configuring Logging
 * **Example:** Log to CloudWatch Logs
 * ```typescript
 * const logGroup = yield* AWS.Logs.LogGroup("WafLogs", {
 *   logGroupName: "aws-waf-logs-my-firewall",
 * });
 *
 * yield* AWS.WAFv2.LoggingConfiguration("Logging", {
 *   resourceArn: acl.webAclArn,
 *   logDestinationConfigs: [logGroup.logGroupArn],
 * });
 * ```
 *
 * **Example:** Redact Headers and Filter to Blocked Requests
 * ```typescript
 * yield* AWS.WAFv2.LoggingConfiguration("Logging", {
 *   resourceArn: acl.webAclArn,
 *   logDestinationConfigs: [logGroup.logGroupArn],
 *   redactedFields: [{ SingleHeader: { Name: "authorization" } }],
 *   loggingFilter: {
 *     DefaultBehavior: "DROP",
 *     Filters: [
 *       {
 *         Behavior: "KEEP",
 *         Requirement: "MEETS_ANY",
 *         Conditions: [{ ActionCondition: { Action: "BLOCK" } }],
 *       },
 *     ],
 *   },
 * });
 * ```
 *
 * @resource
 */
export const LoggingConfiguration = Resource<LoggingConfiguration>(
  "AWS.WAFv2.LoggingConfiguration",
);

/**
 * Derive the scope from a WAFv2 entity ARN. CLOUDFRONT-scoped ARNs carry a
 * `global/` resource prefix (`arn:aws:wafv2:us-east-1:acct:global/webacl/…`);
 * REGIONAL ARNs carry `regional/`.
 */
const scopeOfArn = (arn: string): WafScope =>
  arn.split(":")[5]?.startsWith("global/") ? "CLOUDFRONT" : "REGIONAL";

/**
 * WAF rejects CloudWatch Logs log group ARNs with the `:*` suffix that IAM
 * policies (and the Logs API) use — strip it.
 */
const normalizeDestination = (arn: string): string => (arn.endsWith(":*") ? arn.slice(0, -2) : arn);

/**
 * The first PutLoggingConfiguration in an account creates the WAF
 * service-linked role; until that completes the API surfaces
 * `WAFServiceLinkedRoleErrorException` ("Retry your request"). Bounded
 * retry (~30s).
 */
const retryServiceLinkedRole = <A, E extends { _tag: string }, R>(
  self: Effect.Effect<A, E, R>,
): Effect.Effect<A, E, R> =>
  Effect.retry(self, {
    while: (e) => e._tag === "WAFServiceLinkedRoleErrorException",
    schedule: Schedule.max([Schedule.fixed("3 seconds"), Schedule.recurs(10)]),
  });

export const LoggingConfigurationProvider = () =>
  Provider.effect(
    LoggingConfiguration,
    Effect.gen(function* () {
      const readConfig = Effect.fn(function* (resourceArn: string) {
        const scope = scopeOfArn(resourceArn);
        return yield* withWafScope(
          scope,
          wafv2
            .getLoggingConfiguration({ ResourceArn: resourceArn })
            .pipe(Effect.catchTag("WAFNonexistentItemException", () => Effect.undefined)),
        );
      });

      const toAttrs = (resourceArn: string, destinations: readonly string[]) => ({
        resourceArn,
        scope: scopeOfArn(resourceArn),
        logDestinationConfigs: [...destinations],
      });

      return LoggingConfiguration.Provider.of({
        stables: ["resourceArn", "scope"],

        // A logging configuration is a singleton setting keyed by its web
        // ACL; enumerating them standalone is not useful for orphan scans
        // (the web ACL itself is the discoverable resource).
        list: () => Effect.succeed([]),

        diff: Effect.fn(function* ({ news, olds }) {
          if (!isResolved(news)) return undefined;
          if (olds.resourceArn !== news.resourceArn) {
            return { action: "replace" } as const;
          }
        }),

        read: Effect.fn(function* ({ olds, output }) {
          const resourceArn = output?.resourceArn ?? olds?.resourceArn;
          if (resourceArn === undefined) return undefined;
          const found = yield* readConfig(resourceArn);
          const config = found?.LoggingConfiguration;
          if (!config) return undefined;
          return toAttrs(resourceArn, config.LogDestinationConfigs ?? []);
        }),

        reconcile: Effect.fn(function* ({ news, session }) {
          const scope = scopeOfArn(news.resourceArn);
          const desired: WAFV2.LoggingConfiguration = {
            ResourceArn: news.resourceArn,
            LogDestinationConfigs: news.logDestinationConfigs.map(normalizeDestination),
            RedactedFields: news.redactedFields,
            LoggingFilter: news.loggingFilter,
          };

          // Observe — PutLoggingConfiguration is a true upsert, so only
          // call it when the observed configuration drifts from desired.
          const observed = yield* readConfig(news.resourceArn);
          const current = observed?.LoggingConfiguration;
          const drifted = !deepEqual(
            {
              LogDestinationConfigs: current?.LogDestinationConfigs ?? [],
              RedactedFields: current?.RedactedFields,
              LoggingFilter: current?.LoggingFilter,
            },
            {
              LogDestinationConfigs: desired.LogDestinationConfigs,
              RedactedFields: desired.RedactedFields,
              LoggingFilter: desired.LoggingFilter,
            },
            { stripNullish: true },
          );
          if (current === undefined || drifted) {
            yield* retryServiceLinkedRole(
              withWafScope(
                scope,
                wafv2.putLoggingConfiguration({
                  LoggingConfiguration: desired,
                }),
              ),
            );
          }

          yield* session.note(news.resourceArn);
          return toAttrs(news.resourceArn, desired.LogDestinationConfigs);
        }),

        delete: Effect.fn(function* ({ output }) {
          const scope = scopeOfArn(output.resourceArn);
          // Idempotent — the configuration (or the web ACL itself) may
          // already be gone.
          yield* withWafScope(
            scope,
            wafv2
              .deleteLoggingConfiguration({
                ResourceArn: output.resourceArn,
              })
              .pipe(Effect.catchTag("WAFNonexistentItemException", () => Effect.void)),
          );
        }),
      });
    }),
  );