alchemy 2.0.0-beta.30 → 2.0.0-beta.32

package/src/AWS/IAM/VirtualMFADevice.ts

@@ -162,84 +162,104 @@ export const VirtualMFADeviceProvider = () =>
             tags: toTagRecord(tags.Tags),
           };
         }),
-        create: Effect.fn(function* ({ id, news, session }) {
-          const deviceName = yield* toName(id, news);
-          const tags = {
+        reconcile: Effect.fn(function* ({ id, news, output, session }) {
+          const desiredTags = {
             ...(yield* createInternalTags(id)),
             ...news.tags,
           };
-          const created = yield* iam.createVirtualMFADevice({
-            Path: news.path,
-            VirtualMFADeviceName: deviceName,
-            Tags: createTagsList(tags),
-          });
-          if (!created.VirtualMFADevice.SerialNumber) {
-            return yield* Effect.fail(
-              new Error(`createVirtualMFADevice returned no serial number`),
+
+          // Observe — virtual MFA devices have AWS-generated serial
+          // numbers, so we can only locate the existing device when we
+          // already have its serial from a prior output.
+          const observed = output
+            ? yield* readDevice({
+                serialNumber: output.serialNumber,
+                userName: output.userName,
+              })
+            : undefined;
+
+          // Ensure — create the device when missing. The seed and QR
+          // code are only returned on creation, so on adoption the best
+          // we can do is preserve the existing redacted values.
+          let serialNumber = observed?.SerialNumber ?? output?.serialNumber;
+          let base32StringSeed = output?.base32StringSeed;
+          let qrCodePNG = output?.qrCodePNG;
+
+          if (!observed?.SerialNumber) {
+            const deviceName = yield* toName(id, news);
+            const created = yield* iam.createVirtualMFADevice({
+              Path: news.path,
+              VirtualMFADeviceName: deviceName,
+              Tags: createTagsList(desiredTags),
+            });
+            if (!created.VirtualMFADevice.SerialNumber) {
+              return yield* Effect.fail(
+                new Error(`createVirtualMFADevice returned no serial number`),
+              );
+            }
+            serialNumber = created.VirtualMFADevice.SerialNumber;
+            base32StringSeed = toRedactedBytes(
+              created.VirtualMFADevice.Base32StringSeed,
             );
+            qrCodePNG = toRedactedBytes(created.VirtualMFADevice.QRCodePNG);
+
+            // The device was just created, so it is unassigned. Activate
+            // it for the user when activation codes are provided. After
+            // first activation the codes lose their meaning (`diff`
+            // triggers replacement on code change).
+            if (
+              news.userName &&
+              news.authenticationCode1 &&
+              news.authenticationCode2
+            ) {
+              yield* iam.enableMFADevice({
+                UserName: news.userName,
+                SerialNumber: serialNumber,
+                AuthenticationCode1: news.authenticationCode1,
+                AuthenticationCode2: news.authenticationCode2,
+              });
+            }
           }
-          if (
-            news.userName &&
-            news.authenticationCode1 &&
-            news.authenticationCode2
-          ) {
-            yield* iam.enableMFADevice({
-              UserName: news.userName,
-              SerialNumber: created.VirtualMFADevice.SerialNumber,
-              AuthenticationCode1: news.authenticationCode1,
-              AuthenticationCode2: news.authenticationCode2,
-            });
+
+          if (!serialNumber) {
+            return yield* Effect.fail(
+              new Error(`Virtual MFA device has no serial number`),
+            );
           }
-          const response = yield* readDevice({
-            serialNumber: created.VirtualMFADevice.SerialNumber,
-            userName: news.userName,
+
+          // Sync tags against the cloud's actual tags.
+          const observedTagsResp = yield* iam.listMFADeviceTags({
+            SerialNumber: serialNumber,
           });
-          yield* session.note(created.VirtualMFADevice.SerialNumber);
-          return {
-            serialNumber: created.VirtualMFADevice.SerialNumber,
-            userName: response?.UserName ?? news.userName,
-            enableDate: response?.EnableDate,
-            base32StringSeed: toRedactedBytes(
-              created.VirtualMFADevice.Base32StringSeed,
-            ),
-            qrCodePNG: toRedactedBytes(created.VirtualMFADevice.QRCodePNG),
-            tags,
-          };
-        }),
-        update: Effect.fn(function* ({ id, news, olds, output, session }) {
-          const oldTags = {
-            ...(yield* createInternalTags(id)),
-            ...olds.tags,
-          };
-          const newTags = {
-            ...(yield* createInternalTags(id)),
-            ...news.tags,
-          };
-          const { removed, upsert } = diffTags(oldTags, newTags);
+          const observedTags = toTagRecord(observedTagsResp.Tags);
+          const { removed, upsert } = diffTags(observedTags, desiredTags);
           if (upsert.length > 0) {
             yield* iam.tagMFADevice({
-              SerialNumber: output.serialNumber,
+              SerialNumber: serialNumber,
               Tags: upsert,
             });
           }
           if (removed.length > 0) {
             yield* iam.untagMFADevice({
-              SerialNumber: output.serialNumber,
+              SerialNumber: serialNumber,
               TagKeys: removed,
             });
           }
-          const response = yield* readDevice({
-            serialNumber: output.serialNumber,
-            userName: output.userName,
+
+          // Re-read for fresh `EnableDate` / `UserName` after activation.
+          const fresh = yield* readDevice({
+            serialNumber,
+            userName: news.userName ?? output?.userName,
           });
-          yield* session.note(output.serialNumber);
+
+          yield* session.note(serialNumber);
           return {
-            serialNumber: output.serialNumber,
-            userName: response?.UserName ?? output.userName,
-            enableDate: response?.EnableDate ?? output.enableDate,
-            base32StringSeed: output.base32StringSeed,
-            qrCodePNG: output.qrCodePNG,
-            tags: newTags,
+            serialNumber,
+            userName: fresh?.UserName ?? news.userName ?? output?.userName,
+            enableDate: fresh?.EnableDate ?? output?.enableDate,
+            base32StringSeed,
+            qrCodePNG,
+            tags: desiredTags,
           };
         }),
         delete: Effect.fn(function* ({ output }) {

package/src/AWS/IdentityCenter/AccountAssignment.ts

@@ -108,8 +108,15 @@ export const AccountAssignmentProvider = () =>
 
           return yield* readAssignment(olds);
         }),
-        create: Effect.fn(function* ({ news, session }) {
-          const existing = yield* readAssignment(news);
+        reconcile: Effect.fn(function* ({ news, output, session }) {
+          // Observe — look up the assignment between (principal,
+          // permissionSet, target). All identifying fields are stable;
+          // diff() forces a replace on any change, so this reconcile is
+          // existence-only.
+          const existing = yield* readAssignment({
+            ...news,
+            instanceArn: output?.instanceArn ?? news.instanceArn,
+          });
           if (existing) {
             yield* session.note(
               `${existing.targetId}:${existing.permissionSetArn}:${existing.principalId}`,
@@ -117,6 +124,7 @@ export const AccountAssignmentProvider = () =>
             return existing;
           }
 
+          // Ensure — create the assignment if missing.
           const instance = yield* resolveInstance(news.instanceArn);
           const response = yield* retryIdentityCenter(
             ssoAdmin.createAccountAssignment({
@@ -150,12 +158,6 @@ export const AccountAssignmentProvider = () =>
           );
           return created;
         }),
-        update: Effect.fn(function* ({ output, session }) {
-          yield* session.note(
-            `${output.targetId}:${output.permissionSetArn}:${output.principalId}`,
-          );
-          return output;
-        }),
         delete: Effect.fn(function* ({ output }) {
           if (!(yield* readAssignment(output))) {
             return;

package/src/AWS/IdentityCenter/Group.ts

@@ -82,75 +82,96 @@ export const GroupProvider = () =>
 
           return yield* readGroupByDisplayName(olds);
         }),
-        create: Effect.fn(function* ({ news, session }) {
-          const identityStoreId = yield* resolveIdentityStoreId(news);
-          const existing = yield* readGroupByDisplayName({
-            ...news,
-            identityStoreId,
-          });
-          if (existing) {
-            yield* session.note(existing.groupId);
-            return existing;
-          }
-
-          const response = yield* retryIdentityCenter(
-            identitystore.createGroup({
-              IdentityStoreId: identityStoreId,
-              DisplayName: news.displayName,
-              Description: news.description,
-            }),
-          );
-
-          const created =
-            (response.GroupId
-              ? yield* readGroupById(identityStoreId, response.GroupId)
+        reconcile: Effect.fn(function* ({ news, output, session }) {
+          const identityStoreId =
+            output?.identityStoreId ?? (yield* resolveIdentityStoreId(news));
+
+          // Observe — find the group by id (if we already have one) or
+          // by display name. We never trust `output.groupId` blindly: a
+          // group deleted out of band shows up as missing here.
+          let existing =
+            (output?.groupId
+              ? yield* readGroupById(identityStoreId, output.groupId)
               : undefined) ??
             (yield* readGroupByDisplayName({
               ...news,
               identityStoreId,
             }));
 
-          if (!created) {
-            return yield* Effect.fail(
-              new Error(`group '${news.displayName}' not found after create`),
+          // Ensure — create the group if missing.
+          if (!existing) {
+            const response = yield* retryIdentityCenter(
+              identitystore.createGroup({
+                IdentityStoreId: identityStoreId,
+                DisplayName: news.displayName,
+                Description: news.description,
+              }),
             );
+
+            existing =
+              (response.GroupId
+                ? yield* readGroupById(identityStoreId, response.GroupId)
+                : undefined) ??
+              (yield* readGroupByDisplayName({
+                ...news,
+                identityStoreId,
+              }));
+
+            if (!existing) {
+              return yield* Effect.fail(
+                new Error(`group '${news.displayName}' not found after create`),
+              );
+            }
+
+            yield* session.note(existing.groupId);
+            return existing;
           }
 
-          yield* session.note(created.groupId);
-          return created;
-        }),
-        update: Effect.fn(function* ({ news, output, session }) {
-          const operations = [
-            {
+          // Sync mutable attributes — `updateGroup` overwrites
+          // displayName and description in one call. We diff against
+          // observed cloud state so adoption converges.
+          const operations: {
+            AttributePath: string;
+            AttributeValue: string;
+          }[] = [];
+          if (existing.displayName !== news.displayName) {
+            operations.push({
               AttributePath: "DisplayName",
               AttributeValue: news.displayName,
-            },
-            {
+            });
+          }
+          const desiredDescription = news.description ?? "";
+          if ((existing.description ?? "") !== desiredDescription) {
+            operations.push({
               AttributePath: "Description",
-              AttributeValue: news.description ?? "",
-            },
-          ];
+              AttributeValue: desiredDescription,
+            });
+          }
 
-          yield* retryIdentityCenter(
-            identitystore.updateGroup({
-              IdentityStoreId: output.identityStoreId,
-              GroupId: output.groupId,
-              Operations: operations,
-            }),
-          );
+          if (operations.length > 0) {
+            yield* retryIdentityCenter(
+              identitystore.updateGroup({
+                IdentityStoreId: existing.identityStoreId,
+                GroupId: existing.groupId,
+                Operations: operations,
+              }),
+            );
 
-          const updated = yield* readGroupById(
-            output.identityStoreId,
-            output.groupId,
-          );
-          if (!updated) {
-            return yield* Effect.fail(
-              new Error(`group '${output.groupId}' not found after update`),
+            const updated = yield* readGroupById(
+              existing.identityStoreId,
+              existing.groupId,
             );
+            if (!updated) {
+              return yield* Effect.fail(
+                new Error(`group '${existing.groupId}' not found after update`),
+              );
+            }
+            yield* session.note(updated.groupId);
+            return updated;
           }
 
-          yield* session.note(updated.groupId);
-          return updated;
+          yield* session.note(existing.groupId);
+          return existing;
         }),
         delete: Effect.fn(function* ({ output }) {
           yield* retryIdentityCenter(

package/src/AWS/IdentityCenter/Instance.ts

@@ -103,9 +103,16 @@ export const InstanceProvider = () =>
           });
           return instance ? { ...instance, mode } : undefined;
         }),
-        create: Effect.fn(function* ({ news, session }) {
-          const mode = news.mode ?? "existing";
-          const existing = yield* readInstance(news);
+        reconcile: Effect.fn(function* ({ news, output, session }) {
+          const mode = output?.mode ?? news.mode ?? "existing";
+
+          // Observe — try to find a visible instance, preferring an
+          // explicit ARN (from output or props) and otherwise scanning
+          // the account.
+          const existing = yield* readInstance({
+            instanceArn: output?.instanceArn ?? news.instanceArn,
+            name: news.name,
+          });
           if (existing) {
             yield* session.note(existing.instanceArn);
             return {
@@ -114,6 +121,9 @@ export const InstanceProvider = () =>
             };
           }
 
+          // Ensure — for `existing` mode we cannot create one; fail.
+          // Organization instances must be enabled manually in the
+          // management account.
           if (mode !== "account") {
             return yield* Effect.fail(
               new Error(
@@ -122,6 +132,7 @@ export const InstanceProvider = () =>
             );
           }
 
+          // Ensure — `account` mode creates an account instance.
           const response = yield* retryIdentityCenter(
             ssoAdmin.createInstance({
               Name: news.name,
@@ -146,10 +157,6 @@ export const InstanceProvider = () =>
             mode,
           };
         }),
-        update: Effect.fn(function* ({ output, session }) {
-          yield* session.note(output.instanceArn);
-          return output;
-        }),
         delete: Effect.fn(function* ({ output }) {
           if (output.mode !== "account") {
             return;

package/src/AWS/IdentityCenter/PermissionSet.ts

@@ -93,33 +93,18 @@ export const PermissionSetProvider = () =>
 
           return yield* readPermissionSetByName(olds);
         }),
-        create: Effect.fn(function* ({ news, session }) {
-          const instance = yield* resolveInstance(news.instanceArn);
-          const existing = yield* readPermissionSetByName({
-            ...news,
-            instanceArn: instance.InstanceArn,
-          });
-          if (existing) {
-            yield* session.note(existing.permissionSetArn);
-            return existing;
-          }
-
-          const response = yield* retryIdentityCenter(
-            ssoAdmin.createPermissionSet({
-              InstanceArn: instance.InstanceArn!,
-              Name: news.name,
-              Description: news.description,
-              SessionDuration: news.sessionDuration,
-              RelayState: news.relayState,
-            }),
+        reconcile: Effect.fn(function* ({ news, output, session }) {
+          const instance = yield* resolveInstance(
+            output?.instanceArn ?? news.instanceArn,
           );
 
-          const createdArn = response.PermissionSet?.PermissionSetArn;
-          const created =
-            (createdArn
+          // Observe — find the permission set by ARN (when we already
+          // have one) or by name on the resolved instance.
+          let existing =
+            (output?.permissionSetArn
               ? yield* readPermissionSetByArn({
                   instanceArn: instance.InstanceArn!,
-                  permissionSetArn: createdArn,
+                  permissionSetArn: output.permissionSetArn,
                 })
               : undefined) ??
             (yield* readPermissionSetByName({
@@ -127,40 +112,79 @@ export const PermissionSetProvider = () =>
               instanceArn: instance.InstanceArn,
             }));
 
-          if (!created) {
-            return yield* Effect.fail(
-              new Error(`permission set '${news.name}' not found after create`),
+          // Ensure — create the permission set if missing.
+          if (!existing) {
+            const response = yield* retryIdentityCenter(
+              ssoAdmin.createPermissionSet({
+                InstanceArn: instance.InstanceArn!,
+                Name: news.name,
+                Description: news.description,
+                SessionDuration: news.sessionDuration,
+                RelayState: news.relayState,
+              }),
             );
-          }
 
-          yield* session.note(created.permissionSetArn);
-          return created;
-        }),
-        update: Effect.fn(function* ({ news, output, session }) {
-          yield* retryIdentityCenter(
-            ssoAdmin.updatePermissionSet({
-              InstanceArn: output.instanceArn,
-              PermissionSetArn: output.permissionSetArn,
-              Description: news.description,
-              SessionDuration: news.sessionDuration,
-              RelayState: news.relayState,
-            }),
-          );
+            const createdArn = response.PermissionSet?.PermissionSetArn;
+            existing =
+              (createdArn
+                ? yield* readPermissionSetByArn({
+                    instanceArn: instance.InstanceArn!,
+                    permissionSetArn: createdArn,
+                  })
+                : undefined) ??
+              (yield* readPermissionSetByName({
+                ...news,
+                instanceArn: instance.InstanceArn,
+              }));
 
-          const updated = yield* readPermissionSetByArn({
-            instanceArn: output.instanceArn,
-            permissionSetArn: output.permissionSetArn,
-          });
-          if (!updated) {
-            return yield* Effect.fail(
-              new Error(
-                `permission set '${output.permissionSetArn}' not found after update`,
-              ),
+            if (!existing) {
+              return yield* Effect.fail(
+                new Error(
+                  `permission set '${news.name}' not found after create`,
+                ),
+              );
+            }
+
+            yield* session.note(existing.permissionSetArn);
+            return existing;
+          }
+
+          // Sync mutable attributes — `updatePermissionSet` overwrites
+          // description, sessionDuration, relayState. Diff against
+          // observed cloud state so adoption converges; only call when
+          // there's a real delta.
+          if (
+            (existing.description ?? undefined) !== news.description ||
+            (existing.sessionDuration ?? undefined) !== news.sessionDuration ||
+            (existing.relayState ?? undefined) !== news.relayState
+          ) {
+            yield* retryIdentityCenter(
+              ssoAdmin.updatePermissionSet({
+                InstanceArn: existing.instanceArn,
+                PermissionSetArn: existing.permissionSetArn,
+                Description: news.description,
+                SessionDuration: news.sessionDuration,
+                RelayState: news.relayState,
+              }),
             );
+
+            const updated = yield* readPermissionSetByArn({
+              instanceArn: existing.instanceArn,
+              permissionSetArn: existing.permissionSetArn,
+            });
+            if (!updated) {
+              return yield* Effect.fail(
+                new Error(
+                  `permission set '${existing.permissionSetArn}' not found after update`,
+                ),
+              );
+            }
+            yield* session.note(updated.permissionSetArn);
+            return updated;
           }
 
-          yield* session.note(updated.permissionSetArn);
-          return updated;
+          yield* session.note(existing.permissionSetArn);
+          return existing;
         }),
         delete: Effect.fn(function* ({ output }) {
           yield* retryIdentityCenter(