@composurecdk/dynamodb 0.11.2 → 0.12.1

package/README.md

@@ -109,11 +109,14 @@ createFunctionBuilder()
 | `read`       | `GetItem`, `Query`, `Scan`, `BatchGetItem`, … `DescribeTable`            | `Decrypt`, `DescribeKey`                                   |
 | `write`      | `PutItem`, `UpdateItem`, `DeleteItem`, `BatchWriteItem`, `DescribeTable` | `read`'s, plus `Encrypt`, `ReEncrypt*`, `GenerateDataKey*` |
 | `put`        | `PutItem`                                                                | as `write`                                                 |
+| `update`     | `UpdateItem`                                                             | as `write`                                                 |
 | `readWrite`  | `read`'s and `write`'s                                                   | as `write`                                                 |
 | `fullAccess` | `dynamodb:*`                                                             | as `write`                                                 |
 
 `put` is for a write-once store: its grantee may add items but never update or delete them. It leaves out `BatchWriteItem`, which can delete.
 
+`update` is for a grantee that changes existing items but must never delete them — a worker moving a record's status, beside a separate writer granted `put`. IAM cannot stop an `UpdateItem` on a missing key from creating the item, so guard each call with a condition expression such as `attribute_exists(id)`.
+
 Each capability grants the table's customer-managed key, when it has one, in the grantee's identity policy, so a grant stands alone. A key built by [`@composurecdk/kms`](../kms/README.md) keeps CDK's default key policy, which delegates to IAM, so that is enough within the account. Two limits: on a `TableV2` with replicas only the primary Region's key is granted, not a replica's; and a key in another account needs its key policy to allow the grantee.
 
 ## DynamoDB Streams

package/dist/commonjs/grants.d.ts

@@ -25,6 +25,13 @@ export declare const tableGrants: {
      * because it can delete.
      */
     put: (table: Resolvable<ITable>) => Grant<IGrantable>;
+    /**
+     * Update existing items, and nothing else (`dynamodb:UpdateItem`) — for a
+     * grantee that changes items but must not create or delete them. An
+     * `UpdateItem` on a missing key creates the item, so pair it with a
+     * condition expression such as `attribute_exists(pk)`.
+     */
+    update: (table: Resolvable<ITable>) => Grant<IGrantable>;
     /** Combined read and write access. */
     readWrite: (table: Resolvable<ITable>) => Grant<IGrantable>;
     /** Full access to the table and its indexes (`dynamodb:*`). */

package/dist/commonjs/grants.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"grants.d.ts","sourceRoot":"","sources":["../../src/grants.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,0BAA0B,CAAC;AACvD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,qBAAqB,CAAC;AACtD,OAAO,EAAE,KAAK,KAAK,EAAY,KAAK,UAAU,EAAE,MAAM,oBAAoB,CAAC;AAsB3E;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,WAAW;IACtB,4DAA4D;kBA/BpD,UAAU,CAAC,MAAM,CAAC,KAAG,KAAK,CAAC,UAAU,CAAC;IAmC9C,wEAAwE;mBAnChE,UAAU,CAAC,MAAM,CAAC,KAAG,KAAK,CAAC,UAAU,CAAC;IAuC9C;;;;OAIG;iBA3CK,UAAU,CAAC,MAAM,CAAC,KAAG,KAAK,CAAC,UAAU,CAAC;IAgD9C,sCAAsC;uBAhD9B,UAAU,CAAC,MAAM,CAAC,KAAG,KAAK,CAAC,UAAU,CAAC;IAoD9C,+DAA+D;wBApDvD,UAAU,CAAC,MAAM,CAAC,KAAG,KAAK,CAAC,UAAU,CAAC;CAwD/C,CAAC"}
+{"version":3,"file":"grants.d.ts","sourceRoot":"","sources":["../../src/grants.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,0BAA0B,CAAC;AACvD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,qBAAqB,CAAC;AACtD,OAAO,EAAE,KAAK,KAAK,EAAY,KAAK,UAAU,EAAE,MAAM,oBAAoB,CAAC;AAgC3E;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,WAAW;IACtB,4DAA4D;kBAzCpD,UAAU,CAAC,MAAM,CAAC,KAAG,KAAK,CAAC,UAAU,CAAC;IA6C9C,wEAAwE;mBA7ChE,UAAU,CAAC,MAAM,CAAC,KAAG,KAAK,CAAC,UAAU,CAAC;IAiD9C;;;;OAIG;iBArDK,UAAU,CAAC,MAAM,CAAC,KAAG,KAAK,CAAC,UAAU,CAAC;IAuD9C;;;;;OAKG;oBA5DK,UAAU,CAAC,MAAM,CAAC,KAAG,KAAK,CAAC,UAAU,CAAC;IA8D9C,sCAAsC;uBA9D9B,UAAU,CAAC,MAAM,CAAC,KAAG,KAAK,CAAC,UAAU,CAAC;IAkE9C,+DAA+D;wBAlEvD,UAAU,CAAC,MAAM,CAAC,KAAG,KAAK,CAAC,UAAU,CAAC;CAsE/C,CAAC"}

package/dist/commonjs/grants.js

@@ -17,6 +17,14 @@ const KEY_WRITE_ACTIONS = [
     "kms:ReEncrypt*",
     "kms:GenerateDataKey*",
 ];
+/**
+ * A capability granting `action` alone, via `ITable.grant`, plus the key
+ * actions `write` grants — which `ITable.grant` does not add itself.
+ */
+const itemWrite = (action) => capability((table, grantee) => {
+    table.grant(grantee, action);
+    table.encryptionKey?.grant(grantee, ...KEY_WRITE_ACTIONS);
+});
 /**
  * Consumer-side grant helpers for a DynamoDB table. Pass one to a grantee
  * builder's `grant(...)` — e.g.
@@ -44,10 +52,14 @@ exports.tableGrants = {
      * whose writer must not update or delete. `BatchWriteItem` is left out
      * because it can delete.
      */
-    put: capability((table, grantee) => {
-        table.grant(grantee, "dynamodb:PutItem");
-        table.encryptionKey?.grant(grantee, ...KEY_WRITE_ACTIONS);
-    }),
+    put: itemWrite("dynamodb:PutItem"),
+    /**
+     * Update existing items, and nothing else (`dynamodb:UpdateItem`) — for a
+     * grantee that changes items but must not create or delete them. An
+     * `UpdateItem` on a missing key creates the item, so pair it with a
+     * condition expression such as `attribute_exists(pk)`.
+     */
+    update: itemWrite("dynamodb:UpdateItem"),
     /** Combined read and write access. */
     readWrite: capability((table, grantee) => {
         table.grantReadWriteData(grantee);

package/dist/commonjs/grants.js.map

@@ -1 +1 @@
-{"version":3,"file":"grants.js","sourceRoot":"","sources":["../../src/grants.ts"],"names":[],"mappings":";;;AAEA,6CAA2E;AAE3E,8DAA8D;AAC9D,MAAM,UAAU,GACd,CAAC,KAAmD,EAAE,EAAE,CACxD,CAAC,KAAyB,EAAqB,EAAE,CAC/C,IAAA,eAAQ,EAAC,KAAK,EAAE,KAAK,CAAC,CAAC;AAE3B;;;;;GAKG;AACH,MAAM,iBAAiB,GAAG;IACxB,aAAa;IACb,iBAAiB;IACjB,aAAa;IACb,gBAAgB;IAChB,sBAAsB;CACvB,CAAC;AAEF;;;;;;;;;;;;GAYG;AACU,QAAA,WAAW,GAAG;IACzB,4DAA4D;IAC5D,IAAI,EAAE,UAAU,CAAC,CAAC,KAAK,EAAE,OAAO,EAAE,EAAE;QAClC,KAAK,CAAC,aAAa,CAAC,OAAO,CAAC,CAAC;IAC/B,CAAC,CAAC;IACF,wEAAwE;IACxE,KAAK,EAAE,UAAU,CAAC,CAAC,KAAK,EAAE,OAAO,EAAE,EAAE;QACnC,KAAK,CAAC,cAAc,CAAC,OAAO,CAAC,CAAC;IAChC,CAAC,CAAC;IACF;;;;OAIG;IACH,GAAG,EAAE,UAAU,CAAC,CAAC,KAAK,EAAE,OAAO,EAAE,EAAE;QACjC,KAAK,CAAC,KAAK,CAAC,OAAO,EAAE,kBAAkB,CAAC,CAAC;QACzC,KAAK,CAAC,aAAa,EAAE,KAAK,CAAC,OAAO,EAAE,GAAG,iBAAiB,CAAC,CAAC;IAC5D,CAAC,CAAC;IACF,sCAAsC;IACtC,SAAS,EAAE,UAAU,CAAC,CAAC,KAAK,EAAE,OAAO,EAAE,EAAE;QACvC,KAAK,CAAC,kBAAkB,CAAC,OAAO,CAAC,CAAC;IACpC,CAAC,CAAC;IACF,+DAA+D;IAC/D,UAAU,EAAE,UAAU,CAAC,CAAC,KAAK,EAAE,OAAO,EAAE,EAAE;QACxC,KAAK,CAAC,eAAe,CAAC,OAAO,CAAC,CAAC;IACjC,CAAC,CAAC;CACH,CAAC"}
+{"version":3,"file":"grants.js","sourceRoot":"","sources":["../../src/grants.ts"],"names":[],"mappings":";;;AAEA,6CAA2E;AAE3E,8DAA8D;AAC9D,MAAM,UAAU,GACd,CAAC,KAAmD,EAAE,EAAE,CACxD,CAAC,KAAyB,EAAqB,EAAE,CAC/C,IAAA,eAAQ,EAAC,KAAK,EAAE,KAAK,CAAC,CAAC;AAE3B;;;;;GAKG;AACH,MAAM,iBAAiB,GAAG;IACxB,aAAa;IACb,iBAAiB;IACjB,aAAa;IACb,gBAAgB;IAChB,sBAAsB;CACvB,CAAC;AAEF;;;GAGG;AACH,MAAM,SAAS,GAAG,CAAC,MAAc,EAAE,EAAE,CACnC,UAAU,CAAC,CAAC,KAAK,EAAE,OAAO,EAAE,EAAE;IAC5B,KAAK,CAAC,KAAK,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC;IAC7B,KAAK,CAAC,aAAa,EAAE,KAAK,CAAC,OAAO,EAAE,GAAG,iBAAiB,CAAC,CAAC;AAC5D,CAAC,CAAC,CAAC;AAEL;;;;;;;;;;;;GAYG;AACU,QAAA,WAAW,GAAG;IACzB,4DAA4D;IAC5D,IAAI,EAAE,UAAU,CAAC,CAAC,KAAK,EAAE,OAAO,EAAE,EAAE;QAClC,KAAK,CAAC,aAAa,CAAC,OAAO,CAAC,CAAC;IAC/B,CAAC,CAAC;IACF,wEAAwE;IACxE,KAAK,EAAE,UAAU,CAAC,CAAC,KAAK,EAAE,OAAO,EAAE,EAAE;QACnC,KAAK,CAAC,cAAc,CAAC,OAAO,CAAC,CAAC;IAChC,CAAC,CAAC;IACF;;;;OAIG;IACH,GAAG,EAAE,SAAS,CAAC,kBAAkB,CAAC;IAClC;;;;;OAKG;IACH,MAAM,EAAE,SAAS,CAAC,qBAAqB,CAAC;IACxC,sCAAsC;IACtC,SAAS,EAAE,UAAU,CAAC,CAAC,KAAK,EAAE,OAAO,EAAE,EAAE;QACvC,KAAK,CAAC,kBAAkB,CAAC,OAAO,CAAC,CAAC;IACpC,CAAC,CAAC;IACF,+DAA+D;IAC/D,UAAU,EAAE,UAAU,CAAC,CAAC,KAAK,EAAE,OAAO,EAAE,EAAE;QACxC,KAAK,CAAC,eAAe,CAAC,OAAO,CAAC,CAAC;IACjC,CAAC,CAAC;CACH,CAAC"}

package/dist/esm/grants.d.ts

@@ -25,6 +25,13 @@ export declare const tableGrants: {
      * because it can delete.
      */
     put: (table: Resolvable<ITable>) => Grant<IGrantable>;
+    /**
+     * Update existing items, and nothing else (`dynamodb:UpdateItem`) — for a
+     * grantee that changes items but must not create or delete them. An
+     * `UpdateItem` on a missing key creates the item, so pair it with a
+     * condition expression such as `attribute_exists(pk)`.
+     */
+    update: (table: Resolvable<ITable>) => Grant<IGrantable>;
     /** Combined read and write access. */
     readWrite: (table: Resolvable<ITable>) => Grant<IGrantable>;
     /** Full access to the table and its indexes (`dynamodb:*`). */

package/dist/esm/grants.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"grants.d.ts","sourceRoot":"","sources":["../../src/grants.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,0BAA0B,CAAC;AACvD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,qBAAqB,CAAC;AACtD,OAAO,EAAE,KAAK,KAAK,EAAY,KAAK,UAAU,EAAE,MAAM,oBAAoB,CAAC;AAsB3E;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,WAAW;IACtB,4DAA4D;kBA/BpD,UAAU,CAAC,MAAM,CAAC,KAAG,KAAK,CAAC,UAAU,CAAC;IAmC9C,wEAAwE;mBAnChE,UAAU,CAAC,MAAM,CAAC,KAAG,KAAK,CAAC,UAAU,CAAC;IAuC9C;;;;OAIG;iBA3CK,UAAU,CAAC,MAAM,CAAC,KAAG,KAAK,CAAC,UAAU,CAAC;IAgD9C,sCAAsC;uBAhD9B,UAAU,CAAC,MAAM,CAAC,KAAG,KAAK,CAAC,UAAU,CAAC;IAoD9C,+DAA+D;wBApDvD,UAAU,CAAC,MAAM,CAAC,KAAG,KAAK,CAAC,UAAU,CAAC;CAwD/C,CAAC"}
+{"version":3,"file":"grants.d.ts","sourceRoot":"","sources":["../../src/grants.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,0BAA0B,CAAC;AACvD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,qBAAqB,CAAC;AACtD,OAAO,EAAE,KAAK,KAAK,EAAY,KAAK,UAAU,EAAE,MAAM,oBAAoB,CAAC;AAgC3E;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,WAAW;IACtB,4DAA4D;kBAzCpD,UAAU,CAAC,MAAM,CAAC,KAAG,KAAK,CAAC,UAAU,CAAC;IA6C9C,wEAAwE;mBA7ChE,UAAU,CAAC,MAAM,CAAC,KAAG,KAAK,CAAC,UAAU,CAAC;IAiD9C;;;;OAIG;iBArDK,UAAU,CAAC,MAAM,CAAC,KAAG,KAAK,CAAC,UAAU,CAAC;IAuD9C;;;;;OAKG;oBA5DK,UAAU,CAAC,MAAM,CAAC,KAAG,KAAK,CAAC,UAAU,CAAC;IA8D9C,sCAAsC;uBA9D9B,UAAU,CAAC,MAAM,CAAC,KAAG,KAAK,CAAC,UAAU,CAAC;IAkE9C,+DAA+D;wBAlEvD,UAAU,CAAC,MAAM,CAAC,KAAG,KAAK,CAAC,UAAU,CAAC;CAsE/C,CAAC"}

package/dist/esm/grants.js

@@ -14,6 +14,14 @@ const KEY_WRITE_ACTIONS = [
     "kms:ReEncrypt*",
     "kms:GenerateDataKey*",
 ];
+/**
+ * A capability granting `action` alone, via `ITable.grant`, plus the key
+ * actions `write` grants — which `ITable.grant` does not add itself.
+ */
+const itemWrite = (action) => capability((table, grantee) => {
+    table.grant(grantee, action);
+    table.encryptionKey?.grant(grantee, ...KEY_WRITE_ACTIONS);
+});
 /**
  * Consumer-side grant helpers for a DynamoDB table. Pass one to a grantee
  * builder's `grant(...)` — e.g.
@@ -41,10 +49,14 @@ export const tableGrants = {
      * whose writer must not update or delete. `BatchWriteItem` is left out
      * because it can delete.
      */
-    put: capability((table, grantee) => {
-        table.grant(grantee, "dynamodb:PutItem");
-        table.encryptionKey?.grant(grantee, ...KEY_WRITE_ACTIONS);
-    }),
+    put: itemWrite("dynamodb:PutItem"),
+    /**
+     * Update existing items, and nothing else (`dynamodb:UpdateItem`) — for a
+     * grantee that changes items but must not create or delete them. An
+     * `UpdateItem` on a missing key creates the item, so pair it with a
+     * condition expression such as `attribute_exists(pk)`.
+     */
+    update: itemWrite("dynamodb:UpdateItem"),
     /** Combined read and write access. */
     readWrite: capability((table, grantee) => {
         table.grantReadWriteData(grantee);

package/dist/esm/grants.js.map

@@ -1 +1 @@
-{"version":3,"file":"grants.js","sourceRoot":"","sources":["../../src/grants.ts"],"names":[],"mappings":"AAEA,OAAO,EAAc,QAAQ,EAAmB,MAAM,oBAAoB,CAAC;AAE3E,8DAA8D;AAC9D,MAAM,UAAU,GACd,CAAC,KAAmD,EAAE,EAAE,CACxD,CAAC,KAAyB,EAAqB,EAAE,CAC/C,QAAQ,CAAC,KAAK,EAAE,KAAK,CAAC,CAAC;AAE3B;;;;;GAKG;AACH,MAAM,iBAAiB,GAAG;IACxB,aAAa;IACb,iBAAiB;IACjB,aAAa;IACb,gBAAgB;IAChB,sBAAsB;CACvB,CAAC;AAEF;;;;;;;;;;;;GAYG;AACH,MAAM,CAAC,MAAM,WAAW,GAAG;IACzB,4DAA4D;IAC5D,IAAI,EAAE,UAAU,CAAC,CAAC,KAAK,EAAE,OAAO,EAAE,EAAE;QAClC,KAAK,CAAC,aAAa,CAAC,OAAO,CAAC,CAAC;IAC/B,CAAC,CAAC;IACF,wEAAwE;IACxE,KAAK,EAAE,UAAU,CAAC,CAAC,KAAK,EAAE,OAAO,EAAE,EAAE;QACnC,KAAK,CAAC,cAAc,CAAC,OAAO,CAAC,CAAC;IAChC,CAAC,CAAC;IACF;;;;OAIG;IACH,GAAG,EAAE,UAAU,CAAC,CAAC,KAAK,EAAE,OAAO,EAAE,EAAE;QACjC,KAAK,CAAC,KAAK,CAAC,OAAO,EAAE,kBAAkB,CAAC,CAAC;QACzC,KAAK,CAAC,aAAa,EAAE,KAAK,CAAC,OAAO,EAAE,GAAG,iBAAiB,CAAC,CAAC;IAC5D,CAAC,CAAC;IACF,sCAAsC;IACtC,SAAS,EAAE,UAAU,CAAC,CAAC,KAAK,EAAE,OAAO,EAAE,EAAE;QACvC,KAAK,CAAC,kBAAkB,CAAC,OAAO,CAAC,CAAC;IACpC,CAAC,CAAC;IACF,+DAA+D;IAC/D,UAAU,EAAE,UAAU,CAAC,CAAC,KAAK,EAAE,OAAO,EAAE,EAAE;QACxC,KAAK,CAAC,eAAe,CAAC,OAAO,CAAC,CAAC;IACjC,CAAC,CAAC;CACH,CAAC"}
+{"version":3,"file":"grants.js","sourceRoot":"","sources":["../../src/grants.ts"],"names":[],"mappings":"AAEA,OAAO,EAAc,QAAQ,EAAmB,MAAM,oBAAoB,CAAC;AAE3E,8DAA8D;AAC9D,MAAM,UAAU,GACd,CAAC,KAAmD,EAAE,EAAE,CACxD,CAAC,KAAyB,EAAqB,EAAE,CAC/C,QAAQ,CAAC,KAAK,EAAE,KAAK,CAAC,CAAC;AAE3B;;;;;GAKG;AACH,MAAM,iBAAiB,GAAG;IACxB,aAAa;IACb,iBAAiB;IACjB,aAAa;IACb,gBAAgB;IAChB,sBAAsB;CACvB,CAAC;AAEF;;;GAGG;AACH,MAAM,SAAS,GAAG,CAAC,MAAc,EAAE,EAAE,CACnC,UAAU,CAAC,CAAC,KAAK,EAAE,OAAO,EAAE,EAAE;IAC5B,KAAK,CAAC,KAAK,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC;IAC7B,KAAK,CAAC,aAAa,EAAE,KAAK,CAAC,OAAO,EAAE,GAAG,iBAAiB,CAAC,CAAC;AAC5D,CAAC,CAAC,CAAC;AAEL;;;;;;;;;;;;GAYG;AACH,MAAM,CAAC,MAAM,WAAW,GAAG;IACzB,4DAA4D;IAC5D,IAAI,EAAE,UAAU,CAAC,CAAC,KAAK,EAAE,OAAO,EAAE,EAAE;QAClC,KAAK,CAAC,aAAa,CAAC,OAAO,CAAC,CAAC;IAC/B,CAAC,CAAC;IACF,wEAAwE;IACxE,KAAK,EAAE,UAAU,CAAC,CAAC,KAAK,EAAE,OAAO,EAAE,EAAE;QACnC,KAAK,CAAC,cAAc,CAAC,OAAO,CAAC,CAAC;IAChC,CAAC,CAAC;IACF;;;;OAIG;IACH,GAAG,EAAE,SAAS,CAAC,kBAAkB,CAAC;IAClC;;;;;OAKG;IACH,MAAM,EAAE,SAAS,CAAC,qBAAqB,CAAC;IACxC,sCAAsC;IACtC,SAAS,EAAE,UAAU,CAAC,CAAC,KAAK,EAAE,OAAO,EAAE,EAAE;QACvC,KAAK,CAAC,kBAAkB,CAAC,OAAO,CAAC,CAAC;IACpC,CAAC,CAAC;IACF,+DAA+D;IAC/D,UAAU,EAAE,UAAU,CAAC,CAAC,KAAK,EAAE,OAAO,EAAE,EAAE;QACxC,KAAK,CAAC,eAAe,CAAC,OAAO,CAAC,CAAC;IACjC,CAAC,CAAC;CACH,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@composurecdk/dynamodb",
-  "version": "0.11.2",
+  "version": "0.12.1",
   "description": "Composable DynamoDB table builder with well-architected defaults",
   "repository": {
     "type": "git",
@@ -40,16 +40,16 @@
     }
   },
   "peerDependencies": {
-    "@composurecdk/cloudformation": "^0.11.0",
-    "@composurecdk/cloudwatch": "^0.11.0",
-    "@composurecdk/core": "^0.11.0",
+    "@composurecdk/cloudformation": "^0.12.0",
+    "@composurecdk/cloudwatch": "^0.12.0",
+    "@composurecdk/core": "^0.12.0",
     "aws-cdk-lib": "^2.178.0",
     "constructs": "^10.0.0"
   },
   "devDependencies": {
     "@composurecdk/cdk-testing": "*",
-    "@types/node": "^26.6.5",
-    "aws-cdk-lib": "^2.271.0",
+    "@types/node": "^26.6.6",
+    "aws-cdk-lib": "^2.275.0",
     "constructs": "^10.8.1",
     "typescript": "^6.0.3",
     "vitest": "^5.0.0"