@kensio/yulin 1.21.5 → 1.21.6

package/docs/services/dynamodb/README.md

@@ -2443,6 +2443,123 @@ console.log(output.Responses[1]); // {}
 That is the difference from `BatchGetItem`, which leaves a missing item out of its answer
 altogether. Here the answers stay lined up with the Gets that asked for them.
 
+### Transactions through the document client
+
+`TransactWriteCommand` and `TransactGetCommand` from `@aws-sdk/lib-dynamodb` reach the same two
+operations. Every action's `Item`, `Key` and `ExpressionAttributeValues` are converted on the way in,
+and the `Item` of each `Responses` entry on the way out.
+
+```typescript sim-dynamodb-document-transactions
+/**
+ * Writing an order and the claim on its code together, in plain JavaScript.
+ */
+
+import { CreateTableCommand, DynamoDBClient } from "@aws-sdk/client-dynamodb";
+import {
+  DynamoDBDocumentClient,
+  TransactGetCommand,
+  TransactWriteCommand,
+} from "@aws-sdk/lib-dynamodb";
+
+import { SimSdk } from "@kensio/yulin/sdk";
+
+using simSdk = new SimSdk();
+
+const documents = DynamoDBDocumentClient.from(
+  new DynamoDBClient({ region: "eu-west-2" }),
+);
+simSdk.intercept(documents);
+
+for (const [tableName, keyName] of [
+  ["OrdersTable", "orderId"],
+  ["ClaimsTable", "code"],
+] as const) {
+  await documents.send(
+    new CreateTableCommand({
+      TableName: tableName,
+      KeySchema: [{ AttributeName: keyName, KeyType: "HASH" }],
+      AttributeDefinitions: [{ AttributeName: keyName, AttributeType: "S" }],
+      BillingMode: "PAY_PER_REQUEST",
+    }),
+  );
+}
+await simSdk.simAws.backgroundTasksComplete();
+
+const claim = {
+  TableName: "ClaimsTable",
+  ConditionExpression: "attribute_not_exists(code)",
+};
+
+// The order and the claim on its code go in together.
+await documents.send(
+  new TransactWriteCommand({
+    TransactItems: [
+      {
+        Put: {
+          TableName: "OrdersTable",
+          Item: { orderId: "order-1", total: 42, lines: [{ sku: "widget" }] },
+        },
+      },
+      { Put: { ...claim, Item: { code: "ABC123", orderId: "order-1" } } },
+    ],
+  }),
+);
+
+const read = await documents.send(
+  new TransactGetCommand({
+    TransactItems: [
+      { Get: { TableName: "OrdersTable", Key: { orderId: "order-1" } } },
+      { Get: { TableName: "ClaimsTable", Key: { code: "ABC123" } } },
+    ],
+  }),
+);
+
+const lines = read.Responses?.[0]?.Item?.["lines"] as { sku: string }[];
+console.log(lines[0]?.sku); // widget
+console.log(read.Responses?.[1]?.Item?.["orderId"]); // order-1
+
+// A second order wanting the same code loses the claim, and loses the order
+// with it.
+try {
+  await documents.send(
+    new TransactWriteCommand({
+      TransactItems: [
+        {
+          Put: {
+            TableName: "OrdersTable",
+            Item: { orderId: "order-2", total: 7 },
+          },
+        },
+        { Put: { ...claim, Item: { code: "ABC123", orderId: "order-2" } } },
+      ],
+    }),
+  );
+} catch (error) {
+  const cancelled = error as {
+    name: string;
+    CancellationReasons?: { Code: string }[];
+  };
+
+  console.log(cancelled.name); // "TransactionCanceledException"
+  console.log(cancelled.CancellationReasons?.map((reason) => reason.Code));
+  // ["None", "ConditionalCheckFailed"]
+}
+
+const second = await documents.send(
+  new TransactGetCommand({
+    TransactItems: [
+      { Get: { TableName: "OrdersTable", Key: { orderId: "order-2" } } },
+    ],
+  }),
+);
+
+console.log(second.Responses?.[0]); // {}
+```
+
+`CancellationReasons` arrive as the low-level Command reports them. There is one per action, in
+`TransactItems` order. A reason's `Item` holds AttributeValues, because a cancelled transaction is
+thrown, and the real document client converts nothing on the way out of a transactional write.
+
 ## Expiring items with time to live
 
 `UpdateTimeToLive` names the attribute a table expires items by, and `DescribeTimeToLive` reports
@@ -2930,8 +3047,11 @@ console.log(tags.has("priority")); // true
 ```
 
 `PutCommand`, `GetCommand`, `DeleteCommand`, `UpdateCommand`, `QueryCommand`, `ScanCommand`,
-`BatchWriteCommand` and `BatchGetCommand` are converted. A document Command with no route here, such
-as `TransactWriteCommand`, is refused by name before anything tries to convert its values.
+`BatchWriteCommand`, `BatchGetCommand`, `TransactWriteCommand` and `TransactGetCommand` are
+converted. The two transactional ones have
+[a section of their own](#transactions-through-the-document-client). A document Command with no route
+here, such as the PartiQL `ExecuteStatementCommand`, is refused by name before anything tries to
+convert its values.
 
 Intercept the document client itself. `DynamoDBDocumentClient.from(client)` builds a separate object
 outside the `DynamoDBClient` class, so intercepting the base client leaves Commands sent through the
@@ -3621,15 +3741,15 @@ Arn`, `Fn::GetAtt … StreamArn` and `Fn::GetAtt … TableId` answering. A CDK `
 - SDK interception, and an intercepted `DynamoDBClient` or `DynamoDBStreamsClient` reaches the
   simulation.
 - The `@aws-sdk/lib-dynamodb` document client, with `PutCommand`, `GetCommand`, `DeleteCommand`,
-  `UpdateCommand`, `QueryCommand`, `ScanCommand`, `BatchWriteCommand` and `BatchGetCommand`
-  converting native JavaScript values on the way in and out, and `paginateQuery` and `paginateScan`
-  paging through a simulated table.
+  `UpdateCommand`, `QueryCommand`, `ScanCommand`, `BatchWriteCommand`, `BatchGetCommand`,
+  `TransactWriteCommand` and `TransactGetCommand` converting native JavaScript values on the way in
+  and out, and `paginateQuery` and `paginateScan` paging through a simulated table.
 
 ## Limitations
 
-- The document client's transaction and PartiQL Commands go unconverted. PartiQL is an operation
-  this simulation lacks yet. The transactions are simulated as operations, so only the document form
-  of them is missing. Both are refused by name, never half converted.
+- 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.
 - A document client's translate config goes unread. The marshalling options it was built with do not
   apply. See [the SDK docs](https://yulinsim.dev/sdk/#limitations).
 - `Expected`, `ConditionalOperator`, `AttributeUpdates`, `KeyConditions`, `QueryFilter` and

package/docs/services/iam/README.md

@@ -260,6 +260,11 @@ from the resolved caller and `aws:RequestedRegion` from the Region the request w
 service supplies under either name is overwritten by the derived one. Context-key names are matched
 case-insensitively, while string values remain case-sensitive.
 
+IAM's own requests carry two service keys. A Role handed to a service carries
+[`iam:PassedToService`](#passing-a-role-to-a-service), and a `CreateRole` request carries the
+boundary it declares as
+[`iam:PermissionsBoundary`](#creating-a-role-under-a-permissions-boundary).
+
 Every simulated service supplies its own Region. A policy conditioned on `aws:RequestedRegion`
 therefore sees the Region of the service that handled the request, whichever Region the caller was
 in, and a CloudFormation deployment carries the Region of the Stack it is deploying. IAM, CloudFront
@@ -1045,6 +1050,115 @@ await simAws.backgroundTasksComplete();
 A request naming no caller is decided as the Account root, which may pass any Role. A test that never
 mentions IAM keeps working.
 
+## Creating a Role under a permissions boundary
+
+An account that requires every Role to carry a permissions boundary allows `iam:CreateRole` only
+under `StringEquals` on `iam:PermissionsBoundary`. Its CloudFormation execution policy is written
+that way, and the CDK `PermissionsBoundary.fromName(...)` aspect puts the boundary ARN on every Role
+the app synthesizes. A `CreateRoleCommand` carrying `PermissionsBoundary` supplies the key, and
+`AWS::IAM::Role` supplies it from the template property of the same name.
+
+A request that leaves the property out leaves the key unset. A positive operator over an unset key
+matches nothing, and the guard refuses the Role. A request naming some other policy is refused the
+same way. A test can assert both refusals, and that is what makes the policy worth standing up as a
+deploy Role.
+
+`CreateRole` and `GetRole` then describe the boundary the Role carries, in the attachment shape IAM
+answers with (`PermissionsBoundaryType` and `PermissionsBoundaryArn`). `ListRoles` leaves the field
+out, as IAM does, and points a caller at `GetRole`. The boundary is not yet evaluated as a policy
+source of its own, and does not narrow what the Role may then do
+(see [Limitations](#limitations)).
+
+```typescript sim-iam-permissions-boundary
+/**
+ * Deploying into an account that requires a permissions boundary.
+ */
+
+import { GetRoleCommand } from "@aws-sdk/client-iam";
+import { SimAws } from "@kensio/yulin";
+
+const simAws = new SimAws({ defaultAccountId: "123456789012" });
+const boundaryArn = "arn:aws:iam::123456789012:policy/DeveloperBoundary";
+
+const deployer = await simAws.iam().makeDeployRole({
+  roleName: "cfn-exec",
+  policyDocument: {
+    Version: "2012-10-17",
+    Statement: [
+      {
+        Effect: "Allow",
+        Action: "iam:CreateRole",
+        Resource: "*",
+        Condition: {
+          StringEquals: { "iam:PermissionsBoundary": boundaryArn },
+        },
+      },
+      {
+        Effect: "Allow",
+        Action: ["cloudformation:*", "iam:PutRolePolicy", "iam:PassRole"],
+        Resource: "*",
+      },
+    ],
+  },
+});
+
+const jobRoleTrust = {
+  Version: "2012-10-17",
+  Statement: {
+    Effect: "Allow",
+    Action: "sts:AssumeRole",
+    Principal: { Service: "lambda.amazonaws.com" },
+  },
+};
+
+const stack = await simAws.cloudFormation().deployTemplate({
+  stackName: "guarded-stack",
+  template: {
+    Resources: {
+      JobRole: {
+        Type: "AWS::IAM::Role",
+        Properties: {
+          RoleName: "JobRole",
+          PermissionsBoundary: boundaryArn,
+          AssumeRolePolicyDocument: jobRoleTrust,
+        },
+      },
+    },
+  },
+  caller: deployer,
+});
+
+// CREATE_COMPLETE
+console.log(stack.getResource("JobRole")?.status);
+
+const roleRead = await simAws
+  .iam()
+  .getRole(new GetRoleCommand({ RoleName: "JobRole" }));
+
+// arn:aws:iam::123456789012:policy/DeveloperBoundary
+console.log(roleRead.Role.PermissionsBoundary?.PermissionsBoundaryArn);
+
+try {
+  await simAws.cloudFormation().deployTemplate({
+    stackName: "unguarded-stack",
+    template: {
+      Resources: {
+        BareRole: {
+          Type: "AWS::IAM::Role",
+          Properties: {
+            RoleName: "BareRole",
+            AssumeRolePolicyDocument: jobRoleTrust,
+          },
+        },
+      },
+    },
+    caller: deployer,
+  });
+} catch (error) {
+  console.error("A Role declaring no boundary was refused", error);
+}
+```
+
 ## A Role for a CloudFormation deployment
 
 `makeDeployRole(...)` creates a Role from a policy document and hands back a caller. Pass it as
@@ -1241,6 +1355,11 @@ the logical ID when it is omitted, and inline `Policies` declared on a Role are
 Role's inline policies. The `ReadOnlyAccess` policy above is attached to `LambdaExecutionRole`.
 Authorization for that Role reads the policy document the template gave it.
 
+A Role's `PermissionsBoundary` reaches the authorization decision the deployment is made under, and
+is recorded on the Role it names.
+[Creating a Role under a permissions boundary](#creating-a-role-under-a-permissions-boundary) covers
+the guard it exists for.
+
 ### Users
 
 An `AWS::IAM::User` creates a User in the Stack's Account. `UserName` names it and falls back to the
@@ -1534,6 +1653,8 @@ Sim IAM currently supports:
 - IAM authorization at simulated service boundaries, such as Route53 actions
 - `iam:PassRole` authorization of a Role handed to simulated Lambda, Scheduler, EventBridge, Step
   Functions, ECS or Firehose, with `iam:PassedToService` supplied
+- `iam:CreateRole` authorization against `iam:PermissionsBoundary`, from the `PermissionsBoundary`
+  a request or an `AWS::IAM::Role` declares
 - Resolving the caller of an HTTP request, from an `x-sim-aws-caller` header or a verified SigV4
   signature, defaulting to anonymous, and the resource it is made on behalf of from
   `x-sim-aws-source-arn` and `x-sim-aws-source-account`
@@ -1551,8 +1672,10 @@ Sim IAM models the policy behaviour that multi-service tests most commonly need.
 
 - Groups are absent. An `AWS::IAM::User` naming one fails, and an `AWS::IAM::Policy` naming one
   fails too
-- Permissions boundaries and session policies are not evaluated. Service control policies are, and
-  are attached through [simulated Organizations](https://yulinsim.dev/services/organizations/ "Simulated Organizations service control policies usage docs")
+- Permissions boundaries and session policies are not evaluated. A boundary a `CreateRole` request
+  declares is authorized against `iam:PermissionsBoundary` and described by `GetRole`, and stops
+  there. Service control policies are evaluated, and are attached through
+  [simulated Organizations](https://yulinsim.dev/services/organizations/ "Simulated Organizations service control policies usage docs")
 - Managed Policies have a single version, and the policy version commands are absent
 - A policy document is measured against IAM's character limit one document at a time. The
   20,480-character cap on the sum of a User's inline policies is absent, and so is the cap on how

package/docs/services/route53/README.md

@@ -139,6 +139,17 @@ Register the zone yourself when a test depends on its name, such as one listing
 when its name is a suffix of no record the stack holds. A registered zone keeps the name it was
 given, and its records are stored under the name you chose.
 
+### A lookup that never resolved
+
+`HostedZone.fromLookup` needs credentials for the account holding the zone, or a `cdk.context.json`
+holding a previous lookup's answer. With neither, CDK synthesizes the literal `DUMMY` as the Hosted
+Zone ID and writes it into every `AWS::Route53::RecordSet` in the template. Deploying that template
+gives `InvalidInput`, naming `DUMMY` as the stand-in and pointing back at the synth.
+
+Run `cdk synth` with credentials for that account, or commit the `cdk.context.json` a resolved
+lookup writes. Either one puts the real Hosted Zone ID in the template, and the zone is then
+registered on demand like any other looked-up zone.
+
 ## Creating records
 
 Use `ChangeResourceRecordSetsCommand` to add records to a Hosted Zone.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kensio/yulin",
-  "version": "1.21.5",
+  "version": "1.21.6",
   "description": "AWS system behaviour simulation for isolated unit testing",
   "repository": "https://github.com/KensioSoftware/yulin",
   "homepage": "https://yulinsim.dev/",

package/dist/service/iam/cfn/sim-cfn-iam-optional-string.js

@@ -1,17 +0,0 @@
-/**
- * Read a string property an IAM Resource may leave out.
- *
- * A Role and a User read most of their own properties this way, and both
- * refuse a non-string the same way, naming the Resource type the template
- * declared.
- */
-export function simCfnIamOptionalString(properties) {
-    const { resourceType, resource, value, label } = properties;
-    if (value === undefined) {
-        return undefined;
-    }
-    if (typeof value !== "string") {
-        throw new TypeError(`Invalid ${resourceType} ${resource.logicalId}: ${label} must be a string`);
-    }
-    return value;
-}