The best way to control Claude Code, Codex and more from any computer or phone

main
ts 439 lines 16 KB
Raw
1 import * as s3control from "@distilled.cloud/aws/s3-control";
2 import { Unowned } from "alchemy/AdoptPolicy";
3 import { isResolved } from "alchemy/Diff";
4 import { createPhysicalName } from "alchemy/PhysicalName";
5 import * as Provider from "alchemy/Provider";
6 import { Resource } from "alchemy/Resource";
7 import { createInternalTags, diffTags, hasAlchemyTags } from "alchemy/Tags";
8 import * as Data from "effect/Data";
9 import * as Effect from "effect/Effect";
10 import * as Schedule from "effect/Schedule";
11 import * as Stream from "effect/Stream";
12 import { AWSEnvironment, type AccountID } from "../Environment.ts";
13 import type { Providers } from "../Providers.ts";
14 import type { RegionID } from "../Region.ts";
15
16 /**
17 * Block-public-access settings for an access point. Unlike buckets, AWS
18 * defaults every flag to `true` for access points when the configuration is
19 * omitted at creation time.
20 */
21 export interface AccessPointPublicAccessBlock {
22 /**
23 * Block new public ACLs and uploading public objects.
24 * @default true
25 */
26 blockPublicAcls?: boolean;
27 /**
28 * Ignore all public ACLs on the access point.
29 * @default true
30 */
31 ignorePublicAcls?: boolean;
32 /**
33 * Block new access point policies that grant public access.
34 * @default true
35 */
36 blockPublicPolicy?: boolean;
37 /**
38 * Restrict access granted by public policies to AWS principals.
39 * @default true
40 */
41 restrictPublicBuckets?: boolean;
42 }
43
44 export interface AccessPointProps {
45 /**
46 * Name of the access point (3-50 characters, lowercase letters, numbers
47 * and hyphens). If omitted, a unique name is generated from the app,
48 * stage and logical ID.
49 *
50 * Changing the name replaces the access point.
51 * @default ${app}-${stage}-${id}
52 */
53 accessPointName?: string;
54 /**
55 * Name of the S3 bucket the access point is attached to.
56 *
57 * Changing the bucket replaces the access point.
58 */
59 bucket: string;
60 /**
61 * AWS account ID that owns the bucket, when the bucket is in a
62 * different account than the access point.
63 *
64 * Changing the bucket account replaces the access point.
65 */
66 bucketAccountId?: string;
67 /**
68 * Restrict the access point to a VPC. When set, only requests from the
69 * given VPC can reach the access point (`NetworkOrigin: VPC`); when
70 * omitted the access point accepts requests from the internet
71 * (`NetworkOrigin: Internet`).
72 *
73 * Changing the VPC configuration replaces the access point.
74 */
75 vpcConfiguration?: {
76 /** ID of the VPC the access point is restricted to. */
77 vpcId: string;
78 };
79 /**
80 * Block-public-access settings. AWS defaults every flag to `true` for
81 * access points when omitted.
82 *
83 * Changing these settings replaces the access point (they are
84 * create-only on access points).
85 */
86 publicAccessBlock?: AccessPointPublicAccessBlock;
87 /**
88 * Tags to apply to the access point. Merged with internal Alchemy tags.
89 */
90 tags?: Record<string, string>;
91 }
92
93 export interface AccessPoint extends Resource<
94 "AWS.S3Control.AccessPoint",
95 AccessPointProps,
96 {
97 /**
98 * Name of the access point.
99 */
100 accessPointName: string;
101 /**
102 * ARN of the access point.
103 */
104 accessPointArn: string;
105 /**
106 * The S3-assigned alias of the access point. The alias can be used
107 * anywhere a bucket name is accepted (e.g. `GetObject`).
108 */
109 alias: string | undefined;
110 /**
111 * Name of the bucket the access point is attached to.
112 */
113 bucket: string;
114 /**
115 * Whether the access point allows access from the public internet
116 * (`Internet`) or only from a VPC (`VPC`).
117 */
118 networkOrigin: s3control.NetworkOrigin;
119 /**
120 * AWS region of the access point.
121 */
122 region: RegionID;
123 /**
124 * AWS account ID that owns the access point.
125 */
126 accountId: AccountID;
127 },
128 never,
129 Providers
130 > {}
131
132 /**
133 * An Amazon S3 Access Point — a named network endpoint attached to a bucket
134 * with its own policy, public-access-block settings, and optional VPC
135 * restriction. Use access points to manage shared-dataset access at scale
136 * instead of maintaining one giant bucket policy.
137 * ### Creating Access Points
138 * **Example:** Internet access point on a bucket
139 * ```typescript
140 * import * as S3 from "@alchemy.run/aws/S3";
141 * import * as S3Control from "@alchemy.run/aws/S3Control";
142 *
143 * const bucket = yield* S3.Bucket("data", {});
144 * const accessPoint = yield* S3Control.AccessPoint("data-ap", {
145 * bucket: bucket.bucketName,
146 * });
147 * ```
148 *
149 * **Example:** VPC-only access point
150 * ```typescript
151 * const accessPoint = yield* S3Control.AccessPoint("internal-ap", {
152 * bucket: bucket.bucketName,
153 * vpcConfiguration: { vpcId: vpc.vpcId },
154 * });
155 * ```
156 *
157 * **Example:** Access point with explicit public-access-block
158 * ```typescript
159 * const accessPoint = yield* S3Control.AccessPoint("locked-ap", {
160 * bucket: bucket.bucketName,
161 * publicAccessBlock: {
162 * blockPublicAcls: true,
163 * ignorePublicAcls: true,
164 * blockPublicPolicy: true,
165 * restrictPublicBuckets: true,
166 * },
167 * tags: { team: "data" },
168 * });
169 * ```
170 *
171 * ### Granting Access
172 * **Example:** Attach a policy to the access point
173 * ```typescript
174 * yield* S3Control.AccessPointPolicy("data-ap-policy", {
175 * accessPointName: accessPoint.accessPointName,
176 * policy: {
177 * Version: "2012-10-17",
178 * Statement: [
179 * {
180 * Effect: "Allow",
181 * Principal: { AWS: `arn:aws:iam::${accountId}:role/reader` },
182 * Action: ["s3:GetObject"],
183 * Resource: [Output.interpolate`${accessPoint.accessPointArn}/object/*`],
184 * },
185 * ],
186 * },
187 * });
188 * ```
189 *
190 * @resource
191 */
192 export const AccessPoint = Resource<AccessPoint>("AWS.S3Control.AccessPoint");
193
194 /**
195 * Retry while the freshly-created access point has not propagated yet.
196 * `TagResource`/`ListTagsForResource` (and occasionally `GetAccessPoint`)
197 * return `NoSuchAccessPoint` for a few seconds after `CreateAccessPoint`
198 * succeeds.
199 *
200 * Explicitly typed at module scope — inlining `Effect.retry` in a lifecycle
201 * op leaks `Retry.Return`'s conditional type into declaration emit, widening
202 * the provider layer to `unknown` and poisoning `AWS.providers()`.
203 */
204 const retryWhileAccessPointPropagates = <A, E extends { _tag: string }, R>(
205 self: Effect.Effect<A, E, R>,
206 ): Effect.Effect<A, E, R> =>
207 Effect.retry(self, {
208 while: (e) => e._tag === "NoSuchAccessPoint",
209 schedule: Schedule.max([Schedule.fixed("1 second"), Schedule.recurs(10)]),
210 });
211
212 /**
213 * Marker error for the delete verification loop: the access point is still
214 * observable after `DeleteAccessPoint` reported success (or a spurious
215 * `NoSuchAccessPoint`). The same control-plane propagation lag that makes
216 * `GetAccessPoint`/`TagResource` 404 for a few seconds after create can make
217 * `DeleteAccessPoint` 404 for a freshly-created access point WITHOUT deleting
218 * it — swallowing that 404 as "already gone" orphans the access point (and
219 * poisons the owning bucket's delete with `BucketHasAccessPointsAttached`).
220 */
221 class AccessPointNotYetDeleted extends Data.TaggedError("AccessPointNotYetDeleted")<{
222 readonly resourceName: string;
223 }> {}
224
225 /**
226 * Retry while the access point is still observable after a delete attempt.
227 * Explicitly typed at module scope for the same declaration-emit reason as
228 * {@link retryWhileAccessPointPropagates}.
229 */
230 const retryWhileAccessPointNotYetDeleted = <A, E extends { _tag: string }, R>(
231 self: Effect.Effect<A, E, R>,
232 ): Effect.Effect<A, E, R> =>
233 Effect.retry(self, {
234 while: (e) => e._tag === "AccessPointNotYetDeleted",
235 schedule: Schedule.max([Schedule.exponential(500), Schedule.recurs(6)]),
236 });
237
238 export const AccessPointProvider = () =>
239 Provider.effect(
240 AccessPoint,
241 Effect.gen(function* () {
242 const createName = Effect.fn(function* (
243 id: string,
244 props: Pick<AccessPointProps, "accessPointName">,
245 ) {
246 // Access point names: 3-50 chars, lowercase letters/numbers/hyphens.
247 return (
248 props.accessPointName ??
249 (yield* createPhysicalName({ id, maxLength: 50, lowercase: true }))
250 );
251 });
252
253 const accessPointArn = (region: string, accountId: string, name: string) =>
254 `arn:aws:s3:${region}:${accountId}:accesspoint/${name}`;
255
256 const observeAccessPoint = (accountId: string, name: string) =>
257 s3control
258 .getAccessPoint({ AccountId: accountId, Name: name })
259 .pipe(Effect.catchTag("NoSuchAccessPoint", () => Effect.undefined));
260
261 const observedTags = (accountId: string, arn: string) =>
262 s3control.listTagsForResource({ AccountId: accountId, ResourceArn: arn }).pipe(
263 Effect.map((r) => Object.fromEntries((r.Tags ?? []).map((t) => [t.Key, t.Value]))),
264 Effect.catchTag("NoSuchAccessPoint", () => Effect.succeed({} as Record<string, string>)),
265 );
266
267 const toAttrs = (
268 name: string,
269 live: s3control.GetAccessPointResult,
270 region: RegionID,
271 accountId: AccountID,
272 ) => ({
273 accessPointName: name,
274 accessPointArn: live.AccessPointArn ?? accessPointArn(region, accountId, name),
275 alias: live.Alias,
276 bucket: live.Bucket ?? "",
277 networkOrigin: live.NetworkOrigin ?? "Internet",
278 region,
279 accountId,
280 });
281
282 // Public-access-block flags default to `true` on access points.
283 const canonPab = (pab: AccessPointPublicAccessBlock | undefined) =>
284 JSON.stringify({
285 a: pab?.blockPublicAcls ?? true,
286 i: pab?.ignorePublicAcls ?? true,
287 p: pab?.blockPublicPolicy ?? true,
288 r: pab?.restrictPublicBuckets ?? true,
289 });
290
291 return AccessPoint.Provider.of({
292 stables: [
293 "accessPointName",
294 "accessPointArn",
295 "alias",
296 "bucket",
297 "networkOrigin",
298 "region",
299 "accountId",
300 ],
301 list: () =>
302 Effect.gen(function* () {
303 const { accountId, region } = yield* AWSEnvironment.current;
304 const pages = yield* s3control.listAccessPoints
305 .pages({ AccountId: accountId })
306 .pipe(Stream.runCollect);
307 return Array.from(pages).flatMap((page) =>
308 (page.AccessPointList ?? []).map((ap) => ({
309 accessPointName: ap.Name,
310 accessPointArn: ap.AccessPointArn ?? accessPointArn(region, accountId, ap.Name),
311 alias: ap.Alias,
312 bucket: ap.Bucket,
313 networkOrigin: ap.NetworkOrigin,
314 region,
315 accountId,
316 })),
317 );
318 }),
319 read: Effect.fn(function* ({ id, olds, output }) {
320 const { accountId, region } = yield* AWSEnvironment.current;
321 const name = output?.accessPointName ?? (yield* createName(id, olds ?? {}));
322 const live = yield* observeAccessPoint(accountId, name);
323 if (live === undefined) return undefined;
324 const attrs = toAttrs(name, live, region, accountId);
325 const tags = yield* observedTags(accountId, attrs.accessPointArn);
326 return (yield* hasAlchemyTags(id, tags)) ? attrs : Unowned(attrs);
327 }),
328 diff: Effect.fn(function* ({ id, news, olds }) {
329 if (!isResolved(news)) return undefined;
330 const oldProps = olds ?? ({} as AccessPointProps);
331 const oldName = yield* createName(id, oldProps);
332 const newName = yield* createName(id, news);
333 if (
334 oldName !== newName ||
335 oldProps.bucket !== news.bucket ||
336 (oldProps.bucketAccountId ?? undefined) !== (news.bucketAccountId ?? undefined) ||
337 (oldProps.vpcConfiguration?.vpcId ?? undefined) !==
338 (news.vpcConfiguration?.vpcId ?? undefined) ||
339 canonPab(oldProps.publicAccessBlock) !== canonPab(news.publicAccessBlock)
340 ) {
341 // Everything except tags is create-only on an access point.
342 return { action: "replace" } as const;
343 }
344 // fall through: engine default update path (tags)
345 }),
346 reconcile: Effect.fn(function* ({ id, news, output, session }) {
347 const { accountId, region } = yield* AWSEnvironment.current;
348 const name = output?.accessPointName ?? (yield* createName(id, news));
349
350 // 1. OBSERVE — cloud state is authoritative.
351 let live = yield* observeAccessPoint(accountId, name);
352
353 // 2. ENSURE — create when missing; a concurrent create surfaces as
354 // the typed AccessPointAlreadyOwnedByYou tag (treated as a race)
355 // and a freshly-created access point can 404 for a few seconds.
356 if (live === undefined) {
357 yield* s3control
358 .createAccessPoint({
359 AccountId: accountId,
360 Name: name,
361 Bucket: news.bucket,
362 BucketAccountId: news.bucketAccountId,
363 VpcConfiguration: news.vpcConfiguration
364 ? { VpcId: news.vpcConfiguration.vpcId }
365 : undefined,
366 PublicAccessBlockConfiguration: news.publicAccessBlock
367 ? {
368 BlockPublicAcls: news.publicAccessBlock.blockPublicAcls,
369 IgnorePublicAcls: news.publicAccessBlock.ignorePublicAcls,
370 BlockPublicPolicy: news.publicAccessBlock.blockPublicPolicy,
371 RestrictPublicBuckets: news.publicAccessBlock.restrictPublicBuckets,
372 }
373 : undefined,
374 })
375 .pipe(Effect.catchTag("AccessPointAlreadyOwnedByYou", () => Effect.void));
376 live = yield* retryWhileAccessPointPropagates(
377 s3control.getAccessPoint({ AccountId: accountId, Name: name }),
378 );
379 }
380
381 const attrs = toAttrs(name, live, region, accountId);
382
383 // 3. SYNC TAGS — diff against OBSERVED cloud tags so adoption
384 // converges. Tagging a fresh access point can race propagation.
385 const internalTags = yield* createInternalTags(id);
386 const desiredTags = { ...news.tags, ...internalTags };
387 const currentTags = yield* observedTags(accountId, attrs.accessPointArn);
388 const { upsert, removed } = diffTags(currentTags, desiredTags);
389 if (upsert.length > 0) {
390 yield* retryWhileAccessPointPropagates(
391 s3control.tagResource({
392 AccountId: accountId,
393 ResourceArn: attrs.accessPointArn,
394 Tags: upsert,
395 }),
396 );
397 }
398 if (removed.length > 0) {
399 yield* s3control.untagResource({
400 AccountId: accountId,
401 ResourceArn: attrs.accessPointArn,
402 TagKeys: removed,
403 });
404 }
405
406 yield* session.note(name);
407 return attrs;
408 }),
409 delete: Effect.fn(function* ({ output }) {
410 const { accountId } = yield* AWSEnvironment.current;
411 const name = output.accessPointName;
412 const deleteOnce = s3control.deleteAccessPoint({ AccountId: accountId, Name: name }).pipe(
413 // Idempotent delete — already gone is success.
414 Effect.catchTag("NoSuchAccessPoint", () => Effect.void),
415 );
416 yield* deleteOnce;
417 // Verify the access point is actually gone. `DeleteAccessPoint`
418 // can spuriously return `NoSuchAccessPoint` for a freshly-created
419 // access point (control-plane propagation lag) without deleting
420 // it; treating that as success orphans the access point. While
421 // the access point is still observable, delete again — bounded,
422 // then fail loudly rather than silently leak.
423 yield* retryWhileAccessPointNotYetDeleted(
424 observeAccessPoint(accountId, name).pipe(
425 Effect.flatMap((live) =>
426 live === undefined
427 ? Effect.void
428 : deleteOnce.pipe(
429 Effect.flatMap(() =>
430 Effect.fail(new AccessPointNotYetDeleted({ resourceName: name })),
431 ),
432 ),
433 ),
434 ),
435 );
436 }),
437 });
438 }),
439 );