@kensio/yulin 1.21.12 → 1.21.14

package/dist/service/iam/authorize/match/condition/string/sim-iam-scalar-string-condition-operator.d.ts

@@ -7,7 +7,10 @@ import type { SimIamConditionOperator } from "../sim-iam-condition-operator.js";
  * scalar or an array, with multiple policy values using OR semantics.
  */
 export declare abstract class SimIamScalarStringConditionOperator implements SimIamConditionOperator {
-    readonly matchesAbsentKey = false;
+    /**
+     * Answer for a request carrying no value for the key.
+     */
+    matchesAbsentKey(): boolean;
     /**
      * Check whether a given value matches the expected value.
      */

package/dist/service/iam/authorize/match/condition/string/sim-iam-scalar-string-condition-operator.js

@@ -6,7 +6,12 @@ import { simIamStringValues } from "./sim-iam-string-values.js";
  * scalar or an array, with multiple policy values using OR semantics.
  */
 export class SimIamScalarStringConditionOperator {
-    matchesAbsentKey = false;
+    /**
+     * Answer for a request carrying no value for the key.
+     */
+    matchesAbsentKey() {
+        return false;
+    }
     /**
      * Check whether a given value matches the expected value.
      */

package/docs/services/dynamodb/README.md

@@ -3637,6 +3637,117 @@ unauthorized caller cannot find out which names are taken.
 in the same way, each against the `dynamodb:` action of its own name. `ListTables` names no table.
 It authorizes against `*`.
 
+### Fine-grained access control with dynamodb:LeadingKeys
+
+`GetItem`, `BatchGetItem`, `Query`, `PutItem`, `UpdateItem`, `DeleteItem` and `BatchWriteItem`
+supply the partition key values they reach as `dynamodb:LeadingKeys`. A policy conditioned on that
+key restricts a caller to the items under particular partition keys. AWS scopes one user of a
+shared table to their own rows this way.
+
+The condition takes the `ForAllValues:` qualifier, as AWS requires for this key. Every partition key
+value the request reaches has to match. A batch or a write naming one item outside the allowed set
+is refused whole, and nothing it asked for is applied.
+
+The same commands, along with `Scan`, supply the top-level attribute names they reach as
+`dynamodb:Attributes`. A name reaches the condition wherever the request writes one, in a
+`ProjectionExpression`, an `UpdateExpression`, a `ConditionExpression`, a `FilterExpression`, a
+`KeyConditionExpression`, and in the `Key` or `Item` a request names outright. A `#` placeholder is
+resolved first, so the policy is matched against the attribute rather than the alias. A nested path
+counts as the attribute it starts at, so `address.city` reaches `address`.
+
+A policy conditioned on `dynamodb:Attributes` has to name every primary key and index key attribute
+of the table alongside the attributes it is restricting, as AWS requires. A request names its key,
+and a policy leaving the key attributes out refuses every request that reads or writes an item.
+
+A request reaching no attribute at all leaves the key out of the condition context, which a
+`ForAllValues:` condition matches. A `Scan` carrying no expression is the case to watch. AWS asks
+for a `Null` check beside such a statement to close it, covered under
+[policy conditions](https://yulinsim.dev/services/iam/#policy-conditions).
+
+```typescript sim-dynamodb-leading-keys
+import { CreateTableCommand, PutItemCommand } from "@aws-sdk/client-dynamodb";
+import { CreateRoleCommand, PutRolePolicyCommand } from "@aws-sdk/client-iam";
+import { SimAws } from "@kensio/yulin";
+
+const simAws = new SimAws();
+const accountId = simAws.defaultAccountId;
+const region = simAws.defaultRegionName;
+
+await simAws.dynamoDb().createTable(
+  new CreateTableCommand({
+    TableName: "OrdersTable",
+    KeySchema: [{ AttributeName: "customerId", KeyType: "HASH" }],
+    AttributeDefinitions: [{ AttributeName: "customerId", AttributeType: "S" }],
+    BillingMode: "PAY_PER_REQUEST",
+  }),
+);
+
+const roleCreation = await simAws.iam().createRole(
+  new CreateRoleCommand({
+    RoleName: "CustomerRole",
+    AssumeRolePolicyDocument: JSON.stringify({
+      Version: "2012-10-17",
+      Statement: {
+        Effect: "Allow",
+        Principal: { AWS: `arn:aws:iam::${accountId}:root` },
+        Action: "sts:AssumeRole",
+      },
+    }),
+  }),
+);
+
+await simAws.iam().putRolePolicy(
+  new PutRolePolicyCommand({
+    RoleName: "CustomerRole",
+    PolicyName: "OwnItemsOnly",
+    PolicyDocument: JSON.stringify({
+      Version: "2012-10-17",
+      Statement: {
+        Effect: "Allow",
+        Action: "dynamodb:PutItem",
+        Resource: `arn:aws:dynamodb:${region}:${accountId}:table/OrdersTable`,
+        Condition: {
+          "ForAllValues:StringEquals": { "dynamodb:LeadingKeys": ["c-1"] },
+        },
+      },
+    }),
+  }),
+);
+
+const caller = { kind: "arn", arn: roleCreation.Role.Arn } as const;
+
+// The customer's own item is written.
+await simAws.dynamoDb().putItem(
+  new PutItemCommand({
+    TableName: "OrdersTable",
+    Item: { customerId: { S: "c-1" }, total: { N: "25" } },
+  }),
+  { caller },
+);
+
+// Another customer's item is refused.
+try {
+  await simAws.dynamoDb().putItem(
+    new PutItemCommand({
+      TableName: "OrdersTable",
+      Item: { customerId: { S: "c-2" }, total: { N: "25" } },
+    }),
+    { caller },
+  );
+} catch (error) {
+  console.log(error instanceof Error ? error.name : "unknown error");
+  // "AccessDenied"
+}
+```
+
+Reading the partition key values needs the table's key schema. The table is found first for that,
+before the caller is authorized against it. A caller with no permission still hears `AccessDenied`
+when the table is missing, and an unauthorized caller cannot find out which table names are taken.
+
+A request carrying no readable partition key value leaves the key out of the condition context. A
+`ForAllValues:` condition matches a request carrying no value for its key, as it does on AWS. The
+condition allows such a request.
+
 A transaction is authorized as the operations it is made of rather than as itself. Each action of a
 `TransactWriteItems` needs `dynamodb:PutItem`, `dynamodb:UpdateItem`, `dynamodb:DeleteItem` or
 `dynamodb:ConditionCheckItem` against the table it names, and each `Get` of a `TransactGetItems`
@@ -3657,6 +3768,11 @@ is written.
   answering with the attributes it projects, and paging with a `LastEvaluatedKey` carrying the index
   key and the table key together. A local secondary index also answers a strongly consistent read,
   and fetches an unprojected attribute from the base table.
+- `dynamodb:LeadingKeys` on `GetItem`, `BatchGetItem`, `Query`, `PutItem`, `UpdateItem`,
+  `DeleteItem` and `BatchWriteItem`, carrying the partition key values the request reaches so a
+  `ForAllValues:` condition can scope a caller to particular items.
+- `dynamodb:Attributes` on those seven and on `Scan`, carrying the top-level attribute names the
+  request reaches, read from every expression it carries and from its `Key` or `Item`.
 - `DescribeTable`, answering with the full table description, by table name or ARN.
 - `ListTables`, ordered by UTF-8 bytes and paged with `Limit` and `ExclusiveStartTableName`.
 - `DeleteTable`, following the table status DynamoDB moves a deleted table through, and refusing a
@@ -3730,6 +3846,17 @@ Arn`, `Fn::GetAtt … StreamArn` and `Fn::GetAtt … TableId` answering. A CDK `
 
 ## Limitations
 
+- `dynamodb:LeadingKeys` and `dynamodb:Attributes` are the DynamoDB condition keys supplied.
+  `dynamodb:Select`, `dynamodb:ReturnValues`, `dynamodb:ReturnConsumedCapacity` and the numbered
+  partition key families are absent from the condition context, and a statement conditioned on one
+  of them matches no request. The transactional operations supply neither key, and are authorized by
+  action and table alone.
+- A partition key value reaches a policy condition as a string for a `S` key and as its digits for
+  an `N` key. A binary partition key has no documented form for the condition key. A request
+  carrying one leaves the value out.
+- A request against a table that is not there is authorized carrying no leading keys, since there is
+  no key schema to read them with. A `ForAllValues:` condition matches such a request. A caller
+  barred only by that condition learns the table is missing.
 - The document client's PartiQL Commands go unconverted, because PartiQL is an operation this
   simulation lacks yet. `ExecuteStatementCommand`, `BatchExecuteStatementCommand` and
   `ExecuteTransactionCommand` are refused by name, never half converted.

package/docs/services/iam/README.md

@@ -236,7 +236,7 @@ repository that still says it is there.
 ## Policy conditions
 
 Policy statements can carry `Condition` blocks. Sim IAM currently supports the `StringEquals`,
-`StringLike`, `ArnLike`, `ArnEquals` and `NumericLessThanEquals` operators, along with the
+`StringLike`, `ArnLike`, `ArnEquals`, `NumericLessThanEquals` and `Null` operators, along with the
 `ForAllValues:` and `ForAnyValue:` set variants of `StringEquals` and `StringLike`.
 
 The negated operators `StringNotEquals`, `StringNotLike`, `ArnNotEquals` and `ArnNotLike` are
@@ -335,6 +335,23 @@ matches instead, as AWS documents. With no value in the request there is none fo
 to equal. A `ForAnyValue:` operator answers false for an absent key whatever it wraps, because no
 request value is there to satisfy it.
 
+A `ForAllValues:` operator answers true for an absent key, which is also AWS behaviour. Every value
+the request carries matches when it carries none. AWS warns that this leaves a `ForAllValues:`
+`Allow` overly permissive, and asks for a `Null` check with a `false` value beside it. Write the
+guard and sim IAM evaluates it.
+
+`Null` asks whether the request carries a value for a context key rather than comparing one. `"true"`
+matches where the key is absent and `"false"` where it is present. A key carrying an empty string or
+an empty list of values counts as absent, which is the null dataset AWS describes. The two values
+can also be written as JSON booleans. Any other policy value leaves the condition matching nothing.
+
+```json
+"Condition": {
+  "ForAllValues:StringLike": { "dynamodb:LeadingKeys": ["ORDER#*"] },
+  "Null": { "dynamodb:LeadingKeys": "false" }
+}
+```
+
 ### Statements left unevaluated
 
 An operator from outside the list above fails closed. The statement holding it matches nothing, and
@@ -1684,8 +1701,11 @@ Sim IAM models the policy behaviour that multi-service tests most commonly need.
 - Only the condition operators listed above are supported. A statement using any other operator
   fails closed, matching no request. `decision.unevaluatedStatements` names those statements, and a
   test can assert that a decision was reached over policies read in full
-- A positive `ForAllValues:` condition fails to match a request carrying no value for the key, and
-  fails to match an empty value set. AWS matches both, and the negated form here matches both
+- The `...IfExists` operator suffix is absent. AWS reads it as the sibling of `Null`, treating a
+  condition on a key the request leaves out as true. A statement using it fails closed here
+- A positive `ForAllValues:` condition fails to match an empty value set, where AWS matches one. An
+  absent context key matches, as it does on AWS. A service here leaves a key out where the request
+  carries no value for it, and the empty set is reached only by a caller passing one to `authorize`
 - Signature age is deliberately not enforced. `X-Amz-Date` must be present, well formed, and agree
   with the credential scope date, but is never compared to a clock. A client stamping real time can
   therefore reach a simulation keeping a different one. Session expiry _is_ enforced, against

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kensio/yulin",
-  "version": "1.21.12",
+  "version": "1.21.14",
   "description": "AWS system behaviour simulation for isolated unit testing",
   "repository": "https://github.com/KensioSoftware/yulin",
   "homepage": "https://yulinsim.dev/",
@@ -290,7 +290,7 @@
     "conventional-changelog-conventionalcommits": "9.3.1",
     "esbuild": "^0.28.2",
     "eslint": "^10.8.0",
-    "eslint-plugin-jsdoc": "^63.3.2",
+    "eslint-plugin-jsdoc": "^64.0.1",
     "eslint-plugin-no-secrets": "^2.3.3",
     "eslint-plugin-security": "^4.0.1",
     "eslint-plugin-unicorn": "^73.0.0",