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

main
ts 339 lines 12.8 KB
Raw
1 import * as securitylake from "@distilled.cloud/aws/securitylake";
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 Option from "effect/Option";
11 import * as Stream from "effect/Stream";
12 import type { Providers } from "../Providers.ts";
13 import { readSecurityLakeTags, retryWhileConflict, toTagList } from "./internal.ts";
14
15 /**
16 * The AWS identity (principal + external ID) that a subscriber authenticates
17 * with when consuming data from Security Lake.
18 */
19 export interface SubscriberIdentity {
20 /** The AWS principal (account ID or service principal) of the subscriber. */
21 principal: string;
22 /** The external ID the subscriber must present when assuming the role. */
23 externalId: string;
24 }
25
26 /**
27 * A log source a subscriber consumes — either a natively supported AWS source
28 * or a custom source.
29 */
30 export type SubscriberSource = securitylake.LogSourceResource;
31
32 /**
33 * How the subscriber accesses the data — direct S3 access or Lake Formation
34 * (query) access.
35 */
36 export type SubscriberAccessType = "LAKEFORMATION" | "S3";
37
38 export interface SubscriberProps {
39 /**
40 * Name of the subscriber. If omitted, a unique physical name is generated
41 * from the app, stage, and logical ID.
42 */
43 subscriberName?: string;
44
45 /**
46 * The AWS identity (principal + external ID) the subscriber uses to access
47 * Security Lake data.
48 */
49 subscriberIdentity: SubscriberIdentity;
50
51 /**
52 * Description of the subscriber.
53 */
54 subscriberDescription?: string;
55
56 /**
57 * The log sources the subscriber consumes, e.g.
58 * `[{ awsLogSource: { sourceName: "ROUTE53", sourceVersion: "2.0" } }]`.
59 */
60 sources: SubscriberSource[];
61
62 /**
63 * How the subscriber accesses the data. Changing this replaces the
64 * subscriber (access type is create-only).
65 * @default ["S3"]
66 */
67 accessTypes?: SubscriberAccessType[];
68
69 /**
70 * Tags applied to the subscriber. Alchemy ownership tags are merged in
71 * automatically.
72 */
73 tags?: Record<string, string>;
74 }
75
76 /** @resource */
77 export interface Subscriber extends Resource<
78 "AWS.SecurityLake.Subscriber",
79 SubscriberProps,
80 {
81 /** Unique ID of the subscriber (UUID). */
82 subscriberId: string;
83 /** ARN of the subscriber. */
84 subscriberArn: string;
85 /** Name of the subscriber. */
86 subscriberName: string;
87 /** Current status (`ACTIVE`, `PENDING`, `READY`, `DEACTIVATED`). */
88 subscriberStatus: string | undefined;
89 /** ARN of the IAM role created for the subscriber to assume. */
90 roleArn: string | undefined;
91 /** ARN of the S3 bucket the subscriber reads from. */
92 s3BucketArn: string | undefined;
93 /** The subscriber's notification endpoint, if one is configured. */
94 subscriberEndpoint: string | undefined;
95 /** ARN of the RAM resource share (Lake Formation access only). */
96 resourceShareArn: string | undefined;
97 /** Name of the RAM resource share (Lake Formation access only). */
98 resourceShareName: string | undefined;
99 },
100 never,
101 Providers
102 > {}
103
104 /**
105 * A Security Lake subscriber — a consumer (account or service) granted access
106 * to data in the Security Lake data lake for specific log sources.
107 *
108 * ### Creating a Subscriber
109 * **Example:** S3 data-access subscriber
110 * ```typescript
111 * const subscriber = yield* SecurityLake.Subscriber("Analytics", {
112 * subscriberIdentity: {
113 * principal: "123456789012",
114 * externalId: "analytics-external-id",
115 * },
116 * sources: [{ awsLogSource: { sourceName: "ROUTE53", sourceVersion: "2.0" } }],
117 * });
118 * ```
119 *
120 * **Example:** Lake Formation (query) access
121 * ```typescript
122 * const subscriber = yield* SecurityLake.Subscriber("Athena", {
123 * subscriberName: "athena-consumer",
124 * subscriberDescription: "Athena query access to VPC flow logs",
125 * subscriberIdentity: {
126 * principal: "123456789012",
127 * externalId: "athena-external-id",
128 * },
129 * sources: [{ awsLogSource: { sourceName: "VPC_FLOW", sourceVersion: "2.0" } }],
130 * accessTypes: ["LAKEFORMATION"],
131 * tags: { team: "security" },
132 * });
133 * ```
134 */
135 const SubscriberResource = Resource<Subscriber>("AWS.SecurityLake.Subscriber");
136
137 export { SubscriberResource as Subscriber };
138
139 /**
140 * `CreateSubscriber` returned without a subscriber body and the subscriber
141 * could not be re-observed by name.
142 */
143 export class SubscriberCreateFailed extends Data.TaggedError("SubscriberCreateFailed")<{
144 readonly subscriberName: string;
145 }> {}
146
147 const buildAttrs = (subscriber: securitylake.SubscriberResource) => ({
148 subscriberId: subscriber.subscriberId,
149 subscriberArn: subscriber.subscriberArn,
150 subscriberName: subscriber.subscriberName,
151 subscriberStatus: subscriber.subscriberStatus,
152 roleArn: subscriber.roleArn,
153 s3BucketArn: subscriber.s3BucketArn,
154 subscriberEndpoint: subscriber.subscriberEndpoint,
155 resourceShareArn: subscriber.resourceShareArn,
156 resourceShareName: subscriber.resourceShareName,
157 });
158
159 // Desired sources match observed sources when every desired entry appears in
160 // the observed list (AWS resolves an omitted sourceVersion, so it is only
161 // compared when the desired entry pins one) and the counts agree.
162 const sourcesMatch = (
163 desired: readonly securitylake.LogSourceResource[],
164 observed: readonly securitylake.LogSourceResource[],
165 ) =>
166 desired.length === observed.length &&
167 desired.every((want) => {
168 const wantAws = want.awsLogSource;
169 if (wantAws !== undefined) {
170 return observed.some((have) => {
171 const haveAws = have.awsLogSource;
172 return (
173 haveAws !== undefined &&
174 haveAws.sourceName === wantAws.sourceName &&
175 (wantAws.sourceVersion === undefined || haveAws.sourceVersion === wantAws.sourceVersion)
176 );
177 });
178 }
179 return observed.some(
180 (have) =>
181 have.customLogSource?.sourceName === want.customLogSource?.sourceName &&
182 (want.customLogSource?.sourceVersion === undefined ||
183 have.customLogSource?.sourceVersion === want.customLogSource.sourceVersion),
184 );
185 });
186
187 export const SubscriberProvider = () =>
188 Provider.effect(
189 SubscriberResource,
190 Effect.gen(function* () {
191 const createName = Effect.fn(function* (id: string, props: { subscriberName?: string }) {
192 return props.subscriberName ?? (yield* createPhysicalName({ id, maxLength: 64 }));
193 });
194
195 const getById = (subscriberId: string) =>
196 securitylake.getSubscriber({ subscriberId }).pipe(
197 Effect.map((response) => response.subscriber),
198 Effect.catchTag("ResourceNotFoundException", () => Effect.undefined),
199 );
200
201 // Subscriber names are unique per account/region — find the live
202 // subscriber carrying our deterministic name when state was lost.
203 const findByName = (subscriberName: string) =>
204 securitylake.listSubscribers.items({}).pipe(
205 Stream.filter((subscriber) => subscriber.subscriberName === subscriberName),
206 Stream.take(1),
207 Stream.runHead,
208 Effect.map(Option.getOrUndefined),
209 );
210
211 return {
212 read: Effect.fn(function* ({ id, olds, output }) {
213 // An account that never onboarded Security Lake rejects subscriber
214 // APIs with UnauthorizedException — that means "no subscriber".
215 const subscriber = yield* (
216 output?.subscriberId
217 ? getById(output.subscriberId)
218 : Effect.flatMap(createName(id, olds ?? {}), findByName)
219 ).pipe(Effect.catchTag("UnauthorizedException", () => Effect.undefined));
220 if (subscriber === undefined) return undefined;
221 const attrs = buildAttrs(subscriber);
222 const tags = yield* readSecurityLakeTags(attrs.subscriberArn);
223 return (yield* hasAlchemyTags(id, tags)) ? attrs : Unowned(attrs);
224 }),
225
226 list: () =>
227 securitylake.listSubscribers.items({}).pipe(
228 Stream.runCollect,
229 Effect.map((subscribers) => [...subscribers].map(buildAttrs)),
230 // An account that never onboarded Security Lake has no
231 // subscribers to enumerate.
232 Effect.catchTag(
233 ["AccessDeniedException", "ResourceNotFoundException", "UnauthorizedException"],
234 () => Effect.succeed([]),
235 ),
236 ),
237
238 // accessTypes is create-only (UpdateSubscriber cannot change it).
239 diff: Effect.fn(function* ({ news, olds }) {
240 if (!isResolved(news)) return undefined;
241 const oldAccess = [...(olds.accessTypes ?? ["S3"])].sort();
242 const newAccess = [...(news.accessTypes ?? ["S3"])].sort();
243 if (
244 oldAccess.length !== newAccess.length ||
245 oldAccess.some((value, index) => value !== newAccess[index])
246 ) {
247 return { action: "replace" } as const;
248 }
249 }),
250
251 reconcile: Effect.fn(function* ({ id, news, output, session }) {
252 const subscriberName = yield* createName(id, news);
253 const internalTags = yield* createInternalTags(id);
254 const desiredTags = { ...news.tags, ...internalTags };
255
256 // 1. OBSERVE — by cached id first, then by deterministic name.
257 let subscriber = output?.subscriberId ? yield* getById(output.subscriberId) : undefined;
258 subscriber ??= yield* findByName(subscriberName);
259
260 // 2. ENSURE — create when missing; a ConflictException means a
261 // concurrent create won the race, so re-observe by name.
262 if (subscriber === undefined) {
263 subscriber = yield* securitylake
264 .createSubscriber({
265 subscriberName,
266 subscriberIdentity: news.subscriberIdentity,
267 subscriberDescription: news.subscriberDescription,
268 sources: news.sources,
269 accessTypes: news.accessTypes,
270 tags: toTagList(desiredTags),
271 })
272 .pipe(
273 Effect.map((response) => response.subscriber),
274 Effect.catchTag("ConflictException", () => findByName(subscriberName)),
275 );
276 if (subscriber === undefined) {
277 return yield* new SubscriberCreateFailed({ subscriberName });
278 }
279 } else {
280 // 3. SYNC mutable settings — observed ↔ desired.
281 const changed =
282 subscriber.subscriberName !== subscriberName ||
283 (subscriber.subscriberDescription ?? "") !== (news.subscriberDescription ?? "") ||
284 subscriber.subscriberIdentity.principal !== news.subscriberIdentity.principal ||
285 subscriber.subscriberIdentity.externalId !== news.subscriberIdentity.externalId ||
286 !sourcesMatch(news.sources, subscriber.sources);
287 if (changed) {
288 subscriber = yield* securitylake
289 .updateSubscriber({
290 subscriberId: subscriber.subscriberId,
291 subscriberName,
292 subscriberDescription: news.subscriberDescription,
293 subscriberIdentity: news.subscriberIdentity,
294 sources: news.sources,
295 })
296 .pipe(
297 retryWhileConflict,
298 Effect.map((response) => response.subscriber ?? subscriber!),
299 );
300 }
301
302 // 3b. SYNC tags — diff against OBSERVED cloud tags.
303 const observedTags = yield* readSecurityLakeTags(subscriber.subscriberArn);
304 const { upsert, removed } = diffTags(observedTags, desiredTags);
305 if (upsert.length > 0) {
306 yield* securitylake.tagResource({
307 resourceArn: subscriber.subscriberArn,
308 tags: upsert.map((t) => ({ key: t.Key, value: t.Value })),
309 });
310 }
311 if (removed.length > 0) {
312 yield* securitylake.untagResource({
313 resourceArn: subscriber.subscriberArn,
314 tagKeys: removed,
315 });
316 }
317 }
318
319 // 4. RETURN fresh attributes.
320 const final = (yield* getById(subscriber.subscriberId)) ?? subscriber;
321 yield* session.note(final.subscriberArn);
322 return buildAttrs(final);
323 }),
324
325 delete: Effect.fn(function* ({ output }) {
326 yield* securitylake.deleteSubscriber({ subscriberId: output.subscriberId }).pipe(
327 retryWhileConflict,
328 // Gone already, or the data lake itself was offboarded first
329 // (which removes all subscribers and makes subscriber APIs
330 // reject with UnauthorizedException).
331 Effect.catchTag(
332 ["ResourceNotFoundException", "UnauthorizedException"],
333 () => Effect.void,
334 ),
335 );
336 }),
337 };
338 }),
339 );