import * as s3control from "@distilled.cloud/aws/s3-control";
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 Schedule from "effect/Schedule";
import * as Stream from "effect/Stream";
import { AWSEnvironment, type AccountID } from "../Environment.ts";
import type { Providers } from "../Providers.ts";
import type { RegionID } from "../Region.ts";
/**
* Block-public-access settings for an access point. Unlike buckets, AWS
* defaults every flag to `true` for access points when the configuration is
* omitted at creation time.
*/
export interface AccessPointPublicAccessBlock {
/**
* Block new public ACLs and uploading public objects.
* @default true
*/
blockPublicAcls?: boolean;
/**
* Ignore all public ACLs on the access point.
* @default true
*/
ignorePublicAcls?: boolean;
/**
* Block new access point policies that grant public access.
* @default true
*/
blockPublicPolicy?: boolean;
/**
* Restrict access granted by public policies to AWS principals.
* @default true
*/
restrictPublicBuckets?: boolean;
}
export interface AccessPointProps {
/**
* Name of the access point (3-50 characters, lowercase letters, numbers
* and hyphens). If omitted, a unique name is generated from the app,
* stage and logical ID.
*
* Changing the name replaces the access point.
* @default ${app}-${stage}-${id}
*/
accessPointName?: string;
/**
* Name of the S3 bucket the access point is attached to.
*
* Changing the bucket replaces the access point.
*/
bucket: string;
/**
* AWS account ID that owns the bucket, when the bucket is in a
* different account than the access point.
*
* Changing the bucket account replaces the access point.
*/
bucketAccountId?: string;
/**
* Restrict the access point to a VPC. When set, only requests from the
* given VPC can reach the access point (`NetworkOrigin: VPC`); when
* omitted the access point accepts requests from the internet
* (`NetworkOrigin: Internet`).
*
* Changing the VPC configuration replaces the access point.
*/
vpcConfiguration?: {
/** ID of the VPC the access point is restricted to. */
vpcId: string;
};
/**
* Block-public-access settings. AWS defaults every flag to `true` for
* access points when omitted.
*
* Changing these settings replaces the access point (they are
* create-only on access points).
*/
publicAccessBlock?: AccessPointPublicAccessBlock;
/**
* Tags to apply to the access point. Merged with internal Alchemy tags.
*/
tags?: Record<string, string>;
}
export interface AccessPoint extends Resource<
"AWS.S3Control.AccessPoint",
AccessPointProps,
{
/**
* Name of the access point.
*/
accessPointName: string;
/**
* ARN of the access point.
*/
accessPointArn: string;
/**
* The S3-assigned alias of the access point. The alias can be used
* anywhere a bucket name is accepted (e.g. `GetObject`).
*/
alias: string | undefined;
/**
* Name of the bucket the access point is attached to.
*/
bucket: string;
/**
* Whether the access point allows access from the public internet
* (`Internet`) or only from a VPC (`VPC`).
*/
networkOrigin: s3control.NetworkOrigin;
/**
* AWS region of the access point.
*/
region: RegionID;
/**
* AWS account ID that owns the access point.
*/
accountId: AccountID;
},
never,
Providers
> {}
/**
* An Amazon S3 Access Point — a named network endpoint attached to a bucket
* with its own policy, public-access-block settings, and optional VPC
* restriction. Use access points to manage shared-dataset access at scale
* instead of maintaining one giant bucket policy.
* ### Creating Access Points
* **Example:** Internet access point on a bucket
* ```typescript
* import * as S3 from "@alchemy.run/aws/S3";
* import * as S3Control from "@alchemy.run/aws/S3Control";
*
* const bucket = yield* S3.Bucket("data", {});
* const accessPoint = yield* S3Control.AccessPoint("data-ap", {
* bucket: bucket.bucketName,
* });
* ```
*
* **Example:** VPC-only access point
* ```typescript
* const accessPoint = yield* S3Control.AccessPoint("internal-ap", {
* bucket: bucket.bucketName,
* vpcConfiguration: { vpcId: vpc.vpcId },
* });
* ```
*
* **Example:** Access point with explicit public-access-block
* ```typescript
* const accessPoint = yield* S3Control.AccessPoint("locked-ap", {
* bucket: bucket.bucketName,
* publicAccessBlock: {
* blockPublicAcls: true,
* ignorePublicAcls: true,
* blockPublicPolicy: true,
* restrictPublicBuckets: true,
* },
* tags: { team: "data" },
* });
* ```
*
* ### Granting Access
* **Example:** Attach a policy to the access point
* ```typescript
* yield* S3Control.AccessPointPolicy("data-ap-policy", {
* accessPointName: accessPoint.accessPointName,
* policy: {
* Version: "2012-10-17",
* Statement: [
* {
* Effect: "Allow",
* Principal: { AWS: `arn:aws:iam::${accountId}:role/reader` },
* Action: ["s3:GetObject"],
* Resource: [Output.interpolate`${accessPoint.accessPointArn}/object/*`],
* },
* ],
* },
* });
* ```
*
* @resource
*/
export const AccessPoint = Resource<AccessPoint>("AWS.S3Control.AccessPoint");
/**
* Retry while the freshly-created access point has not propagated yet.
* `TagResource`/`ListTagsForResource` (and occasionally `GetAccessPoint`)
* return `NoSuchAccessPoint` for a few seconds after `CreateAccessPoint`
* succeeds.
*
* Explicitly typed at module scope — inlining `Effect.retry` in a lifecycle
* op leaks `Retry.Return`'s conditional type into declaration emit, widening
* the provider layer to `unknown` and poisoning `AWS.providers()`.
*/
const retryWhileAccessPointPropagates = <A, E extends { _tag: string }, R>(
self: Effect.Effect<A, E, R>,
): Effect.Effect<A, E, R> =>
Effect.retry(self, {
while: (e) => e._tag === "NoSuchAccessPoint",
schedule: Schedule.max([Schedule.fixed("1 second"), Schedule.recurs(10)]),
});
/**
* Marker error for the delete verification loop: the access point is still
* observable after `DeleteAccessPoint` reported success (or a spurious
* `NoSuchAccessPoint`). The same control-plane propagation lag that makes
* `GetAccessPoint`/`TagResource` 404 for a few seconds after create can make
* `DeleteAccessPoint` 404 for a freshly-created access point WITHOUT deleting
* it — swallowing that 404 as "already gone" orphans the access point (and
* poisons the owning bucket's delete with `BucketHasAccessPointsAttached`).
*/
class AccessPointNotYetDeleted extends Data.TaggedError("AccessPointNotYetDeleted")<{
readonly resourceName: string;
}> {}
/**
* Retry while the access point is still observable after a delete attempt.
* Explicitly typed at module scope for the same declaration-emit reason as
* {@link retryWhileAccessPointPropagates}.
*/
const retryWhileAccessPointNotYetDeleted = <A, E extends { _tag: string }, R>(
self: Effect.Effect<A, E, R>,
): Effect.Effect<A, E, R> =>
Effect.retry(self, {
while: (e) => e._tag === "AccessPointNotYetDeleted",
schedule: Schedule.max([Schedule.exponential(500), Schedule.recurs(6)]),
});
export const AccessPointProvider = () =>
Provider.effect(
AccessPoint,
Effect.gen(function* () {
const createName = Effect.fn(function* (
id: string,
props: Pick<AccessPointProps, "accessPointName">,
) {
// Access point names: 3-50 chars, lowercase letters/numbers/hyphens.
return (
props.accessPointName ??
(yield* createPhysicalName({ id, maxLength: 50, lowercase: true }))
);
});
const accessPointArn = (region: string, accountId: string, name: string) =>
`arn:aws:s3:${region}:${accountId}:accesspoint/${name}`;
const observeAccessPoint = (accountId: string, name: string) =>
s3control
.getAccessPoint({ AccountId: accountId, Name: name })
.pipe(Effect.catchTag("NoSuchAccessPoint", () => Effect.undefined));
const observedTags = (accountId: string, arn: string) =>
s3control.listTagsForResource({ AccountId: accountId, ResourceArn: arn }).pipe(
Effect.map((r) => Object.fromEntries((r.Tags ?? []).map((t) => [t.Key, t.Value]))),
Effect.catchTag("NoSuchAccessPoint", () => Effect.succeed({} as Record<string, string>)),
);
const toAttrs = (
name: string,
live: s3control.GetAccessPointResult,
region: RegionID,
accountId: AccountID,
) => ({
accessPointName: name,
accessPointArn: live.AccessPointArn ?? accessPointArn(region, accountId, name),
alias: live.Alias,
bucket: live.Bucket ?? "",
networkOrigin: live.NetworkOrigin ?? "Internet",
region,
accountId,
});
// Public-access-block flags default to `true` on access points.
const canonPab = (pab: AccessPointPublicAccessBlock | undefined) =>
JSON.stringify({
a: pab?.blockPublicAcls ?? true,
i: pab?.ignorePublicAcls ?? true,
p: pab?.blockPublicPolicy ?? true,
r: pab?.restrictPublicBuckets ?? true,
});
return AccessPoint.Provider.of({
stables: [
"accessPointName",
"accessPointArn",
"alias",
"bucket",
"networkOrigin",
"region",
"accountId",
],
list: () =>
Effect.gen(function* () {
const { accountId, region } = yield* AWSEnvironment.current;
const pages = yield* s3control.listAccessPoints
.pages({ AccountId: accountId })
.pipe(Stream.runCollect);
return Array.from(pages).flatMap((page) =>
(page.AccessPointList ?? []).map((ap) => ({
accessPointName: ap.Name,
accessPointArn: ap.AccessPointArn ?? accessPointArn(region, accountId, ap.Name),
alias: ap.Alias,
bucket: ap.Bucket,
networkOrigin: ap.NetworkOrigin,
region,
accountId,
})),
);
}),
read: Effect.fn(function* ({ id, olds, output }) {
const { accountId, region } = yield* AWSEnvironment.current;
const name = output?.accessPointName ?? (yield* createName(id, olds ?? {}));
const live = yield* observeAccessPoint(accountId, name);
if (live === undefined) return undefined;
const attrs = toAttrs(name, live, region, accountId);
const tags = yield* observedTags(accountId, attrs.accessPointArn);
return (yield* hasAlchemyTags(id, tags)) ? attrs : Unowned(attrs);
}),
diff: Effect.fn(function* ({ id, news, olds }) {
if (!isResolved(news)) return undefined;
const oldProps = olds ?? ({} as AccessPointProps);
const oldName = yield* createName(id, oldProps);
const newName = yield* createName(id, news);
if (
oldName !== newName ||
oldProps.bucket !== news.bucket ||
(oldProps.bucketAccountId ?? undefined) !== (news.bucketAccountId ?? undefined) ||
(oldProps.vpcConfiguration?.vpcId ?? undefined) !==
(news.vpcConfiguration?.vpcId ?? undefined) ||
canonPab(oldProps.publicAccessBlock) !== canonPab(news.publicAccessBlock)
) {
// Everything except tags is create-only on an access point.
return { action: "replace" } as const;
}
// fall through: engine default update path (tags)
}),
reconcile: Effect.fn(function* ({ id, news, output, session }) {
const { accountId, region } = yield* AWSEnvironment.current;
const name = output?.accessPointName ?? (yield* createName(id, news));
// 1. OBSERVE — cloud state is authoritative.
let live = yield* observeAccessPoint(accountId, name);
// 2. ENSURE — create when missing; a concurrent create surfaces as
// the typed AccessPointAlreadyOwnedByYou tag (treated as a race)
// and a freshly-created access point can 404 for a few seconds.
if (live === undefined) {
yield* s3control
.createAccessPoint({
AccountId: accountId,
Name: name,
Bucket: news.bucket,
BucketAccountId: news.bucketAccountId,
VpcConfiguration: news.vpcConfiguration
? { VpcId: news.vpcConfiguration.vpcId }
: undefined,
PublicAccessBlockConfiguration: news.publicAccessBlock
? {
BlockPublicAcls: news.publicAccessBlock.blockPublicAcls,
IgnorePublicAcls: news.publicAccessBlock.ignorePublicAcls,
BlockPublicPolicy: news.publicAccessBlock.blockPublicPolicy,
RestrictPublicBuckets: news.publicAccessBlock.restrictPublicBuckets,
}
: undefined,
})
.pipe(Effect.catchTag("AccessPointAlreadyOwnedByYou", () => Effect.void));
live = yield* retryWhileAccessPointPropagates(
s3control.getAccessPoint({ AccountId: accountId, Name: name }),
);
}
const attrs = toAttrs(name, live, region, accountId);
// 3. SYNC TAGS — diff against OBSERVED cloud tags so adoption
// converges. Tagging a fresh access point can race propagation.
const internalTags = yield* createInternalTags(id);
const desiredTags = { ...news.tags, ...internalTags };
const currentTags = yield* observedTags(accountId, attrs.accessPointArn);
const { upsert, removed } = diffTags(currentTags, desiredTags);
if (upsert.length > 0) {
yield* retryWhileAccessPointPropagates(
s3control.tagResource({
AccountId: accountId,
ResourceArn: attrs.accessPointArn,
Tags: upsert,
}),
);
}
if (removed.length > 0) {
yield* s3control.untagResource({
AccountId: accountId,
ResourceArn: attrs.accessPointArn,
TagKeys: removed,
});
}
yield* session.note(name);
return attrs;
}),
delete: Effect.fn(function* ({ output }) {
const { accountId } = yield* AWSEnvironment.current;
const name = output.accessPointName;
const deleteOnce = s3control.deleteAccessPoint({ AccountId: accountId, Name: name }).pipe(
// Idempotent delete — already gone is success.
Effect.catchTag("NoSuchAccessPoint", () => Effect.void),
);
yield* deleteOnce;
// Verify the access point is actually gone. `DeleteAccessPoint`
// can spuriously return `NoSuchAccessPoint` for a freshly-created
// access point (control-plane propagation lag) without deleting
// it; treating that as success orphans the access point. While
// the access point is still observable, delete again — bounded,
// then fail loudly rather than silently leak.
yield* retryWhileAccessPointNotYetDeleted(
observeAccessPoint(accountId, name).pipe(
Effect.flatMap((live) =>
live === undefined
? Effect.void
: deleteOnce.pipe(
Effect.flatMap(() =>
Effect.fail(new AccessPointNotYetDeleted({ resourceName: name })),
),
),
),
),
);
}),
});
}),
);