dynamodb: TableV2 grants emit unactionable upstream deprecation warnings

[laazyj]

Summary

Every synth() that grants against a TableV2 emits two deprecation warnings that consumers cannot act on:

[WARNING] aws-cdk-lib.aws_dynamodb.TableGrantsProps#encryptedResource is deprecated.
  - Leave this field undefined. ... This API will be removed in the next major release.
[WARNING] aws-cdk-lib.aws_dynamodb.TableGrantsProps#policyResource is deprecated.
  - Leave this field undefined. ... This API will be removed in the next major release.

Surfaced while investigating the CI timeouts on #329 (fixed in #337).

It is not our call site

packages/dynamodb/src/grants.ts calls the plain native methods and never passes those props:

read: capability((table, grantee) => {
  table.grantReadData(grantee);
}),

Isolated it to TableV2 specifically, with a script using only aws-cdk-lib and no ComposureCDK:

construct	grantReadData	grantReadWriteData	grantFullAccess
Table (v1)	0 warnings	0	0
TableV2	2 warnings	2	2

So aws-cdk-lib's own TableV2 grant path constructs TableGrants with the deprecated props internally. Reproduced on aws-cdk-lib@2.262.1.

Why it still matters to us

TableV2Builder is shipped library code, so every consumer using tableGrants.* against a v2 table sees these warnings on every synth, with no way to silence them and nothing to fix in their own code. Two of our own examples trigger it: crud-api-app.ts and clean-desk-policy.ts.

The props are marked for removal in the next major, so this should resolve upstream — but it is worth tracking rather than rediscovering.

Suggested actions

• Confirm against the latest aws-cdk-lib and check whether an upstream issue already exists
• File upstream if not
• Decide whether to note it in the dynamodb README so consumers do not chase it

No change to ComposureCDK is indicated today — the call sites are already correct.

[laazyj]

Diagnosis

Traced to aws-cdk-lib and reproduced against published aws-cdk-lib@2.262.1. Confirmed still present on today's upstream main.

Root cause

It is TableV2's constructor — not the grant call — at packages/aws-cdk-lib/aws-dynamodb/lib/table-v2.ts:877-883, and again at :1532-1537 for TableV2MultiAccountReplica:

this.grants = new TableGrants({
  table: this,
  regions: Array.from(this.replicaTables.keys()),
  hasIndex: this.hasIndex,
  encryptedResource: this.encryptionKey ? this : undefined,  // deprecated
  policyResource: this,                                      // deprecated
});

v1 Table goes through TableGrants.fromTable(this, this.regions) (table.ts:744), which passes neither — hence the 0-vs-2 split in the table above.

Two things make it leak to consumers:

1. jsii injects the deprecation check into the callee, not the caller. The compiled TableGrants constructor opens with jsiiDeprecationWarnings().aws_cdk_lib_aws_dynamodb_TableGrantsProps(props). It fires for any caller, including aws-cdk-lib's own internals. There is no "internal use is exempt" path.
2. The generated validator tests key presence, not value. From .warnings.jsii.js:

   "encryptedResource" in p && print(...), "policyResource" in p && print(...)

   So encryptedResource: undefined — the false branch of that ternary — still warns. That is why unencrypted tables get two warnings, not one.

Correction to the framing here (and to upstream #37221)

Neither tableGrants.* nor grantStreamRead() is implicated. Repro against 2.262.1:

>>> creating A          → 2 warnings
>>> creating B          → 2 warnings   (no grants called at all)

Warnings fire at new TableV2(...), before any grant* call, once per instance, no dedup. Table v1 emits none, and grantStreamRead on either construct emits none — StreamGrants is constructed cleanly at table.ts:756.

So TableV2Builder triggers this merely by constructing the table. The count scales with tables, not grant calls. A README note filed under "grants" would point consumers at the wrong place.

Severity is worse than warnings

cdk-test and framework-integ's integ script both run with JSII_DEPRECATED=fail, where the emitter throws instead of warning:

$ JSII_DEPRECATED=fail node repro.js
v1 Table    : OK
v2 TableV2  : THREW DeprecationError: aws-cdk-lib.aws_dynamodb.TableGrantsProps#encryptedResource is deprecated.

Under strict mode TableV2 cannot be constructed at all. That is not cosmetic.

Upstream status

An upstream issue already exists — aws/aws-cdk#37221 (open, bug / effort/small / good first issue / p2, filed 11 Mar 2026). Its stated root cause (DynamoEventSource.bind() → grantStreamRead()) is wrong per the above.

PR aws/aws-cdk#38399 is open and does exactly the right thing: deletes the two lines at both call sites in table-v2.ts. Labelled pr/needs-community-review, blocked on a test-exemption request. No need to file upstream or open a competing PR — the second checkbox above can be closed out.

Why deleting those lines is behaviour-preserving

• policyResource: this → the ?? fallback is iam.ResourceWithPolicies.of(this); GrantableResources.isResourceWithPolicy just checks addToResourcePolicy !== undefined (aws-iam/lib/grant.ts:573), which TableBaseV2 defines. Resolves to the identical this.
• encryptedResource: this.encryptionKey ? this : undefined → fallback is EncryptedResources.of(this); isEncryptedResource checks grantOnKey !== undefined, which TableBaseV2 defines at table-v2-base.ts:271 as { grant: this.encryptionKey?.grant(...) } — already a no-op without a CMK. The ternary is dead code today: its undefined branch falls straight through the ?? to the same object it was trying to avoid.

Existing upstream tests already pin both resolutions: table-v2-base.test.ts:149/412/541 (CMK + grant, assert kms:Decrypt et al.), :1004/:1329 (replica and imported keys), table-v2.test.ts:1273 (the addToPrincipalOrResource branch with resourceSelfArns: ['*']), and :3857–4151 for the replica call site. The non-CMK case is covered implicitly — :88/:347/:500 assert exact Statement arrays, so a spurious kms:* statement would fail the match.

The one thing genuinely not covered is a guard against the deprecated props coming back, and that gap is structural: aws-cdk-lib's jest config prefers .ts over .js with a ts-jest transform, so intra-package imports resolve to TypeScript source where the jsii prologue does not exist. A unit test under aws-dynamodb/test/ cannot observe the warning at all. Such a guard has to live in a package consuming the built aws-cdk-lib.

Alternatives considered

A. Internal escape hatch. Add an @internal factory on TableGrants taking pre-resolved trait objects so aws-cdk-lib internals never cross the deprecated public struct. Keeps explicit wiring available if trait auto-discovery ever fails for a TableV2 variant. Costs internal API surface, does not help the other structs with the same self-inflicted pattern. Worse than the direct fix unless someone can name a case where discovery gets it wrong.

B. Fix the jsii codegen. Change the emitted check from "x" in p to p.x !== undefined, so { x: undefined } stops warning. Kills a whole class of false positives across every CDK module (any spread or ternary over an optional deprecated prop). But it needs a jsii release plus a CDK bump, and it would not silence policyResource: this, which is a genuine deprecated-prop use. Worth raising upstream on its own merits, as a complement to #38399 rather than a substitute.

Actions for us

• Confirm against latest aws-cdk-lib / check for an existing upstream issue — confirmed present on upstream main; #37221 exists
• File upstream if not — not needed, #37221 + PR #38399 already cover it
• README note — recommend against, at least as worded. The warnings have nothing to do with tableGrants.*, so documenting them there misleads. If we want something, it belongs next to TableV2Builder and should say the warnings fire on table construction and are fixed by #38399.

No change to ComposureCDK is indicated — the original conclusion holds, and the call sites in packages/dynamodb/src/grants.ts are correct. The only lever available before #38399 lands is JSII_DEPRECATED=quiet, which suppresses all deprecation warnings globally; I would not bake that into anything consumers inherit.

Not verified

framework-integ has ~10 integ.dynamodb-v2.* tests and runs with JSII_DEPRECATED=fail, so on the face of it those should already throw on re-synth. Either that is live upstream CI breakage or integ-runner's default path does not re-synth. Settling it needs a full yarn install + build of the CDK repo, which I did not run.

---

Generated by Claude Code