sailfork / t3code-github / .repos/ alchemy-effect/ packages/ aws/ src/ RAM/ Permission.ts

import * as ram from "@distilled.cloud/aws/ram";
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 Array from "effect/Array";
import * as Data from "effect/Data";
import * as Effect from "effect/Effect";
import * as Schedule from "effect/Schedule";
import * as Stream from "effect/Stream";
import type { Providers } from "../Providers.ts";

export class RAMPermissionUnexpectedResponse extends Data.TaggedError(
  "RAMPermissionUnexpectedResponse",
)<{
  readonly message: string;
  readonly cause?: unknown;
}> {}

/**
 * The policy template of a customer managed permission — the actions a
 * resource share grants to principals for the permission's resource type.
 * RAM policy templates only support `Effect: "Allow"` with `Action` and an
 * optional `Condition`; the `Principal` and `Resource` are supplied by the
 * resource share at association time.
 */
export interface PermissionPolicyTemplate {
  /**
   * Actions granted to principals the resource share is shared with. Must be
   * a subset of the actions RAM supports for the permission's `resourceType`
   * (for example `appsync:SourceGraphQL` for `appsync:Apis`).
   */
  actions: string[];

  /**
   * Optional IAM condition block constraining when the actions are granted.
   */
  condition?: Record<string, unknown>;
}

export interface PermissionProps {
  /**
   * Name of the customer managed permission. Must be unique within your
   * account and Region. If omitted, Alchemy generates a deterministic name
   * from the stack, stage, and logical ID. Max 36 characters.
   * Changing the name replaces the permission.
   */
  permissionName?: string;

  /**
   * The resource type this permission applies to, in `service:Type` format —
   * for example `appsync:Apis`. Only some resource types support customer
   * managed permissions (others, like `ec2:Subnet`, only allow the AWS
   * managed default permission).
   * Changing the resource type replaces the permission.
   */
  resourceType: string;

  /**
   * The policy template granted by resource shares using this permission.
   * Changing the template creates a new permission version and promotes it
   * to the default; the previous default version is deleted when it is no
   * longer attached to any resource share.
   */
  policyTemplate: PermissionPolicyTemplate;

  /**
   * Tags applied to the permission.
   */
  tags?: Record<string, string>;
}

export interface Permission extends Resource<
  "AWS.RAM.Permission",
  PermissionProps,
  {
    /** ARN of the customer managed permission. */
    permissionArn: string;
    /** Name of the permission. */
    name: string;
    /** The resource type the permission applies to. */
    resourceType: string;
    /** The default version number of the permission. */
    version: string | undefined;
    /** Current status (`ATTACHABLE`, `UNATTACHABLE`, `DELETING`, ...). */
    status: string | undefined;
    /** Tags applied to the permission. */
    tags: Record<string, string>;
  },
  never,
  Providers
> {}

/**
 * An AWS Resource Access Manager (RAM) customer managed permission.
 *
 * A customer managed permission precisely controls which actions principals
 * receive on resources of a given type when you attach the permission to a
 * {@link ResourceShare} via `permissionArns`.
 *
 * ### Creating a Permission
 * **Example:** Least-privilege AppSync API sharing
 * ```typescript
 * const permission = yield* Permission("SourceGraphQLOnly", {
 *   resourceType: "appsync:Apis",
 *   policyTemplate: {
 *     actions: ["appsync:SourceGraphQL"],
 *   },
 * });
 * ```
 *
 * **Example:** Attach a permission to a resource share
 * ```typescript
 * const share = yield* ResourceShare("ApiShare", {
 *   resourceArns: [api.apiArn],
 *   principals: ["123456789012"],
 *   permissionArns: [permission.permissionArn],
 * });
 * ```
 *
 * ### Updating the Policy
 * **Example:** Add an action (creates a new default version)
 * ```typescript
 * const permission = yield* Permission("SourceGraphQLOnly", {
 *   resourceType: "appsync:Apis",
 *   policyTemplate: {
 *     actions: ["appsync:SourceGraphQL", "appsync:GraphQL"],
 *   },
 * });
 * ```
 *
 * @resource
 */
export const Permission = Resource<Permission>("AWS.RAM.Permission");

const toName = (id: string, props: { permissionName?: string } = {}) =>
  props.permissionName
    ? Effect.succeed(props.permissionName)
    : createPhysicalName({ id, maxLength: 36 });

/** RAM's inline `{ key, value }` tag list → a plain `Record`. */
const tagsToRecord = (tags: readonly ram.Tag[] | undefined): Record<string, string> => {
  const record: Record<string, string> = {};
  for (const tag of tags ?? []) {
    if (tag.key !== undefined && tag.value !== undefined) {
      record[tag.key] = tag.value;
    }
  }
  return record;
};

/** A permission is "live" only while it is not deleting/deleted. */
const isLive = (status: string | undefined): boolean =>
  status !== "DELETING" && status !== "DELETED";

/** Serialize the declared policy template to RAM's JSON wire format. */
const renderPolicyTemplate = (template: PermissionPolicyTemplate): string =>
  JSON.stringify({
    Effect: "Allow",
    Action: [...template.actions].sort(),
    ...(template.condition ? { Condition: template.condition } : {}),
  });

/** Parse an observed policy document into a comparable canonical string. */
const canonicalizePolicy = (policy: string | undefined): string => {
  if (policy === undefined) return "";
  try {
    const parsed = JSON.parse(policy) as {
      Effect?: string;
      Action?: string | string[];
      Condition?: Record<string, unknown>;
    };
    const actions = typeof parsed.Action === "string" ? [parsed.Action] : (parsed.Action ?? []);
    return JSON.stringify({
      Effect: parsed.Effect ?? "Allow",
      Action: [...actions].sort(),
      ...(parsed.Condition ? { Condition: parsed.Condition } : {}),
    });
  } catch {
    return policy;
  }
};

const toAttrs = (
  permission: ram.ResourceSharePermissionSummary | ram.ResourceSharePermissionDetail,
): Permission["Attributes"] => ({
  permissionArn: permission.arn!,
  name: permission.name!,
  resourceType: permission.resourceType!,
  version: permission.version,
  status: permission.status,
  tags: tagsToRecord(permission.tags),
});

/** Read the default version of a permission by ARN; undefined if missing. */
const readDetail = Effect.fn(function* (arn: string) {
  const detail = yield* ram.getPermission({ permissionArn: arn }).pipe(
    Effect.map((r) => r.permission),
    Effect.catchTag("UnknownResourceException", () => Effect.undefined),
  );
  return detail && isLive(detail.status) ? detail : undefined;
});

/** Find a live customer managed permission owned by us with the given name. */
const readByName = Effect.fn(function* (name: string) {
  const permissions = yield* ram.listPermissions.pages({ permissionType: "CUSTOMER_MANAGED" }).pipe(
    Stream.runCollect,
    Effect.map((chunk) => Array.fromIterable(chunk).flatMap((page) => page.permissions ?? [])),
  );
  const summary = permissions.find((p) => p.name === name && isLive(p.status));
  return summary?.arn ? yield* readDetail(summary.arn) : undefined;
});

export const PermissionProvider = () =>
  Provider.effect(
    Permission,
    Effect.gen(function* () {
      return {
        stables: ["permissionArn"],
        diff: Effect.fn(function* ({ news, olds }) {
          if (!isResolved(news)) return;
          // Name and resource type are fixed at creation (RAM has no
          // rename/retype API for permissions).
          if (olds !== undefined) {
            if (news.permissionName !== olds.permissionName) {
              return { action: "replace" } as const;
            }
            if (news.resourceType !== olds.resourceType) {
              return { action: "replace" } as const;
            }
          }
        }),
        list: () =>
          ram.listPermissions.pages({ permissionType: "CUSTOMER_MANAGED" }).pipe(
            Stream.runCollect,
            Effect.map((chunk) =>
              Array.fromIterable(chunk)
                .flatMap((page) => page.permissions ?? [])
                .filter((p) => isLive(p.status) && p.arn !== undefined && p.name !== undefined)
                .map(toAttrs),
            ),
          ),
        read: Effect.fn(function* ({ id, olds, output }) {
          const detail = output?.permissionArn
            ? yield* readDetail(output.permissionArn)
            : yield* readByName(yield* toName(id, olds ?? {}));
          if (!detail) return undefined;
          const state = toAttrs(detail);
          return (yield* hasAlchemyTags(id, state.tags)) ? state : Unowned(state);
        }),
        reconcile: Effect.fn(function* ({ id, news, output, session }) {
          const name = yield* toName(id, news);
          const internalTags = yield* createInternalTags(id);
          const desiredTags = { ...news.tags, ...internalTags };
          const desiredPolicy = renderPolicyTemplate(news.policyTemplate);

          // 1. OBSERVE — output ARN is only a cache; re-read live state.
          let detail = output?.permissionArn
            ? yield* readDetail(output.permissionArn)
            : yield* readByName(name);

          // 2. ENSURE — create if missing. PermissionAlreadyExists is a
          //    race with a concurrent create; fall through to observation.
          if (!detail) {
            const created = yield* ram
              .createPermission({
                name,
                resourceType: news.resourceType,
                policyTemplate: desiredPolicy,
                tags: Object.entries(desiredTags).map(([key, value]) => ({
                  key,
                  value,
                })),
              })
              .pipe(
                Effect.map((r) => r.permission),
                Effect.catchTag("PermissionAlreadyExistsException", () => Effect.undefined),
              );
            // Prefer the ARN from the create response; on the AlreadyExists
            // race fall back to the (briefly eventually consistent) list.
            detail = created?.arn ? yield* readDetail(created.arn) : yield* readByName(name);
            if (!detail?.arn) {
              if (created?.arn) {
                yield* session.note(created.arn);
                return { ...toAttrs(created), tags: desiredTags };
              }
              return yield* new RAMPermissionUnexpectedResponse({
                message: `permission '${name}' not found after create`,
              });
            }
            yield* session.note(detail.arn);
            return toAttrs(detail);
          }

          const arn = detail.arn!;
          const previousVersion = detail.version;

          // 3a. SYNC policy — diff the observed default version's policy
          //     against the desired template; publish a new default version
          //     on drift, then drop the superseded version (RAM caps a
          //     permission at 5 versions).
          if (canonicalizePolicy(detail.permission) !== desiredPolicy) {
            // createPermissionVersion automatically becomes the default.
            yield* ram.createPermissionVersion({
              permissionArn: arn,
              policyTemplate: desiredPolicy,
            });
            if (previousVersion !== undefined) {
              // The old version may still be attached to an existing share;
              // that's fine — leave it and converge on a later reconcile.
              yield* ram
                .deletePermissionVersion({
                  permissionArn: arn,
                  permissionVersion: Number(previousVersion),
                })
                .pipe(
                  Effect.catchTag(
                    ["OperationNotPermittedException", "InvalidParameterException"],
                    () => Effect.void,
                  ),
                );
            }
          }

          // 3b. SYNC tags — diff against observed cloud tags.
          const { upsert, removed } = diffTags(tagsToRecord(detail.tags), desiredTags);
          if (upsert.length > 0) {
            yield* ram.tagResource({
              resourceArn: arn,
              tags: upsert.map((t) => ({ key: t.Key, value: t.Value })),
            });
          }
          if (removed.length > 0) {
            yield* ram.untagResource({ resourceArn: arn, tagKeys: removed });
          }

          // 4. RETURN fresh state.
          const updated = yield* readDetail(arn);
          yield* session.note(arn);
          return updated ? toAttrs(updated) : { ...toAttrs(detail), tags: desiredTags };
        }),
        delete: Effect.fn(function* ({ output }) {
          // A permission cannot be deleted while attached to a resource
          // share; shares delete asynchronously, so retry briefly on
          // OperationNotPermitted before giving up.
          yield* ram.deletePermission({ permissionArn: output.permissionArn }).pipe(
            Effect.retry({
              while: (e): boolean => e._tag === "OperationNotPermittedException",
              schedule: Schedule.exponential("2 seconds"),
              times: 8,
            }),
            Effect.catchTag("UnknownResourceException", () => Effect.void),
          );
        }),
      };
    }),
  );