feat(iam): add Athena service integration permissions (#769)

Auto-generates the IAM execution role permissions documented at
https://docs.aws.amazon.com/step-functions/latest/dg/connect-athena.html
for state machines that invoke Athena. Without this, Athena queries
fail at runtime because the state machine's role lacks the necessary
catalog and storage grants.

- New iamStrategies/athena.js handles the five integration ARNs:
  startQueryExecution(.sync), stopQueryExecution, getQueryExecution,
  getQueryResults
- For startQueryExecution(.sync), grants the full action set plus
  S3, Glue, and Lake Formation permissions per AWS template — Athena
  uses the caller identity for catalog and data access
- Resource scoping: workgroup/<name> when WorkGroup is a static
  string, workgroup/* when it is a runtime path or absent
- Standalone get/stop actions scope to workgroup/* (resource is
  identified at runtime by QueryExecutionId)
- getQueryResults additionally grants s3:GetObject for the result
  location
- Athena .sync uses polling, not EventBridge — no events:Put*
  permission (unlike sagemaker .sync)
- Integration fixture exercises three machines (sync, request-response
  with static WorkGroup, request-response with runtime WorkGroup) and
  asserts the generated CF role matches AWS's documented template

Closes #450

Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: VirtueMe

fixtures/athena/serverless.yml

@@ -0,0 +1,69 @@
+service: integration-athena
+
+provider: ${file(../base.yml):provider}
+plugins: ${file(../base.yml):plugins}
+package: ${file(../base.yml):package}
+custom: ${file(../base.yml):custom}
+
+stepFunctions:
+  stateMachines:
+    athenaMachine:
+      name: integration-athena-${opt:stage, 'test'}
+      definition:
+        StartAt: StartQuery
+        States:
+          StartQuery:
+            Type: Task
+            Resource: arn:aws:states:::athena:startQueryExecution.sync
+            Parameters:
+              QueryString: SELECT 1
+              WorkGroup: primary
+              ResultConfiguration:
+                OutputLocation: s3://example-results/
+            Next: GetQueryExecution
+          GetQueryExecution:
+            Type: Task
+            Resource: arn:aws:states:::athena:getQueryExecution
+            Parameters:
+              QueryExecutionId.$: $.QueryExecution.QueryExecutionId
+            Next: GetQueryResults
+          GetQueryResults:
+            Type: Task
+            Resource: arn:aws:states:::athena:getQueryResults
+            Parameters:
+              QueryExecutionId.$: $.QueryExecution.QueryExecutionId
+            Next: StopQuery
+          StopQuery:
+            Type: Task
+            Resource: arn:aws:states:::athena:stopQueryExecution
+            Parameters:
+              QueryExecutionId.$: $.QueryExecution.QueryExecutionId
+            End: true
+    athenaAsyncMachine:
+      name: integration-athena-async-${opt:stage, 'test'}
+      definition:
+        StartAt: StartQueryAsync
+        States:
+          StartQueryAsync:
+            Type: Task
+            Resource: arn:aws:states:::athena:startQueryExecution
+            Parameters:
+              QueryString: SELECT 1
+              WorkGroup: primary
+              ResultConfiguration:
+                OutputLocation: s3://example-results/
+            End: true
+    athenaRuntimeWorkgroupMachine:
+      name: integration-athena-runtime-wg-${opt:stage, 'test'}
+      definition:
+        StartAt: StartQueryRuntimeWg
+        States:
+          StartQueryRuntimeWg:
+            Type: Task
+            Resource: arn:aws:states:::athena:startQueryExecution
+            Parameters:
+              QueryString: SELECT 1
+              WorkGroup.$: $.workgroup
+              ResultConfiguration:
+                OutputLocation: s3://example-results/
+            End: true

fixtures/athena/verify.test.js

@@ -0,0 +1,146 @@
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+const expect = require('chai').expect;
+
+const templatePath = path.join(__dirname, '.serverless', 'cloudformation-template-update-stack.json');
+
+const collectActions = (role) => role.Properties.Policies[0].PolicyDocument.Statement
+  .flatMap((s) => [].concat(s.Action));
+
+const findStatementByAction = (role, actionName) => role.Properties.Policies[0]
+  .PolicyDocument.Statement.find((s) => [].concat(s.Action).includes(actionName));
+
+const arnSubStrings = (statement) => {
+  const resources = [].concat(statement.Resource);
+  return resources
+    .map((r) => r && r['Fn::Sub'])
+    .filter(Boolean)
+    .map((sub) => (Array.isArray(sub) ? sub[0] : sub));
+};
+
+const workGroupArn = (statement) => arnSubStrings(statement).find((s) => s.includes(':workgroup/'));
+
+describe('athena fixture — generated IAM role', () => {
+  let resources;
+  let syncRole;
+  let asyncRole;
+  let runtimeWgRole;
+
+  before(() => {
+    const template = JSON.parse(fs.readFileSync(templatePath, 'utf8'));
+    resources = template.Resources;
+
+    const roles = Object.values(resources).filter((r) => r.Type === 'AWS::IAM::Role');
+    // The sync machine grants the full Run-a-Job action set including ListQueryExecutions.
+    syncRole = roles.find((r) => collectActions(r).includes('athena:ListQueryExecutions'));
+    const asyncRoles = roles.filter((r) => {
+      const actions = collectActions(r);
+      return actions.includes('athena:startQueryExecution')
+        && !actions.includes('athena:ListQueryExecutions');
+    });
+    asyncRole = asyncRoles.find((r) => workGroupArn(
+      findStatementByAction(r, 'athena:startQueryExecution'),
+    ).endsWith(':workgroup/primary'));
+    runtimeWgRole = asyncRoles.find((r) => workGroupArn(
+      findStatementByAction(r, 'athena:startQueryExecution'),
+    ).endsWith(':workgroup/*'));
+  });
+
+  it('creates an IAM role for each athena state machine', () => {
+    expect(syncRole, 'sync machine role should exist').to.not.equal(undefined);
+    expect(asyncRole, 'async-only static-WorkGroup role should exist').to.not.equal(undefined);
+    expect(runtimeWgRole, 'runtime-WorkGroup role should exist').to.not.equal(undefined);
+  });
+
+  describe('sync machine (startQueryExecution.sync)', () => {
+    it('grants the full Run-a-Job athena action set (matches AWS template)', () => {
+      const stmt = findStatementByAction(syncRole, 'athena:startQueryExecution');
+      const actions = [].concat(stmt.Action);
+      for (const action of [
+        'athena:startQueryExecution',
+        'athena:stopQueryExecution',
+        'athena:getQueryExecution',
+        'athena:getDataCatalog',
+        'athena:GetWorkGroup',
+        'athena:BatchGetQueryExecution',
+        'athena:GetQueryResults',
+        'athena:ListQueryExecutions',
+      ]) {
+        expect(actions).to.include(action);
+      }
+    });
+
+    it('scopes the athena resource to workgroup/<name> + datacatalog/* when WorkGroup is static', () => {
+      const stmt = findStatementByAction(syncRole, 'athena:startQueryExecution');
+      const arns = arnSubStrings(stmt);
+      expect(arns.some((a) => /:workgroup\/primary$/.test(a))).to.equal(true);
+      expect(arns.some((a) => /:datacatalog\/\*$/.test(a))).to.equal(true);
+    });
+
+    it('does not grant events:* (Athena .sync uses polling, not the EventBridge rule)', () => {
+      const actions = collectActions(syncRole);
+      expect(actions).to.not.include('events:PutTargets');
+      expect(actions).to.not.include('events:PutRule');
+      expect(actions).to.not.include('events:DescribeRule');
+    });
+
+    it('grants the documented S3 action set on arn:aws:s3:::*', () => {
+      const stmt = findStatementByAction(syncRole, 's3:GetBucketLocation');
+      const actions = [].concat(stmt.Action);
+      for (const action of [
+        's3:GetBucketLocation', 's3:GetObject', 's3:ListBucket', 's3:PutObject',
+      ]) {
+        expect(actions).to.include(action);
+      }
+      expect([].concat(stmt.Resource)).to.include('arn:aws:s3:::*');
+    });
+
+    it('grants the documented Glue action set on catalog/database/table/userDefinedFunction', () => {
+      const stmt = findStatementByAction(syncRole, 'glue:GetDatabase');
+      const arns = arnSubStrings(stmt);
+      expect(arns.some((a) => /:catalog$/.test(a))).to.equal(true);
+      expect(arns.some((a) => /:database\/\*$/.test(a))).to.equal(true);
+      expect(arns.some((a) => /:table\/\*$/.test(a))).to.equal(true);
+      expect(arns.some((a) => /:userDefinedFunction\/\*$/.test(a))).to.equal(true);
+    });
+
+    it('grants lakeformation:GetDataAccess on *', () => {
+      const stmt = findStatementByAction(syncRole, 'lakeformation:GetDataAccess');
+      expect(stmt).to.not.equal(undefined);
+      expect([].concat(stmt.Resource)).to.include('*');
+    });
+  });
+
+  describe('async-only machine with static WorkGroup (startQueryExecution request-response)', () => {
+    it('grants only startQueryExecution and getDataCatalog (no polling/stop)', () => {
+      const stmt = findStatementByAction(asyncRole, 'athena:startQueryExecution');
+      const actions = [].concat(stmt.Action);
+      expect(actions).to.include('athena:startQueryExecution');
+      expect(actions).to.include('athena:getDataCatalog');
+      expect(actions).to.not.include('athena:stopQueryExecution');
+      expect(actions).to.not.include('athena:getQueryResults');
+      expect(actions).to.not.include('athena:ListQueryExecutions');
+    });
+
+    it('still grants S3 + Glue + LakeFormation (Athena uses caller identity for data access)', () => {
+      const actions = collectActions(asyncRole);
+      expect(actions).to.include('s3:GetObject');
+      expect(actions).to.include('glue:GetTable');
+      expect(actions).to.include('lakeformation:GetDataAccess');
+    });
+
+    it('scopes the athena resource to workgroup/primary', () => {
+      const stmt = findStatementByAction(asyncRole, 'athena:startQueryExecution');
+      expect(workGroupArn(stmt)).to.match(/:workgroup\/primary$/);
+    });
+  });
+
+  describe('runtime-WorkGroup machine (WorkGroup.$ path)', () => {
+    it('falls back to workgroup/* when the WorkGroup is a runtime JSON path', () => {
+      const stmt = findStatementByAction(runtimeWgRole, 'athena:startQueryExecution');
+      expect(workGroupArn(stmt)).to.match(/:workgroup\/\*$/);
+    });
+  });
+});

lib/deploy/stepFunctions/iamStrategies/athena.js

@@ -0,0 +1,87 @@
+'use strict';
+
+// IAM permissions follow AWS's documented templates for Step Functions ↔ Athena
+// integration. Athena is unusual: it uses the *caller's* IAM identity for Glue
+// catalog and S3 data access, so the state machine's execution role needs Glue,
+// S3, and Lake Formation grants in addition to the athena: actions.
+// Reference: https://docs.aws.amazon.com/step-functions/latest/dg/connect-athena.html
+
+const S3_PERMISSIONS = {
+  action: 's3:GetBucketLocation,s3:GetObject,s3:ListBucket,s3:ListBucketMultipartUploads,s3:ListMultipartUploadParts,s3:AbortMultipartUpload,s3:CreateBucket,s3:PutObject',
+  resource: 'arn:aws:s3:::*',
+};
+
+const GLUE_PERMISSIONS = {
+  action: 'glue:CreateDatabase,glue:GetDatabase,glue:GetDatabases,glue:UpdateDatabase,glue:DeleteDatabase,glue:CreateTable,glue:UpdateTable,glue:GetTable,glue:GetTables,glue:DeleteTable,glue:BatchDeleteTable,glue:BatchCreatePartition,glue:CreatePartition,glue:UpdatePartition,glue:GetPartition,glue:GetPartitions,glue:BatchGetPartition,glue:DeletePartition,glue:BatchDeletePartition',
+  resource: [
+    { 'Fn::Sub': ['arn:${AWS::Partition}:glue:${AWS::Region}:${AWS::AccountId}:catalog', {}] },
+    { 'Fn::Sub': ['arn:${AWS::Partition}:glue:${AWS::Region}:${AWS::AccountId}:database/*', {}] },
+    { 'Fn::Sub': ['arn:${AWS::Partition}:glue:${AWS::Region}:${AWS::AccountId}:table/*', {}] },
+    { 'Fn::Sub': ['arn:${AWS::Partition}:glue:${AWS::Region}:${AWS::AccountId}:userDefinedFunction/*', {}] },
+  ],
+};
+
+const LAKE_FORMATION_PERMISSION = {
+  action: 'lakeformation:GetDataAccess',
+  resource: '*',
+};
+
+function workGroupArn(workGroupName) {
+  const target = workGroupName || '*';
+  return {
+    'Fn::Sub': [
+      `arn:\${AWS::Partition}:athena:\${AWS::Region}:\${AWS::AccountId}:workgroup/${target}`,
+      {},
+    ],
+  };
+}
+
+const dataCatalogArn = {
+  'Fn::Sub': [
+    'arn:${AWS::Partition}:athena:${AWS::Region}:${AWS::AccountId}:datacatalog/*',
+    {},
+  ],
+};
+
+function staticWorkGroup(state) {
+  const wg = state && state.Parameters && state.Parameters.WorkGroup;
+  return typeof wg === 'string' && wg.length > 0 ? wg : null;
+}
+
+function getStartQueryPermissions({ sync = false, state } = {}) {
+  const athenaActions = sync
+    ? 'athena:startQueryExecution,athena:stopQueryExecution,athena:getQueryExecution,athena:getDataCatalog,athena:GetWorkGroup,athena:BatchGetQueryExecution,athena:GetQueryResults,athena:ListQueryExecutions'
+    : 'athena:startQueryExecution,athena:getDataCatalog';
+
+  return [
+    {
+      action: athenaActions,
+      resource: [workGroupArn(staticWorkGroup(state)), dataCatalogArn],
+    },
+    S3_PERMISSIONS,
+    GLUE_PERMISSIONS,
+    LAKE_FORMATION_PERMISSION,
+  ];
+}
+
+function getStopQueryPermissions() {
+  return [{ action: 'athena:stopQueryExecution', resource: workGroupArn(null) }];
+}
+
+function getGetQueryExecutionPermissions() {
+  return [{ action: 'athena:getQueryExecution', resource: workGroupArn(null) }];
+}
+
+function getGetQueryResultsPermissions() {
+  return [
+    { action: 'athena:getQueryResults', resource: workGroupArn(null) },
+    { action: 's3:GetObject', resource: 'arn:aws:s3:::*' },
+  ];
+}
+
+module.exports = {
+  getStartQueryPermissions,
+  getStopQueryPermissions,
+  getGetQueryExecutionPermissions,
+  getGetQueryResultsPermissions,
+};