import * as shield from "@distilled.cloud/aws/shield";
import { Unowned } from "alchemy/AdoptPolicy";
import { isResolved } from "alchemy/Diff";
import { createPhysicalName } from "alchemy/PhysicalName";
import * as Provider from "alchemy/Provider";
import { Resource } from "alchemy/Resource";
import { createInternalTags, diffTags, hasAlchemyTags, tagRecord } from "alchemy/Tags";
import * as Data from "effect/Data";
import * as Effect from "effect/Effect";
import * as Stream from "effect/Stream";
import type { Providers } from "../Providers.ts";
export class ProtectionUnexpectedResponse extends Data.TaggedError("ProtectionUnexpectedResponse")<{
readonly message: string;
readonly cause?: unknown;
}> {}
/** Route 53 health check ARNs look like `arn:aws:route53:::healthcheck/{id}`. */
const healthCheckIdFromArn = (arn: string) => arn.split("/").pop() ?? arn;
const healthCheckArnFromId = (id: string) => `arn:aws:route53:::healthcheck/${id}`;
/**
* How Shield Advanced responds automatically to application-layer (layer 7)
* DDoS attacks against the protected resource: `BLOCK` the attacking traffic
* with the associated AWS WAF web ACL, or `COUNT` it for visibility only.
*/
export type ApplicationLayerAutomaticResponseAction = "BLOCK" | "COUNT";
export interface ProtectionProps {
/**
* Friendly name for the protection. Immutable — changing it replaces the
* protection. If omitted, a unique name is generated.
*/
name?: string;
/**
* ARN of the resource to protect (CloudFront distribution, Route 53 hosted
* zone, Global Accelerator, ALB, CLB, or Elastic IP allocation). Immutable —
* changing it replaces the protection.
*/
resourceArn: string;
/**
* Route 53 health check ARNs to associate with the protection for
* health-based DDoS detection. Mutable.
*/
healthCheckArns?: string[];
/**
* Shield Advanced automatic application-layer DDoS mitigation: `BLOCK`
* attacking traffic with the associated AWS WAF web ACL, or `COUNT` it for
* visibility only. Omit to leave the feature disabled. Only supported for
* CloudFront distributions and Application Load Balancers that have an
* associated web ACL. Mutable.
*/
applicationLayerAutomaticResponse?: ApplicationLayerAutomaticResponseAction;
/**
* User-defined tags. Alchemy ownership tags are merged in automatically.
*/
tags?: Record<string, string>;
}
export interface Protection extends Resource<
"AWS.Shield.Protection",
ProtectionProps,
{
/** Unique identifier of the protection. */
protectionId: string;
/** ARN of the protection. */
protectionArn: string;
/** Name of the protection. */
name: string;
/** ARN of the protected resource. */
resourceArn: string;
/** IDs of the associated Route 53 health checks. */
healthCheckIds: string[];
/**
* The automatic application-layer DDoS mitigation action, or `undefined`
* when the feature is disabled.
*/
applicationLayerAutomaticResponse: ApplicationLayerAutomaticResponseAction | undefined;
/** Tags on the protection (including Alchemy ownership tags). */
tags: Record<string, string>;
},
never,
Providers
> {}
/**
* An AWS Shield Advanced Protection for a single resource (CloudFront
* distribution, Route 53 hosted zone, Global Accelerator, Application/Classic
* Load Balancer, or Elastic IP).
*
* Requires an active Shield Advanced subscription ($3,000/month with a 1-year
* commitment); without one every call fails with the typed
* `SubscriptionNotFound` error.
*
* ### Protecting Resources
* **Example:** Protect a CloudFront Distribution
* ```typescript
* const protection = yield* Shield.Protection("SiteProtection", {
* resourceArn: distribution.distributionArn,
* });
* ```
*
* **Example:** Protection with Health-Based Detection
* ```typescript
* const protection = yield* Shield.Protection("ApiProtection", {
* name: "api-protection",
* resourceArn: loadBalancer.loadBalancerArn,
* healthCheckArns: ["arn:aws:route53:::healthcheck/11111111-2222-3333-4444-555555555555"],
* tags: { team: "platform" },
* });
* ```
*
* ### Automatic Application-Layer Mitigation
* **Example:** Block Layer-7 Attacks Automatically
* ```typescript
* // Requires an AWS WAF web ACL associated with the CloudFront distribution
* // or Application Load Balancer.
* const protection = yield* Shield.Protection("SiteProtection", {
* resourceArn: distribution.distributionArn,
* applicationLayerAutomaticResponse: "BLOCK",
* });
* ```
*/
export const Protection = Resource<Protection>("AWS.Shield.Protection");
const observeByResourceArn = (resourceArn: string) =>
shield.describeProtection({ ResourceArn: resourceArn }).pipe(
Effect.map((r) => r.Protection),
Effect.catchTag(["ResourceNotFoundException", "SubscriptionNotFound"], () => Effect.undefined),
);
const toTagRecord = (tags: shield.Tag[] | undefined): Record<string, string> =>
tagRecord(
(tags ?? []).flatMap((t) =>
t.Key !== undefined && t.Value !== undefined ? [{ Key: t.Key, Value: t.Value }] : [],
),
);
const readProtectionTags = (protectionArn: string) =>
shield.listTagsForResource({ ResourceARN: protectionArn }).pipe(
Effect.map((r) => toTagRecord(r.Tags)),
Effect.orElseSucceed(() => ({})),
);
/**
* Collapse the observed ALAR configuration to the prop shape: the action when
* enabled, `undefined` when disabled or never configured.
*/
const observedAlarAction = (
protection: shield.Protection,
): ApplicationLayerAutomaticResponseAction | undefined => {
const config = protection.ApplicationLayerAutomaticResponseConfiguration;
if (config?.Status !== "ENABLED") return undefined;
return config.Action.Block !== undefined ? "BLOCK" : "COUNT";
};
const buildAttrs = (protection: shield.Protection, tags: Record<string, string>) => ({
protectionId: protection.Id!,
protectionArn: protection.ProtectionArn!,
name: protection.Name!,
resourceArn: protection.ResourceArn!,
healthCheckIds: [...(protection.HealthCheckIds ?? [])],
applicationLayerAutomaticResponse: observedAlarAction(protection),
tags,
});
export const ProtectionProvider = () =>
Provider.effect(
Protection,
Effect.gen(function* () {
const toName = (id: string, props: { name?: string }) =>
props.name ? Effect.succeed(props.name) : createPhysicalName({ id, maxLength: 128 });
const syncTags = Effect.fn(function* (
protectionArn: string,
desiredTags: Record<string, string>,
) {
const observedTags = yield* readProtectionTags(protectionArn);
const { upsert, removed } = diffTags(observedTags, desiredTags);
if (upsert.length > 0) {
yield* shield.tagResource({
ResourceARN: protectionArn,
Tags: upsert,
});
}
if (removed.length > 0) {
yield* shield.untagResource({
ResourceARN: protectionArn,
TagKeys: removed,
});
}
});
// Automatic application-layer DDoS mitigation: enable, update, or
// disable based on the delta between OBSERVED and desired state.
const syncApplicationLayerAutomaticResponse = Effect.fn(function* (
resourceArn: string,
observed: ApplicationLayerAutomaticResponseAction | undefined,
desired: ApplicationLayerAutomaticResponseAction | undefined,
) {
if (observed === desired) return;
if (desired === undefined) {
yield* shield.disableApplicationLayerAutomaticResponse({
ResourceArn: resourceArn,
});
return;
}
const Action = desired === "BLOCK" ? { Block: {} } : { Count: {} };
if (observed === undefined) {
yield* shield.enableApplicationLayerAutomaticResponse({
ResourceArn: resourceArn,
Action,
});
} else {
yield* shield.updateApplicationLayerAutomaticResponse({
ResourceArn: resourceArn,
Action,
});
}
});
const syncHealthChecks = Effect.fn(function* (
protectionId: string,
observedIds: readonly string[],
desiredArns: readonly string[],
) {
const desiredIds = desiredArns.map(healthCheckIdFromArn);
for (const arn of desiredArns) {
if (!observedIds.includes(healthCheckIdFromArn(arn))) {
yield* shield.associateHealthCheck({
ProtectionId: protectionId,
HealthCheckArn: arn,
});
}
}
for (const observedId of observedIds) {
if (!desiredIds.includes(observedId)) {
yield* shield.disassociateHealthCheck({
ProtectionId: protectionId,
HealthCheckArn: healthCheckArnFromId(observedId),
});
}
}
});
return {
stables: ["protectionId", "protectionArn", "name", "resourceArn"],
diff: Effect.fn(function* ({ id, olds, news }) {
if (!isResolved(news)) return;
if (olds === undefined) return;
if (olds.resourceArn !== news.resourceArn) {
return { action: "replace" } as const;
}
if ((yield* toName(id, olds)) !== (yield* toName(id, news))) {
return { action: "replace" } as const;
}
}),
read: Effect.fn(function* ({ id, olds, output }) {
const resourceArn = output?.resourceArn ?? olds?.resourceArn;
if (resourceArn === undefined) return undefined;
const protection = yield* observeByResourceArn(resourceArn);
if (!protection?.Id || !protection.ProtectionArn) return undefined;
const tags = yield* readProtectionTags(protection.ProtectionArn);
const attrs = buildAttrs(protection, tags);
return (yield* hasAlchemyTags(id, tags)) ? attrs : Unowned(attrs);
}),
reconcile: Effect.fn(function* ({ id, news, session }) {
const name = yield* toName(id, news);
const internalTags = yield* createInternalTags(id);
const desiredTags = { ...news.tags, ...internalTags };
// 1. OBSERVE — cloud state is authoritative; a protection is keyed
// by the resource it protects.
let protection = yield* observeByResourceArn(news.resourceArn);
// 2. ENSURE — create if missing; tolerate the AlreadyExists race.
if (!protection?.Id) {
yield* shield
.createProtection({
Name: name,
ResourceArn: news.resourceArn,
Tags: Object.entries(desiredTags).map(([Key, Value]) => ({
Key,
Value,
})),
})
.pipe(Effect.catchTag("ResourceAlreadyExistsException", () => Effect.void));
protection = yield* observeByResourceArn(news.resourceArn);
if (!protection?.Id || !protection.ProtectionArn) {
return yield* new ProtectionUnexpectedResponse({
message: `Failed to create or read Shield protection for ${news.resourceArn}`,
});
}
}
// 3. SYNC health check associations — diff observed against desired.
yield* syncHealthChecks(
protection.Id,
protection.HealthCheckIds ?? [],
news.healthCheckArns ?? [],
);
// 3b. SYNC automatic application-layer DDoS mitigation.
yield* syncApplicationLayerAutomaticResponse(
news.resourceArn,
observedAlarAction(protection),
news.applicationLayerAutomaticResponse,
);
// 3c. SYNC tags — diff against OBSERVED cloud tags.
yield* syncTags(protection.ProtectionArn!, desiredTags);
// 4. RETURN fresh attributes.
const final = yield* observeByResourceArn(news.resourceArn);
yield* session.note(protection.ProtectionArn!);
return buildAttrs(final ?? protection, desiredTags);
}),
// Enumerate every protection in the account. Without a Shield Advanced
// subscription the account cannot have any protections.
list: () =>
Effect.gen(function* () {
const protections = yield* shield.listProtections.pages({}).pipe(
Stream.runCollect,
Effect.map((chunk) => Array.from(chunk).flatMap((page) => page.Protections ?? [])),
Effect.catchTag("SubscriptionNotFound", () => Effect.succeed([])),
);
return yield* Effect.forEach(
protections.filter((p) => p.Id != null && p.ProtectionArn != null),
(protection) =>
Effect.gen(function* () {
const tags = yield* readProtectionTags(protection.ProtectionArn!);
return buildAttrs(protection, tags);
}),
{ concurrency: 5 },
);
}),
delete: Effect.fn(function* ({ output }) {
yield* shield
.deleteProtection({ ProtectionId: output.protectionId })
.pipe(
Effect.catchTag(
["ResourceNotFoundException", "SubscriptionNotFound"],
() => Effect.void,
),
);
}),
};
}),
);