fix(cloudtrail): address cubic review findings

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01LJV2dCcAYvf1JuxquCMZAd

Author: waleedlatif1

apps/docs/content/docs/integrations/cloudtrail.mdx

@@ -11,7 +11,9 @@ import { BlockInfoCard } from "@/components/ui/block-info-card"
 />
 
 {/* MANUAL-CONTENT-START:intro */}
-[AWS CloudTrail](https://aws.amazon.com/cloudtrail/) records who did what in your AWS accounts. Every API call — from the console, the CLI, an SDK, or another AWS service — is captured as an event with the calling identity, source IP, parameters, and result. It is the system of record for security investigation, compliance evidence, and answering "what changed?"
+[AWS CloudTrail](https://aws.amazon.com/cloudtrail/) records who did what in your AWS accounts. An API call — from the console, the CLI, an SDK, or another AWS service — is captured as an event with the calling identity, source IP, parameters, and result. It is the system of record for security investigation, compliance evidence, and answering "what changed?"
+
+What lands in that record is set by configuration, not assumed. Trails and event data stores log management events by default; data events, network activity events, and Insights events are captured only where you configure selectors for them. Read a trail's selectors before you treat its history as complete.
 
 With AWS CloudTrail, you can:
 
@@ -22,9 +24,39 @@ With AWS CloudTrail, you can:
 
 In Sim, CloudTrail is the audit half of the AWS story. Where IAM and Identity Center answer *who has access*, CloudTrail answers *what they actually did with it* — so an agent can take a suspicious permission change and trace it back to the principal, the source IP, and the moment it happened, then hand a written timeline to whoever needs to act on it.
 
-This block is read-only with one narrow exception: `Cancel Query` stops a running CloudTrail Lake query. It never enables or disables logging, alters trail configuration, or deletes a trail, so it can be granted a `cloudtrail:Describe*/Get*/List*/LookupEvents/StartQuery` policy with no residual write risk. Note that `Start Query` is billed per GB scanned and consumes your account's concurrent-query quota.
-
-`Lookup Events` is limited by AWS to two requests per second per account per Region. The block paces itself against that limit automatically, so broad searches take longer rather than failing.
+This block is read-only with one narrow exception: `Cancel Query` stops a running CloudTrail Lake query. It never enables or disables logging, alters trail configuration, or deletes a trail. Every operation it ships is covered by this policy, with no residual write risk:
+
+```json
+{
+  "Version": "2012-10-17",
+  "Statement": [
+    {
+      "Effect": "Allow",
+      "Action": [
+        "cloudtrail:DescribeTrails",
+        "cloudtrail:GetTrail",
+        "cloudtrail:GetTrailStatus",
+        "cloudtrail:GetEventSelectors",
+        "cloudtrail:GetInsightSelectors",
+        "cloudtrail:GetEventDataStore",
+        "cloudtrail:ListTrails",
+        "cloudtrail:ListEventDataStores",
+        "cloudtrail:ListTags",
+        "cloudtrail:LookupEvents",
+        "cloudtrail:StartQuery",
+        "cloudtrail:DescribeQuery",
+        "cloudtrail:GetQueryResults",
+        "cloudtrail:CancelQuery"
+      ],
+      "Resource": "*"
+    }
+  ]
+}
+```
+
+`cloudtrail:CancelQuery` is the action `Cancel Query` needs, and it is not implied by `Describe*`, `Get*`, or `List*` — omit it and that one operation fails with an access-denied error. Note that `Start Query` is billed per GB scanned and consumes your account's concurrent-query quota of 10.
+
+`Lookup Events` is limited by AWS to two requests per second per account per Region. Each call uses AWS adaptive retry mode and allows up to six attempts, so a throttled request backs off exponentially with jitter and usually succeeds instead of surfacing an error. That is a retry budget, not a guarantee: sustained throttling past six attempts fails the call with a `ThrottlingException`, and because a fresh SDK client is built per invocation, adaptive mode's client-side rate limiter carries no pacing state between calls. `Lookup Events` also returns one page per call — feed `nextToken` back in to walk a broad search, and expect to handle a throttling error on a long paging loop.
 {/* MANUAL-CONTENT-END */}
 
 
@@ -192,7 +224,7 @@ List the ARN, name, and home Region of every CloudTrail trail visible to the acc
 |   ↳ `trailArn` | string | ARN of the trail |
 |   ↳ `name` | string | Trail name |
 |   ↳ `homeRegion` | string | Region in which the trail was created |
-| `nextToken` | string | Pagination token for the next page of trails |
+| `nextToken` | string | Pagination token for the next page of trails, or null on the last page |
 
 ### CloudTrail Get Event Selectors
 

apps/sim/lib/api/contracts/tools/aws/cloudtrail-describe-query.ts

@@ -7,6 +7,12 @@ import type {
 import { defineRouteContract } from '@/lib/api/contracts/types'
 import { validateAwsRegion } from '@/lib/core/security/input-validation'
 
+/**
+ * `DescribeQuery` requires either `QueryId` or `QueryAlias`. AWS documents `RefreshId` as
+ * something you "provide along with `QueryAlias`" to read a dashboard refresh, so it is
+ * rejected when the query is addressed by ID.
+ * @see https://docs.aws.amazon.com/awscloudtrail/latest/APIReference/API_DescribeQuery.html
+ */
 const DescribeQuerySchema = z
   .object({
     region: z
@@ -44,9 +50,21 @@ const DescribeQuerySchema = z
       .regex(/^\d+$/, 'Account ID must be numeric')
       .optional(),
   })
-  .refine((v) => Boolean(v.queryId) !== Boolean(v.queryAlias), {
-    message: 'Specify exactly one of queryId or queryAlias',
-    path: ['queryId'],
+  .superRefine((v, ctx) => {
+    if (Boolean(v.queryId) === Boolean(v.queryAlias)) {
+      ctx.addIssue({
+        code: 'custom',
+        message: 'Specify exactly one of queryId or queryAlias',
+        path: ['queryId'],
+      })
+    }
+    if (v.refreshId && !v.queryAlias) {
+      ctx.addIssue({
+        code: 'custom',
+        message: 'refreshId identifies a dashboard refresh and is only valid with queryAlias',
+        path: ['refreshId'],
+      })
+    }
   })
 
 const DescribeQueryResponseSchema = z.object({

apps/sim/lib/api/contracts/tools/aws/cloudtrail-describe-trails.ts

@@ -1,4 +1,5 @@
 import { z } from 'zod'
+import { cloudtrailTrailNameOrArnSchema } from '@/lib/api/contracts/tools/aws/cloudtrail-shared'
 import type {
   ContractBody,
   ContractBodyInput,
@@ -7,22 +8,6 @@ import type {
 import { defineRouteContract } from '@/lib/api/contracts/types'
 import { validateAwsRegion } from '@/lib/core/security/input-validation'
 
-/**
- * A trail name (3-128 chars, ASCII alphanumerics plus non-adjacent `.`, `_`, `-`,
- * starting and ending alphanumeric) or a full trail ARN. Shadow trails and
- * organization trails in another Region can only be addressed by ARN.
- * @see https://docs.aws.amazon.com/awscloudtrail/latest/APIReference/API_GetTrail.html
- */
-const trailNameOrArnSchema = z
-  .string()
-  .trim()
-  .min(3, 'Trail name must be at least 3 characters')
-  .max(256, 'Trail name or ARN is too long')
-  .regex(
-    /^(?:arn:aws[a-zA-Z0-9-]*:cloudtrail:[a-z0-9-]+:\d{12}:trail\/[\w.\-/]+|[a-zA-Z0-9](?:[._-]?[a-zA-Z0-9]+)+)$/,
-    'Must be a valid trail name or trail ARN'
-  )
-
 const trailSchema = z.object({
   name: z.string(),
   s3BucketName: z.string().nullable(),
@@ -51,9 +36,17 @@ const DescribeTrailsSchema = z.object({
     }),
   accessKeyId: z.string().min(1, 'AWS access key ID is required'),
   secretAccessKey: z.string().min(1, 'AWS secret access key is required'),
+  /**
+   * `DescribeTrails` documents no array-member limit on `trailNameList`, so this ceiling is a
+   * request-payload guard rather than an AWS constraint. It is deliberately set above anything
+   * reachable: the trails-per-Region quota is 5, so naming every trail and shadow trail in an
+   * account across all commercial Regions still stays well under 200.
+   * @see https://docs.aws.amazon.com/awscloudtrail/latest/APIReference/API_DescribeTrails.html
+   * @see https://docs.aws.amazon.com/awscloudtrail/latest/userguide/WhatIsCloudTrail-Limits.html
+   */
   trailNameList: z
-    .array(trailNameOrArnSchema)
-    .max(200, 'A maximum of 200 trail names or ARNs can be described at once')
+    .array(cloudtrailTrailNameOrArnSchema)
+    .max(200, 'At most 200 trail names or ARNs can be described in one request')
     .optional(),
   includeShadowTrails: z.boolean().optional(),
 })

apps/sim/lib/api/contracts/tools/aws/cloudtrail-get-event-selectors.ts

@@ -1,4 +1,5 @@
 import { z } from 'zod'
+import { cloudtrailTrailNameOrArnSchema } from '@/lib/api/contracts/tools/aws/cloudtrail-shared'
 import type {
   ContractBody,
   ContractBodyInput,
@@ -7,22 +8,6 @@ import type {
 import { defineRouteContract } from '@/lib/api/contracts/types'
 import { validateAwsRegion } from '@/lib/core/security/input-validation'
 
-/**
- * A trail name (3-128 chars, ASCII alphanumerics plus non-adjacent `.`, `_`, `-`,
- * starting and ending alphanumeric) or a full trail ARN. Shadow trails and
- * organization trails in another Region can only be addressed by ARN.
- * @see https://docs.aws.amazon.com/awscloudtrail/latest/APIReference/API_GetTrail.html
- */
-const trailNameOrArnSchema = z
-  .string()
-  .trim()
-  .min(3, 'Trail name must be at least 3 characters')
-  .max(256, 'Trail name or ARN is too long')
-  .regex(
-    /^(?:arn:aws[a-zA-Z0-9-]*:cloudtrail:[a-z0-9-]+:\d{12}:trail\/[\w.\-/]+|[a-zA-Z0-9](?:[._-]?[a-zA-Z0-9]+)+)$/,
-    'Must be a valid trail name or trail ARN'
-  )
-
 const advancedEventSelectorSchema = z.object({
   name: z.string().nullable(),
   fieldSelectors: z.array(
@@ -47,7 +32,7 @@ const GetEventSelectorsSchema = z.object({
     }),
   accessKeyId: z.string().min(1, 'AWS access key ID is required'),
   secretAccessKey: z.string().min(1, 'AWS secret access key is required'),
-  trailName: trailNameOrArnSchema,
+  trailName: cloudtrailTrailNameOrArnSchema,
 })
 
 const GetEventSelectorsResponseSchema = z.object({

apps/sim/lib/api/contracts/tools/aws/cloudtrail-get-insight-selectors.ts

@@ -1,4 +1,5 @@
 import { z } from 'zod'
+import { cloudtrailTrailNameOrArnSchema } from '@/lib/api/contracts/tools/aws/cloudtrail-shared'
 import type {
   ContractBody,
   ContractBodyInput,
@@ -7,22 +8,6 @@ import type {
 import { defineRouteContract } from '@/lib/api/contracts/types'
 import { validateAwsRegion } from '@/lib/core/security/input-validation'
 
-/**
- * A trail name (3-128 chars, ASCII alphanumerics plus non-adjacent `.`, `_`, `-`,
- * starting and ending alphanumeric) or a full trail ARN. Shadow trails and
- * organization trails in another Region can only be addressed by ARN.
- * @see https://docs.aws.amazon.com/awscloudtrail/latest/APIReference/API_GetTrail.html
- */
-const trailNameOrArnSchema = z
-  .string()
-  .trim()
-  .min(3, 'Trail name must be at least 3 characters')
-  .max(256, 'Trail name or ARN is too long')
-  .regex(
-    /^(?:arn:aws[a-zA-Z0-9-]*:cloudtrail:[a-z0-9-]+:\d{12}:trail\/[\w.\-/]+|[a-zA-Z0-9](?:[._-]?[a-zA-Z0-9]+)+)$/,
-    'Must be a valid trail name or trail ARN'
-  )
-
 /**
  * The ARN, or the ID suffix of the ARN, of a CloudTrail Lake event data store.
  * @see https://docs.aws.amazon.com/awscloudtrail/latest/APIReference/API_GetEventDataStore.html
@@ -44,7 +29,7 @@ const GetInsightSelectorsSchema = z
       }),
     accessKeyId: z.string().min(1, 'AWS access key ID is required'),
     secretAccessKey: z.string().min(1, 'AWS secret access key is required'),
-    trailName: trailNameOrArnSchema.optional(),
+    trailName: cloudtrailTrailNameOrArnSchema.optional(),
     eventDataStore: eventDataStoreSchema.optional(),
   })
   .refine((v) => Boolean(v.trailName) !== Boolean(v.eventDataStore), {

apps/sim/lib/api/contracts/tools/aws/cloudtrail-get-trail-status.ts

@@ -1,4 +1,5 @@
 import { z } from 'zod'
+import { cloudtrailTrailNameOrArnSchema } from '@/lib/api/contracts/tools/aws/cloudtrail-shared'
 import type {
   ContractBody,
   ContractBodyInput,
@@ -7,22 +8,6 @@ import type {
 import { defineRouteContract } from '@/lib/api/contracts/types'
 import { validateAwsRegion } from '@/lib/core/security/input-validation'
 
-/**
- * A trail name (3-128 chars, ASCII alphanumerics plus non-adjacent `.`, `_`, `-`,
- * starting and ending alphanumeric) or a full trail ARN. Shadow trails and
- * organization trails in another Region can only be addressed by ARN.
- * @see https://docs.aws.amazon.com/awscloudtrail/latest/APIReference/API_GetTrail.html
- */
-const trailNameOrArnSchema = z
-  .string()
-  .trim()
-  .min(3, 'Trail name must be at least 3 characters')
-  .max(256, 'Trail name or ARN is too long')
-  .regex(
-    /^(?:arn:aws[a-zA-Z0-9-]*:cloudtrail:[a-z0-9-]+:\d{12}:trail\/[\w.\-/]+|[a-zA-Z0-9](?:[._-]?[a-zA-Z0-9]+)+)$/,
-    'Must be a valid trail name or trail ARN'
-  )
-
 const GetTrailStatusSchema = z.object({
   region: z
     .string()
@@ -32,7 +17,7 @@ const GetTrailStatusSchema = z.object({
     }),
   accessKeyId: z.string().min(1, 'AWS access key ID is required'),
   secretAccessKey: z.string().min(1, 'AWS secret access key is required'),
-  name: trailNameOrArnSchema,
+  name: cloudtrailTrailNameOrArnSchema,
 })
 
 const GetTrailStatusResponseSchema = z.object({

apps/sim/lib/api/contracts/tools/aws/cloudtrail-get-trail.ts

@@ -1,4 +1,5 @@
 import { z } from 'zod'
+import { cloudtrailTrailNameOrArnSchema } from '@/lib/api/contracts/tools/aws/cloudtrail-shared'
 import type {
   ContractBody,
   ContractBodyInput,
@@ -7,22 +8,6 @@ import type {
 import { defineRouteContract } from '@/lib/api/contracts/types'
 import { validateAwsRegion } from '@/lib/core/security/input-validation'
 
-/**
- * A trail name (3-128 chars, ASCII alphanumerics plus non-adjacent `.`, `_`, `-`,
- * starting and ending alphanumeric) or a full trail ARN. Shadow trails and
- * organization trails in another Region can only be addressed by ARN.
- * @see https://docs.aws.amazon.com/awscloudtrail/latest/APIReference/API_GetTrail.html
- */
-const trailNameOrArnSchema = z
-  .string()
-  .trim()
-  .min(3, 'Trail name must be at least 3 characters')
-  .max(256, 'Trail name or ARN is too long')
-  .regex(
-    /^(?:arn:aws[a-zA-Z0-9-]*:cloudtrail:[a-z0-9-]+:\d{12}:trail\/[\w.\-/]+|[a-zA-Z0-9](?:[._-]?[a-zA-Z0-9]+)+)$/,
-    'Must be a valid trail name or trail ARN'
-  )
-
 const GetTrailSchema = z.object({
   region: z
     .string()
@@ -32,7 +17,7 @@ const GetTrailSchema = z.object({
     }),
   accessKeyId: z.string().min(1, 'AWS access key ID is required'),
   secretAccessKey: z.string().min(1, 'AWS secret access key is required'),
-  name: trailNameOrArnSchema,
+  name: cloudtrailTrailNameOrArnSchema,
 })
 
 const GetTrailResponseSchema = z.object({

apps/sim/lib/api/contracts/tools/aws/cloudtrail-shared.ts

@@ -0,0 +1,41 @@
+import { z } from 'zod'
+
+/**
+ * Boundary primitives shared by the AWS CloudTrail tool contracts.
+ *
+ * Every bound and pattern here is transcribed from the CloudTrail API Reference.
+ */
+
+/** Longest trail name CloudTrail accepts, per `InvalidTrailNameException`. */
+const TRAIL_NAME_MAX_LENGTH = 128
+
+/** Longest trail ARN CloudTrail accepts wherever a name or ARN is allowed. */
+const TRAIL_ARN_MAX_LENGTH = 256
+
+const TRAIL_NAME_OR_ARN_PATTERN =
+  /^(?:arn:aws[a-zA-Z0-9-]*:cloudtrail:[a-z0-9-]+:\d{12}:trail\/[\w.\-/]+|[a-zA-Z0-9](?:[._-]?[a-zA-Z0-9]+)+)$/
+
+/**
+ * A trail name or a full trail ARN. The two branches carry different ceilings: a bare name
+ * is 3-128 characters of ASCII alphanumerics plus non-adjacent `.`, `_`, `-`, starting and
+ * ending alphanumeric, while an ARN may run to 256. Applying only the ARN ceiling would let
+ * a 129-256 character bare name through to AWS, which rejects it with
+ * `InvalidTrailNameException`. Shadow trails and organization trails in another Region can
+ * only be addressed by ARN.
+ * @see https://docs.aws.amazon.com/awscloudtrail/latest/APIReference/API_GetTrail.html
+ * @see https://docs.aws.amazon.com/awscloudtrail/latest/APIReference/API_DescribeTrails.html
+ */
+export const cloudtrailTrailNameOrArnSchema = z
+  .string()
+  .trim()
+  .min(3, 'Trail name must be at least 3 characters')
+  .max(TRAIL_ARN_MAX_LENGTH, 'Trail name or ARN is too long')
+  .regex(TRAIL_NAME_OR_ARN_PATTERN, 'Must be a valid trail name or trail ARN')
+  .superRefine((value, ctx) => {
+    if (!value.startsWith('arn:') && value.length > TRAIL_NAME_MAX_LENGTH) {
+      ctx.addIssue({
+        code: 'custom',
+        message: `Trail name must be at most ${TRAIL_NAME_MAX_LENGTH} characters; use the trail ARN to address a trail in another Region`,
+      })
+    }
+  })