alchemy 2.0.0-beta.4 → 2.0.0-beta.40

package/src/AWS/IAM/SigningCertificate.ts

@@ -91,43 +91,53 @@ export const SigningCertificateProvider = () =>
         uploadDate: cert.UploadDate,
       };
     }),
-    create: Effect.fn(function* ({ news, session }) {
-      const created = yield* iam.uploadSigningCertificate({
-        UserName: news.userName,
-        CertificateBody: news.certificateBody,
-      });
-      if (
-        news.status !== undefined &&
-        created.Certificate.Status !== news.status
-      ) {
-        yield* iam.updateSigningCertificate({
+    reconcile: Effect.fn(function* ({ news, output, session }) {
+      // Observe — certificate ids are AWS-generated; we can only locate
+      // the live entry via the prior output. The certificate body is
+      // immutable (`diff` triggers replacement on body change), so a
+      // missing entry always means we need to upload.
+      const observed = output
+        ? yield* iam
+            .listSigningCertificates({ UserName: output.userName })
+            .pipe(
+              Effect.map((r) =>
+                r.Certificates.find(
+                  (entry) => entry.CertificateId === output.certificateId,
+                ),
+              ),
+              Effect.catchTag("NoSuchEntityException", () =>
+                Effect.succeed(undefined),
+              ),
+            )
+        : undefined;
+
+      // Ensure — upload when missing.
+      let cert = observed;
+      if (!cert?.CertificateId) {
+        const uploaded = yield* iam.uploadSigningCertificate({
           UserName: news.userName,
-          CertificateId: created.Certificate.CertificateId,
-          Status: news.status,
+          CertificateBody: news.certificateBody,
         });
+        cert = uploaded.Certificate;
       }
-      yield* session.note(created.Certificate.CertificateId);
-      return {
-        userName: created.Certificate.UserName,
-        certificateId: created.Certificate.CertificateId,
-        certificateBody: created.Certificate.CertificateBody,
-        status: news.status ?? created.Certificate.Status,
-        uploadDate: created.Certificate.UploadDate,
-      };
-    }),
-    update: Effect.fn(function* ({ news, output, session }) {
-      const status = news.status ?? output.status;
-      if (status !== output.status) {
+
+      // Sync — apply the desired status when it differs.
+      const desiredStatus = news.status ?? cert.Status;
+      if (desiredStatus !== cert.Status) {
         yield* iam.updateSigningCertificate({
-          UserName: output.userName,
-          CertificateId: output.certificateId,
-          Status: status,
+          UserName: news.userName,
+          CertificateId: cert.CertificateId,
+          Status: desiredStatus,
         });
       }
-      yield* session.note(output.certificateId);
+
+      yield* session.note(cert.CertificateId);
       return {
-        ...output,
-        status,
+        userName: cert.UserName,
+        certificateId: cert.CertificateId,
+        certificateBody: cert.CertificateBody,
+        status: desiredStatus,
+        uploadDate: cert.UploadDate,
       };
     }),
     delete: Effect.fn(function* ({ output }) {

package/src/AWS/IAM/User.ts

@@ -256,73 +256,62 @@ export const UserProvider = () =>
             tags,
           };
         }),
-        create: Effect.fn(function* ({ id, news, session }) {
-          const userName = yield* toName(id, news);
-          const tags = {
+        reconcile: Effect.fn(function* ({ id, news, output, session }) {
+          const userName = output?.userName ?? (yield* toName(id, news));
+          const desiredTags = {
             ...(yield* createInternalTags(id)),
             ...news.tags,
           };
-          const created = yield* iam
-            .createUser({
-              UserName: userName,
-              Path: news.path,
-              PermissionsBoundary: news.permissionsBoundary,
-              Tags: createTagsList(tags),
-            })
+
+          // Observe — read the live user (or absence).
+          const observedResponse = yield* iam
+            .getUser({ UserName: userName })
             .pipe(
-              Effect.catchTag("EntityAlreadyExistsException", () =>
-                iam
-                  .getUser({
-                    UserName: userName,
-                  })
-                  .pipe(
+              Effect.catchTag("NoSuchEntityException", () =>
+                Effect.succeed(undefined),
+              ),
+            );
+          let observedUser = observedResponse?.User;
+
+          // Ensure — create the user when missing. On race, verify
+          // ownership tags before adopting.
+          if (!observedUser?.Arn) {
+            const created = yield* iam
+              .createUser({
+                UserName: userName,
+                Path: news.path,
+                PermissionsBoundary: news.permissionsBoundary,
+                Tags: createTagsList(desiredTags),
+              })
+              .pipe(
+                Effect.catchTag("EntityAlreadyExistsException", () =>
+                  iam.getUser({ UserName: userName }).pipe(
                     Effect.filterOrFail(
-                      (existing) => hasTags(tags, existing.User?.Tags),
+                      (existing) => hasTags(desiredTags, existing.User?.Tags),
                       () =>
                         new Error(
                           `User '${userName}' already exists and is not managed by alchemy`,
                         ),
                     ),
                   ),
-              ),
-            );
-
-          yield* syncManagedPolicies({
-            userName,
-            olds: [],
-            news: news.managedPolicyArns ?? [],
-          });
-          yield* syncInlinePolicies({
-            userName,
-            olds: {},
-            news: news.inlinePolicies ?? {},
-          });
+                ),
+              );
+            observedUser = created.User;
+          }
 
-          yield* session.note(created.User?.Arn ?? userName);
-          return {
-            userArn: created.User?.Arn ?? userName,
-            userName,
-            userId: created.User?.UserId,
-            path: created.User?.Path ?? news.path ?? "/",
-            permissionsBoundary:
-              created.User?.PermissionsBoundary?.PermissionsBoundaryArn ??
-              news.permissionsBoundary,
-            managedPolicyArns: news.managedPolicyArns ?? [],
-            inlinePolicies: news.inlinePolicies ?? {},
-            tags,
-          };
-        }),
-        update: Effect.fn(function* ({ id, news, olds, output, session }) {
-          if (news.permissionsBoundary !== olds.permissionsBoundary) {
+          // Sync permissions boundary against observed.
+          const observedBoundary =
+            observedUser?.PermissionsBoundary?.PermissionsBoundaryArn;
+          if (news.permissionsBoundary !== observedBoundary) {
             if (news.permissionsBoundary) {
               yield* iam.putUserPermissionsBoundary({
-                UserName: output.userName,
+                UserName: userName,
                 PermissionsBoundary: news.permissionsBoundary,
               });
-            } else if (olds.permissionsBoundary) {
+            } else if (observedBoundary) {
               yield* iam
                 .deleteUserPermissionsBoundary({
-                  UserName: output.userName,
+                  UserName: userName,
                 })
                 .pipe(
                   Effect.catchTag("NoSuchEntityException", () => Effect.void),
@@ -330,55 +319,56 @@ export const UserProvider = () =>
             }
           }
 
+          // Sync managed and inline policies — observe live state and
+          // apply only the delta.
+          const [observedManagedPolicies, observedInlinePolicies] =
+            yield* Effect.all([
+              readManagedPolicies(userName),
+              readInlinePolicies(userName),
+            ]);
           yield* syncManagedPolicies({
-            userName: output.userName,
-            olds: olds.managedPolicyArns ?? [],
+            userName,
+            olds: observedManagedPolicies,
             news: news.managedPolicyArns ?? [],
           });
           yield* syncInlinePolicies({
-            userName: output.userName,
-            olds: olds.inlinePolicies ?? {},
+            userName,
+            olds: observedInlinePolicies,
             news: news.inlinePolicies ?? {},
           });
 
-          const oldTags = {
-            ...(yield* createInternalTags(id)),
-            ...olds.tags,
-          };
-          const newTags = {
-            ...(yield* createInternalTags(id)),
-            ...news.tags,
-          };
-          const { removed, upsert } = diffTags(oldTags, newTags);
+          // Sync tags against the cloud's actual tags.
+          const observedTags = yield* readTags(userName);
+          const { removed, upsert } = diffTags(observedTags, desiredTags);
           if (upsert.length > 0) {
             yield* iam.tagUser({
-              UserName: output.userName,
+              UserName: userName,
               Tags: upsert,
             });
           }
           if (removed.length > 0) {
             yield* iam.untagUser({
-              UserName: output.userName,
+              UserName: userName,
               TagKeys: removed,
             });
           }
 
-          const user = yield* iam.getUser({
-            UserName: output.userName,
-          });
+          // Re-read for fresh attributes after all mutations.
+          const user = yield* iam.getUser({ UserName: userName });
+          const userArn = user.User?.Arn ?? observedUser?.Arn ?? userName;
 
-          yield* session.note(output.userArn);
+          yield* session.note(userArn);
           return {
-            userArn: user.User?.Arn ?? output.userArn,
-            userName: user.User?.UserName ?? output.userName,
-            userId: user.User?.UserId ?? output.userId,
-            path: user.User?.Path ?? output.path,
+            userArn,
+            userName: user.User?.UserName ?? userName,
+            userId: user.User?.UserId ?? observedUser?.UserId,
+            path: user.User?.Path ?? observedUser?.Path ?? news.path ?? "/",
             permissionsBoundary:
               user.User?.PermissionsBoundary?.PermissionsBoundaryArn ??
               news.permissionsBoundary,
             managedPolicyArns: news.managedPolicyArns ?? [],
             inlinePolicies: news.inlinePolicies ?? {},
-            tags: newTags,
+            tags: desiredTags,
           };
         }),
         delete: Effect.fn(function* ({ output }) {

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(