aws-lambda-event-sources: aws-cdk-lib.aws_iam.GrantOnPrincipalOptions#scope is deprecated.

[jdelStrother]

Describe the bug

Not sure if deprecation warnings are considered bugs, but thought it was worth reporting just in case.

If I connect a dynamodb event source to a lambda function, I get a deprecation warning on aws-cdk-lib.aws_iam.GrantOnPrincipalOptions#scope

Regression Issue

• Select this option if this issue appears to be a regression.

Last Known Working CDK Library Version

2.138.0

Expected Behavior

No deprecations are printed for using DynamoEventSource as documented. (Apologies if I'm missing something and using it incorrectly)

Current Behavior

This is printed:

[WARNING] aws-cdk-lib.aws_iam.GrantOnPrincipalOptions#scope is deprecated.
  The scope argument is currently unused.
  This API will be removed in the next major release.

Reproduction Steps

This seems to be a minimal reproduction:

    const fn = new lambda.Function(this, "MyFunction", {
      runtime: lambda.Runtime.PYTHON_3_11,
      handler: "index.handler",
      code: lambda.Code.fromInline(
        'def handler(event, context): return "Hello"',
      ),
    });
    const dynamoDBMetricsTable = new dynamodb.Table(this, "MetricsTable", {
      partitionKey: { name: "podcast_id", type: dynamodb.AttributeType.NUMBER },
      stream: dynamodb.StreamViewType.KEYS_ONLY,
    });
    fn.addEventSource(
      new DynamoEventSource(dynamoDBMetricsTable, {
        startingPosition: lambda.StartingPosition.LATEST,
        batchSize: 50,
        maxBatchingWindow: cdk.Duration.seconds(300),
        bisectBatchOnError: true,
      }),
    );

Possible Solution

No response

Additional Information/Context

No response

AWS CDK Library version (aws-cdk-lib)

2.231.0

AWS CDK CLI version

2.1033.0 (build 1ec3310)

Node.js Version

22.20

OS

macOS 15.7.1

Language

TypeScript

Language Version

No response

Other information

No response

[pahud]

Hi @jdelStrother,

Thank you for reporting this issue. The analysis indicates that the deprecation warnings are coming from the StreamGrants class, which is still passing the deprecated scope parameter to iam.Grant.addToPrincipal().

The issue appears in two places:

1. StreamGrants.actions() -

aws-cdk/packages/aws-cdk-lib/aws-dynamodb/lib/stream-grants.ts

Lines 54 to 61 in ad25aba

	public actions(grantee: iam.IGrantable, ...actions: string[]): iam.Grant {
	return iam.Grant.addToPrincipal({
	grantee,
	actions,
	resourceArns: [this.tableStreamArn],
	scope: this.table,
	});
	}

2. StreamGrants.read() - line 95:

aws-cdk/packages/aws-cdk-lib/aws-dynamodb/lib/stream-grants.ts

Lines 86 to 94 in ad25aba

	public read(grantee: iam.IGrantable): iam.Grant {
	this.list(grantee);
	this.encryptionKey?.grant(grantee, ...perms.KEY_READ_ACTIONS);
	return iam.Grant.addToPrincipal({
	grantee,
	actions: perms.READ_STREAM_DATA_ACTIONS,
	resourceArns: [this.tableStreamArn],
	scope: this.table,
	});

The fix would be to remove the scope: this.table parameter from both method calls, as the scope parameter is deprecated and currently unused according to the GrantOnPrincipalOptions interface:

aws-cdk/packages/aws-cdk-lib/aws-iam/lib/grant.ts

Line 88 in ad25aba

* @deprecated The scope argument is currently unused.

I can't find an immediate method to mute this specific deprecation warning. Making this a p1 and requesting review from the team.

[pahud]

Before we have a PR to fix them. The only option is export JSII_DEPRECATED=quiet to disable all deprecation warnings.

[rix0rrr]

There's something more to investigate here: our tests should validate that the public API surface is not using deprecated APIs internally.

We should do this by setting JSII_DEPRECATED=abort (or whatever the setting is, look it up). Apparently that has stopped working at some point, and we should reinstate it.