sailfork / t3code-github / .repos/ alchemy-effect/ packages/ aws/ src/ SecurityLake/ Subscriber.ts

import * as securitylake from "@distilled.cloud/aws/securitylake";
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 } from "alchemy/Tags";
import * as Data from "effect/Data";
import * as Effect from "effect/Effect";
import * as Option from "effect/Option";
import * as Stream from "effect/Stream";
import type { Providers } from "../Providers.ts";
import { readSecurityLakeTags, retryWhileConflict, toTagList } from "./internal.ts";

/**
 * The AWS identity (principal + external ID) that a subscriber authenticates
 * with when consuming data from Security Lake.
 */
export interface SubscriberIdentity {
  /** The AWS principal (account ID or service principal) of the subscriber. */
  principal: string;
  /** The external ID the subscriber must present when assuming the role. */
  externalId: string;
}

/**
 * A log source a subscriber consumes — either a natively supported AWS source
 * or a custom source.
 */
export type SubscriberSource = securitylake.LogSourceResource;

/**
 * How the subscriber accesses the data — direct S3 access or Lake Formation
 * (query) access.
 */
export type SubscriberAccessType = "LAKEFORMATION" | "S3";

export interface SubscriberProps {
  /**
   * Name of the subscriber. If omitted, a unique physical name is generated
   * from the app, stage, and logical ID.
   */
  subscriberName?: string;

  /**
   * The AWS identity (principal + external ID) the subscriber uses to access
   * Security Lake data.
   */
  subscriberIdentity: SubscriberIdentity;

  /**
   * Description of the subscriber.
   */
  subscriberDescription?: string;

  /**
   * The log sources the subscriber consumes, e.g.
   * `[{ awsLogSource: { sourceName: "ROUTE53", sourceVersion: "2.0" } }]`.
   */
  sources: SubscriberSource[];

  /**
   * How the subscriber accesses the data. Changing this replaces the
   * subscriber (access type is create-only).
   * @default ["S3"]
   */
  accessTypes?: SubscriberAccessType[];

  /**
   * Tags applied to the subscriber. Alchemy ownership tags are merged in
   * automatically.
   */
  tags?: Record<string, string>;
}

/** @resource */
export interface Subscriber extends Resource<
  "AWS.SecurityLake.Subscriber",
  SubscriberProps,
  {
    /** Unique ID of the subscriber (UUID). */
    subscriberId: string;
    /** ARN of the subscriber. */
    subscriberArn: string;
    /** Name of the subscriber. */
    subscriberName: string;
    /** Current status (`ACTIVE`, `PENDING`, `READY`, `DEACTIVATED`). */
    subscriberStatus: string | undefined;
    /** ARN of the IAM role created for the subscriber to assume. */
    roleArn: string | undefined;
    /** ARN of the S3 bucket the subscriber reads from. */
    s3BucketArn: string | undefined;
    /** The subscriber's notification endpoint, if one is configured. */
    subscriberEndpoint: string | undefined;
    /** ARN of the RAM resource share (Lake Formation access only). */
    resourceShareArn: string | undefined;
    /** Name of the RAM resource share (Lake Formation access only). */
    resourceShareName: string | undefined;
  },
  never,
  Providers
> {}

/**
 * A Security Lake subscriber — a consumer (account or service) granted access
 * to data in the Security Lake data lake for specific log sources.
 *
 * ### Creating a Subscriber
 * **Example:** S3 data-access subscriber
 * ```typescript
 * const subscriber = yield* SecurityLake.Subscriber("Analytics", {
 *   subscriberIdentity: {
 *     principal: "123456789012",
 *     externalId: "analytics-external-id",
 *   },
 *   sources: [{ awsLogSource: { sourceName: "ROUTE53", sourceVersion: "2.0" } }],
 * });
 * ```
 *
 * **Example:** Lake Formation (query) access
 * ```typescript
 * const subscriber = yield* SecurityLake.Subscriber("Athena", {
 *   subscriberName: "athena-consumer",
 *   subscriberDescription: "Athena query access to VPC flow logs",
 *   subscriberIdentity: {
 *     principal: "123456789012",
 *     externalId: "athena-external-id",
 *   },
 *   sources: [{ awsLogSource: { sourceName: "VPC_FLOW", sourceVersion: "2.0" } }],
 *   accessTypes: ["LAKEFORMATION"],
 *   tags: { team: "security" },
 * });
 * ```
 */
const SubscriberResource = Resource<Subscriber>("AWS.SecurityLake.Subscriber");

export { SubscriberResource as Subscriber };

/**
 * `CreateSubscriber` returned without a subscriber body and the subscriber
 * could not be re-observed by name.
 */
export class SubscriberCreateFailed extends Data.TaggedError("SubscriberCreateFailed")<{
  readonly subscriberName: string;
}> {}

const buildAttrs = (subscriber: securitylake.SubscriberResource) => ({
  subscriberId: subscriber.subscriberId,
  subscriberArn: subscriber.subscriberArn,
  subscriberName: subscriber.subscriberName,
  subscriberStatus: subscriber.subscriberStatus,
  roleArn: subscriber.roleArn,
  s3BucketArn: subscriber.s3BucketArn,
  subscriberEndpoint: subscriber.subscriberEndpoint,
  resourceShareArn: subscriber.resourceShareArn,
  resourceShareName: subscriber.resourceShareName,
});

// Desired sources match observed sources when every desired entry appears in
// the observed list (AWS resolves an omitted sourceVersion, so it is only
// compared when the desired entry pins one) and the counts agree.
const sourcesMatch = (
  desired: readonly securitylake.LogSourceResource[],
  observed: readonly securitylake.LogSourceResource[],
) =>
  desired.length === observed.length &&
  desired.every((want) => {
    const wantAws = want.awsLogSource;
    if (wantAws !== undefined) {
      return observed.some((have) => {
        const haveAws = have.awsLogSource;
        return (
          haveAws !== undefined &&
          haveAws.sourceName === wantAws.sourceName &&
          (wantAws.sourceVersion === undefined || haveAws.sourceVersion === wantAws.sourceVersion)
        );
      });
    }
    return observed.some(
      (have) =>
        have.customLogSource?.sourceName === want.customLogSource?.sourceName &&
        (want.customLogSource?.sourceVersion === undefined ||
          have.customLogSource?.sourceVersion === want.customLogSource.sourceVersion),
    );
  });

export const SubscriberProvider = () =>
  Provider.effect(
    SubscriberResource,
    Effect.gen(function* () {
      const createName = Effect.fn(function* (id: string, props: { subscriberName?: string }) {
        return props.subscriberName ?? (yield* createPhysicalName({ id, maxLength: 64 }));
      });

      const getById = (subscriberId: string) =>
        securitylake.getSubscriber({ subscriberId }).pipe(
          Effect.map((response) => response.subscriber),
          Effect.catchTag("ResourceNotFoundException", () => Effect.undefined),
        );

      // Subscriber names are unique per account/region — find the live
      // subscriber carrying our deterministic name when state was lost.
      const findByName = (subscriberName: string) =>
        securitylake.listSubscribers.items({}).pipe(
          Stream.filter((subscriber) => subscriber.subscriberName === subscriberName),
          Stream.take(1),
          Stream.runHead,
          Effect.map(Option.getOrUndefined),
        );

      return {
        read: Effect.fn(function* ({ id, olds, output }) {
          // An account that never onboarded Security Lake rejects subscriber
          // APIs with UnauthorizedException — that means "no subscriber".
          const subscriber = yield* (
            output?.subscriberId
              ? getById(output.subscriberId)
              : Effect.flatMap(createName(id, olds ?? {}), findByName)
          ).pipe(Effect.catchTag("UnauthorizedException", () => Effect.undefined));
          if (subscriber === undefined) return undefined;
          const attrs = buildAttrs(subscriber);
          const tags = yield* readSecurityLakeTags(attrs.subscriberArn);
          return (yield* hasAlchemyTags(id, tags)) ? attrs : Unowned(attrs);
        }),

        list: () =>
          securitylake.listSubscribers.items({}).pipe(
            Stream.runCollect,
            Effect.map((subscribers) => [...subscribers].map(buildAttrs)),
            // An account that never onboarded Security Lake has no
            // subscribers to enumerate.
            Effect.catchTag(
              ["AccessDeniedException", "ResourceNotFoundException", "UnauthorizedException"],
              () => Effect.succeed([]),
            ),
          ),

        // accessTypes is create-only (UpdateSubscriber cannot change it).
        diff: Effect.fn(function* ({ news, olds }) {
          if (!isResolved(news)) return undefined;
          const oldAccess = [...(olds.accessTypes ?? ["S3"])].sort();
          const newAccess = [...(news.accessTypes ?? ["S3"])].sort();
          if (
            oldAccess.length !== newAccess.length ||
            oldAccess.some((value, index) => value !== newAccess[index])
          ) {
            return { action: "replace" } as const;
          }
        }),

        reconcile: Effect.fn(function* ({ id, news, output, session }) {
          const subscriberName = yield* createName(id, news);
          const internalTags = yield* createInternalTags(id);
          const desiredTags = { ...news.tags, ...internalTags };

          // 1. OBSERVE — by cached id first, then by deterministic name.
          let subscriber = output?.subscriberId ? yield* getById(output.subscriberId) : undefined;
          subscriber ??= yield* findByName(subscriberName);

          // 2. ENSURE — create when missing; a ConflictException means a
          // concurrent create won the race, so re-observe by name.
          if (subscriber === undefined) {
            subscriber = yield* securitylake
              .createSubscriber({
                subscriberName,
                subscriberIdentity: news.subscriberIdentity,
                subscriberDescription: news.subscriberDescription,
                sources: news.sources,
                accessTypes: news.accessTypes,
                tags: toTagList(desiredTags),
              })
              .pipe(
                Effect.map((response) => response.subscriber),
                Effect.catchTag("ConflictException", () => findByName(subscriberName)),
              );
            if (subscriber === undefined) {
              return yield* new SubscriberCreateFailed({ subscriberName });
            }
          } else {
            // 3. SYNC mutable settings — observed ↔ desired.
            const changed =
              subscriber.subscriberName !== subscriberName ||
              (subscriber.subscriberDescription ?? "") !== (news.subscriberDescription ?? "") ||
              subscriber.subscriberIdentity.principal !== news.subscriberIdentity.principal ||
              subscriber.subscriberIdentity.externalId !== news.subscriberIdentity.externalId ||
              !sourcesMatch(news.sources, subscriber.sources);
            if (changed) {
              subscriber = yield* securitylake
                .updateSubscriber({
                  subscriberId: subscriber.subscriberId,
                  subscriberName,
                  subscriberDescription: news.subscriberDescription,
                  subscriberIdentity: news.subscriberIdentity,
                  sources: news.sources,
                })
                .pipe(
                  retryWhileConflict,
                  Effect.map((response) => response.subscriber ?? subscriber!),
                );
            }

            // 3b. SYNC tags — diff against OBSERVED cloud tags.
            const observedTags = yield* readSecurityLakeTags(subscriber.subscriberArn);
            const { upsert, removed } = diffTags(observedTags, desiredTags);
            if (upsert.length > 0) {
              yield* securitylake.tagResource({
                resourceArn: subscriber.subscriberArn,
                tags: upsert.map((t) => ({ key: t.Key, value: t.Value })),
              });
            }
            if (removed.length > 0) {
              yield* securitylake.untagResource({
                resourceArn: subscriber.subscriberArn,
                tagKeys: removed,
              });
            }
          }

          // 4. RETURN fresh attributes.
          const final = (yield* getById(subscriber.subscriberId)) ?? subscriber;
          yield* session.note(final.subscriberArn);
          return buildAttrs(final);
        }),

        delete: Effect.fn(function* ({ output }) {
          yield* securitylake.deleteSubscriber({ subscriberId: output.subscriberId }).pipe(
            retryWhileConflict,
            // Gone already, or the data lake itself was offboarded first
            // (which removes all subscribers and makes subscriber APIs
            // reject with UnauthorizedException).
            Effect.catchTag(
              ["ResourceNotFoundException", "UnauthorizedException"],
              () => Effect.void,
            ),
          );
        }),
      };
    }),
  );