sailfork / t3code-github / .repos/ alchemy-effect/ packages/ aws/ src/ VerifiedPermissions/ Policy.ts

import * as avp from "@distilled.cloud/aws/verifiedpermissions";
import { isResolved } from "alchemy/Diff";
import * as Provider from "alchemy/Provider";
import { Resource } from "alchemy/Resource";
import * as Data from "effect/Data";
import * as Effect from "effect/Effect";
import type { Providers } from "../Providers.ts";

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

/**
 * Identifies a Cedar entity, e.g.
 * `{ entityType: "PhotoApp::User", entityId: "alice" }`.
 */
export interface EntityIdentifier {
  /** The Cedar entity type, e.g. `PhotoApp::User`. */
  entityType: string;
  /** The entity ID, e.g. `alice`. */
  entityId: string;
}

export interface PolicyProps {
  /**
   * The ID of the policy store the policy belongs to. Changing the store
   * replaces the policy.
   */
  policyStoreId: string;
  /**
   * The Cedar policy statement for a **static** policy, e.g.
   * `permit(principal, action == Action::"view", resource);`. Mutable —
   * updating re-submits the statement via `UpdatePolicy` (only annotations
   * and conditions may change; the principal/resource scope is fixed).
   *
   * Exactly one of `statement` (static) or `templateId` (template-linked)
   * must be provided.
   */
  statement?: string;
  /**
   * An optional description stored alongside a static policy statement.
   */
  description?: string;
  /**
   * The ID of a {@link PolicyTemplate} to instantiate as a
   * **template-linked** policy. Template-linked policies cannot be updated
   * in place — changing `templateId`, `principal`, or `resource` replaces
   * the policy (the template itself is the mutable part).
   */
  templateId?: string;
  /**
   * The principal to fill into the template's `?principal` placeholder.
   * Only valid with `templateId`.
   */
  principal?: EntityIdentifier;
  /**
   * The resource to fill into the template's `?resource` placeholder.
   * Only valid with `templateId`.
   */
  resource?: EntityIdentifier;
}

export interface Policy extends Resource<
  "AWS.VerifiedPermissions.Policy",
  PolicyProps,
  {
    /**
     * ID of the policy store the policy belongs to.
     */
    policyStoreId: string;
    /**
     * Service-assigned unique ID of the policy within the store.
     */
    policyId: string;
  },
  {},
  Providers
> {}

/**
 * A static Cedar policy in a Verified Permissions policy store. Static
 * policies contain a complete Cedar statement and are evaluated for every
 * matching authorization request.
 * ### Creating Policies
 * **Example:** Permit a Specific Principal
 * ```typescript
 * import * as AWS from "@alchemy.run/aws";
 *
 * const store = yield* AWS.VerifiedPermissions.PolicyStore("Store", {});
 *
 * yield* AWS.VerifiedPermissions.Policy("AllowAlice", {
 *   policyStoreId: store.policyStoreId,
 *   statement: `permit(
 *     principal == PhotoApp::User::"alice",
 *     action == PhotoApp::Action::"viewPhoto",
 *     resource
 *   );`,
 *   description: "Alice can view any photo",
 * });
 * ```
 *
 * ### Template-Linked Policies
 * **Example:** Instantiate a Policy Template for a Principal
 * ```typescript
 * const template = yield* AWS.VerifiedPermissions.PolicyTemplate("ViewPhoto", {
 *   policyStoreId: store.policyStoreId,
 *   statement: `permit(
 *     principal == ?principal,
 *     action == PhotoApp::Action::"viewPhoto",
 *     resource
 *   );`,
 * });
 *
 * yield* AWS.VerifiedPermissions.Policy("AliceCanView", {
 *   policyStoreId: store.policyStoreId,
 *   templateId: template.policyTemplateId,
 *   principal: { entityType: "PhotoApp::User", entityId: "alice" },
 * });
 * ```
 *
 * @resource
 */
export const Policy = Resource<Policy>("AWS.VerifiedPermissions.Policy");

/** Desired props → the wire `PolicyDefinition` union. */
const toDefinition = (news: PolicyProps) =>
  Effect.gen(function* () {
    if (news.templateId !== undefined && news.statement !== undefined) {
      return yield* new VerifiedPermissionsPolicyInvalidProps({
        message:
          "a Policy accepts either `statement` (static) or `templateId` (template-linked), not both",
      });
    }
    if (news.templateId !== undefined) {
      return {
        templateLinked: {
          policyTemplateId: news.templateId,
          principal: news.principal,
          resource: news.resource,
        },
      } as const;
    }
    if (news.statement === undefined) {
      return yield* new VerifiedPermissionsPolicyInvalidProps({
        message: "a Policy requires either `statement` (static) or `templateId` (template-linked)",
      });
    }
    return {
      static: { statement: news.statement, description: news.description },
    } as const;
  });

export const PolicyProvider = () =>
  Provider.effect(
    Policy,
    Effect.gen(function* () {
      const observe = Effect.fn(function* (policyStoreId: string, policyId: string) {
        return yield* avp
          .getPolicy({ policyStoreId, policyId })
          .pipe(Effect.catchTag("ResourceNotFoundException", () => Effect.undefined));
      });

      return Policy.Provider.of({
        stables: ["policyStoreId", "policyId"],

        // child of a policy store — not enumerable account-wide
        list: () => Effect.succeed([]),

        read: Effect.fn(function* ({ olds, output }) {
          const policyStoreId = output?.policyStoreId ?? olds?.policyStoreId;
          const policyId = output?.policyId;
          if (policyStoreId === undefined || policyId === undefined) {
            return undefined;
          }
          const policy = yield* observe(policyStoreId, policyId);
          if (policy === undefined) return undefined;
          return { policyStoreId, policyId: policy.policyId };
        }),

        diff: Effect.fn(function* ({ news, olds }) {
          if (!isResolved(news)) return undefined;
          if (olds.policyStoreId !== news.policyStoreId) {
            return { action: "replace" } as const;
          }
          // switching static <-> template-linked replaces; UpdatePolicy only
          // supports static definitions, and a template-linked policy's
          // template/principal/resource are fixed at creation
          if (
            (olds.templateId === undefined) !== (news.templateId === undefined) ||
            (news.templateId !== undefined &&
              (olds.templateId !== news.templateId ||
                olds.principal?.entityType !== news.principal?.entityType ||
                olds.principal?.entityId !== news.principal?.entityId ||
                olds.resource?.entityType !== news.resource?.entityType ||
                olds.resource?.entityId !== news.resource?.entityId))
          ) {
            return { action: "replace" } as const;
          }
          // static statement / description are mutable → default update path
        }),

        reconcile: Effect.fn(function* ({ news, output, session }) {
          const definition = yield* toDefinition(news);

          // 1. OBSERVE — cloud state is authoritative
          const existing =
            output?.policyId !== undefined
              ? yield* observe(news.policyStoreId, output.policyId)
              : undefined;

          // 2. ENSURE / SYNC
          let policyId: string;
          if (existing === undefined) {
            const created = yield* avp.createPolicy({
              policyStoreId: news.policyStoreId,
              definition,
            });
            policyId = created.policyId;
          } else if ("static" in definition && definition.static !== undefined) {
            const updated = yield* avp.updatePolicy({
              policyStoreId: news.policyStoreId,
              policyId: existing.policyId,
              definition: { static: definition.static },
            });
            policyId = updated.policyId;
          } else {
            // template-linked policies have no in-place update — diff replaces
            // on any change, so the observed policy is already converged
            policyId = existing.policyId;
          }

          yield* session.note(policyId);
          return { policyStoreId: news.policyStoreId, policyId };
        }),

        delete: Effect.fn(function* ({ output }) {
          yield* avp
            .deletePolicy({
              policyStoreId: output.policyStoreId,
              policyId: output.policyId,
            })
            .pipe(Effect.catchTag("ResourceNotFoundException", () => Effect.void));
        }),
      });
    }),
  );