@microagi/alchemy-gcp 0.7.0 → 0.8.1

package/lib/Iam/ServiceAccount.js

@@ -0,0 +1,255 @@
+import { ConfigError } from "@distilled.cloud/gcp";
+import * as iam from "@distilled.cloud/gcp/unstable/iam-v1";
+import { Resource } from "alchemy";
+import { Unowned } from "alchemy/AdoptPolicy";
+import { isResolved } from "alchemy/Diff";
+import * as Provider from "alchemy/Provider";
+import { diffTags } from "alchemy/Tags";
+import * as Duration from "effect/Duration";
+import * as Effect from "effect/Effect";
+import * as Schedule from "effect/Schedule";
+import { descriptionHasAlchemyMarker, gcpAlchemyDescription, stripAlchemyMarker, } from "../Tags.js";
+export const ServiceAccount = Resource("GCP.ServiceAccount");
+const toAttributes = (sa) => {
+    const accountId = (sa.email ?? "").split("@")[0];
+    return {
+        name: sa.name ?? "",
+        email: sa.email ?? "",
+        uniqueId: sa.uniqueId ?? "",
+        projectId: sa.projectId ?? "",
+        accountId,
+        displayName: sa.displayName,
+        description: stripAlchemyMarker(sa.description),
+        disabled: sa.disabled ?? false,
+    };
+};
+export const ServiceAccountProvider = () => Provider.effect(ServiceAccount, Effect.gen(function* () {
+    const getProjectsServiceAccounts = yield* iam.getProjectsServiceAccounts;
+    const createProjectsServiceAccounts = yield* iam.createProjectsServiceAccounts;
+    const patchProjectsServiceAccounts = yield* iam.patchProjectsServiceAccounts;
+    const deleteProjectsServiceAccounts = yield* iam.deleteProjectsServiceAccounts;
+    const listProjectsServiceAccounts = yield* iam.listProjectsServiceAccounts;
+    const getIamPolicyProjectsServiceAccounts = yield* iam.getIamPolicyProjectsServiceAccounts;
+    const setIamPolicyProjectsServiceAccounts = yield* iam.setIamPolicyProjectsServiceAccounts;
+    const resourceName = (projectId, accountId) => `projects/${projectId}/serviceAccounts/${accountId}`;
+    const observeServiceAccount = (projectId, accountId) => getProjectsServiceAccounts({
+        name: resourceName(projectId, accountId),
+    }).pipe(
+    // GSAs that don't exist OR that the caller can't see both
+    // collapse to "absent" — same 403→missing pattern as the
+    // project observer.
+    Effect.catchTag("NotFound", () => Effect.succeed(undefined)), Effect.catchTag("Forbidden", () => Effect.succeed(undefined)));
+    const requireServiceAccount = (projectId, accountId, context) => observeServiceAccount(projectId, accountId).pipe(Effect.flatMap((sa) => sa
+        ? Effect.succeed(sa)
+        : Effect.fail(new ConfigError({
+            message: `ServiceAccount ${accountId} in project ${projectId} ${context}.`,
+        }))));
+    // List-page scan for cold recovery. Alchemy marker in the
+    // description field identifies our GSAs; the page boundary is
+    // arbitrary — we still need to page through to find any marker
+    // that happens to fall past the first page.
+    const findByAlchemyMarker = Effect.fn(function* (id, projectId) {
+        let pageToken;
+        // Up to 100 pages × 100 items per page = 10000 GSAs; well past
+        // any realistic project size. If we ever exceed that we should
+        // cap and warn rather than silently miss matches.
+        for (let i = 0; i < 100; i++) {
+            const page = yield* listProjectsServiceAccounts({
+                name: `projects/${projectId}`,
+                ...(pageToken ? { pageToken } : {}),
+                pageSize: 100,
+            });
+            for (const sa of page.accounts ?? []) {
+                if (yield* descriptionHasAlchemyMarker(id, sa.description)) {
+                    return sa;
+                }
+            }
+            pageToken = page.nextPageToken;
+            if (!pageToken)
+                return undefined;
+        }
+        return undefined;
+    });
+    // Sync mutable fields: displayName + description. Both use
+    // `updateMask` so we only PATCH what actually changed. Diff
+    // against OBSERVED state, not `olds`, so adoption converges
+    // correctly when a foreign description is on the GSA.
+    const syncMutable = Effect.fn(function* (observed, desired) {
+        const updateMaskFields = [];
+        if (desired.displayName !== observed.displayName) {
+            updateMaskFields.push("display_name");
+        }
+        const descDiff = diffTags({ description: observed.description ?? "" }, { description: desired.descriptionWithMarker });
+        if (descDiff.removed.length > 0 ||
+            descDiff.upsert.length > 0) {
+            updateMaskFields.push("description");
+        }
+        if (updateMaskFields.length === 0)
+            return observed;
+        return yield* patchProjectsServiceAccounts({
+            name: observed.name,
+            body: {
+                updateMask: updateMaskFields.join(","),
+                serviceAccount: {
+                    displayName: desired.displayName,
+                    description: desired.descriptionWithMarker,
+                },
+            },
+        });
+    });
+    // Apply merged IAM bindings as a single setIamPolicy. Same
+    // foreign-binding preservation + etag-retry pattern as the
+    // Project's `syncIam` — see `src/CloudResourceManager/Project.ts:421-474`.
+    const syncIam = (args) => Effect.gen(function* () {
+        const desiredByRole = new Map();
+        for (const b of args.bindings) {
+            for (const ib of b.data.iamBindings) {
+                const set = desiredByRole.get(ib.role) ?? new Set();
+                for (const m of ib.members)
+                    set.add(m);
+                desiredByRole.set(ib.role, set);
+            }
+        }
+        if (desiredByRole.size === 0)
+            return;
+        const current = yield* getIamPolicyProjectsServiceAccounts({
+            resource: args.resourceName,
+            "options.requestedPolicyVersion": 3,
+        });
+        const existingBindings = (current.bindings ?? []).map((b) => ({
+            ...b,
+            members: [...(b.members ?? [])],
+        }));
+        let mutated = false;
+        for (const [role, members] of desiredByRole) {
+            let existing = existingBindings.find((b) => b.role === role && !b.condition);
+            if (!existing) {
+                existing = { role, members: [] };
+                existingBindings.push(existing);
+            }
+            const merged = new Set([...(existing.members ?? []), ...members]);
+            if (merged.size !== (existing.members?.length ?? 0))
+                mutated = true;
+            existing.members = [...merged];
+        }
+        if (!mutated)
+            return;
+        yield* setIamPolicyProjectsServiceAccounts({
+            resource: args.resourceName,
+            body: {
+                policy: { ...current, bindings: existingBindings, version: 3 },
+            },
+        });
+    }).pipe(Effect.retry({
+        schedule: Schedule.exponential(Duration.seconds(2)).pipe(Schedule.both(Schedule.recurs(8))),
+    }));
+    return {
+        // Stable identity: accountId + project; both immutable; either
+        // change → replace. The server-assigned uniqueId is also stable
+        // for the lifetime of the GSA (re-create gets a different one).
+        stables: ["accountId", "projectId", "uniqueId", "name", "email"],
+        diff: Effect.fn(function* ({ id, news, olds = {}, output }) {
+            if (!isResolved(news))
+                return undefined;
+            // Replace ONLY when a prior identity is actually known AND differs.
+            // A partial/adopted state can lack the persisted accountId/projectId
+            // (an adoption that never persisted full Attributes leaves
+            // output.projectId === "" / undefined). Treating that "unknown" as a
+            // replace spuriously deletes+recreates a live, correctly-named GSA
+            // (and churns its uniqueId → breaks Workload-Identity bindings).
+            // When the prior identity is absent, fall through to reconcile, which
+            // observes the live resource and re-persists its Attributes. The
+            // truthiness guard covers both `undefined` and the `""` toAttributes
+            // default; a genuine accountId/project change still has a non-empty
+            // prior value to compare against, so real replacements are unaffected.
+            // `||` (not `??`): toAttributes persists `accountId`/`projectId` as
+            // `""` when absent, and an empty string must fall through to `olds`
+            // (the previous Props) rather than mask it — otherwise a genuine
+            // identity change with an empty `output` but a populated `olds` would
+            // skip the replace and adopt/create at the new identity without
+            // deleting the old GSA.
+            const priorAccount = output?.accountId || olds.accountId;
+            const priorProject = output?.projectId || olds.project;
+            if ((priorAccount && news.accountId !== priorAccount) ||
+                (priorProject && news.project !== priorProject)) {
+                return { action: "replace" };
+            }
+            return undefined;
+        }),
+        reconcile: Effect.fn(function* ({ id, news, bindings }) {
+            const descriptionWithMarker = yield* gcpAlchemyDescription(id, news.description);
+            // 1. Observe — cloud state is authoritative. A second
+            //    scan-by-marker covers the cold-recovery case where
+            //    persisted `output`/`olds` lost the uniqueId after
+            //    state loss. We prefer the direct-by-name probe first
+            //    (cheap) and fall back to the scan only when direct
+            //    observation returned `undefined`.
+            let observed = yield* observeServiceAccount(news.project, news.accountId);
+            if (!observed) {
+                observed = yield* findByAlchemyMarker(id, news.project);
+            }
+            // 2. Ensure — create if missing. createProjectsServiceAccounts
+            //    is synchronous (returns the SA, not an LRO). Conflict
+            //    covers a peer reconciler race — re-observe.
+            if (!observed) {
+                observed = yield* createProjectsServiceAccounts({
+                    name: `projects/${news.project}`,
+                    body: {
+                        accountId: news.accountId,
+                        serviceAccount: {
+                            displayName: news.displayName,
+                            description: descriptionWithMarker,
+                        },
+                    },
+                }).pipe(Effect.catchTag("Conflict", () => Effect.succeed(undefined)));
+                if (!observed) {
+                    observed = yield* requireServiceAccount(news.project, news.accountId, "did not appear after create");
+                }
+            }
+            // 3. Sync mutable fields against OBSERVED state.
+            const synced = yield* syncMutable(observed, {
+                displayName: news.displayName ?? observed.displayName,
+                descriptionWithMarker,
+                descriptionUserOnly: news.description,
+            });
+            // 4. Sync IAM bindings (Workload Identity, impersonators, …).
+            //    Single setIamPolicy on the GSA with merged bindings;
+            //    foreign roles preserved. Etag-retried internally.
+            yield* syncIam({
+                resourceName: synced.name,
+                bindings,
+            });
+            return toAttributes(synced);
+        }),
+        delete: Effect.fn(function* ({ output }) {
+            // Synchronous delete — Empty response, no LRO. NotFound
+            // means the GSA was already deleted (or never existed in our
+            // scope); both are idempotent successes.
+            yield* deleteProjectsServiceAccounts({
+                name: output.name,
+            }).pipe(Effect.catchTag("NotFound", () => Effect.void), Effect.catchTag("Forbidden", () => Effect.void));
+        }),
+        read: Effect.fn(function* ({ id, output, olds }) {
+            // Direct-by-name probe when we have any handle on the
+            // accountId. Falls back to a project-wide scan-by-marker
+            // for cold recovery after state loss.
+            const accountId = output?.accountId ?? olds?.accountId;
+            const projectId = output?.projectId ?? olds?.project;
+            let observed;
+            if (accountId && projectId) {
+                observed = yield* observeServiceAccount(projectId, accountId);
+            }
+            if (!observed && projectId) {
+                observed = yield* findByAlchemyMarker(id, projectId);
+            }
+            if (!observed)
+                return undefined;
+            const attrs = toAttributes(observed);
+            // Adoption gate via description marker (see Tags.ts §description).
+            return (yield* descriptionHasAlchemyMarker(id, observed.description))
+                ? attrs
+                : Unowned(attrs);
+        }),
+    };
+}));
+//# sourceMappingURL=ServiceAccount.js.map

package/lib/Iam/ServiceAccount.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ServiceAccount.js","sourceRoot":"","sources":["../../src/Iam/ServiceAccount.ts"],"names":[],"mappings":"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"}

package/lib/Iam/ServiceAccountIamMember.d.ts

@@ -0,0 +1,49 @@
+import * as Effect from "effect/Effect";
+import type { ServiceAccount } from "./ServiceAccount.ts";
+/**
+ * Bind a single `(role, member)` IAM grant onto a {@link ServiceAccount}.
+ *
+ * This is a **target-side binding** — it records the grant onto the
+ * GSA's binding bag (`stack.bindings[gsa]`); the ServiceAccount
+ * provider's `reconcile` later merges all such bindings (across all
+ * callers, including parallel ones from different stack stages) into
+ * a single `setIamPolicy` call on the GSA. Same pattern as
+ * `projectIamMember` / `subnetworkIamMember`.
+ *
+ * Identity for dedup: the rendered SID is `IamMember(<gsa>, <key>)`.
+ * The engine collapses binds by SID, so callers MUST supply a
+ * stack-unique `key` per (gsa, role, member) triple — otherwise a
+ * later bind silently overwrites an earlier one with the same key.
+ *
+ * The reason `key` exists: `member` is usually an `Output<string>`
+ * (e.g. `Output.interpolate\`...${cluster.projectId}...\``), and
+ * `Output` expressions stringify by their AST shape, not by the
+ * eventual value. Two interpolations of the same shape but different
+ * literal templates render the same SID. `key` sidesteps that by
+ * forcing a static, caller-supplied label into the SID.
+ *
+ * Use this for the "Pulumi `gcp.serviceAccount.IAMMember`" pattern:
+ * authoritative-for-(role, member)-tuple, additive (does not displace
+ * other members on the same role).
+ *
+ * @example Workload Identity binding for one cluster
+ * ```typescript
+ * yield* GCP.serviceAccountIamMember(gsa, "ClusterA-WorkloadIdentity", {
+ *   role: "roles/iam.workloadIdentityUser",
+ *   member: `serviceAccount:${clusterA.projectId}.svc.id.goog[researchers/build]`,
+ * });
+ * ```
+ *
+ * @example Same GSA, second cluster (separate key → distinct SID)
+ * ```typescript
+ * yield* GCP.serviceAccountIamMember(gsa, "ClusterB-WorkloadIdentity", {
+ *   role: "roles/iam.workloadIdentityUser",
+ *   member: `serviceAccount:${clusterB.projectId}.svc.id.goog[researchers/build]`,
+ * });
+ * ```
+ */
+export declare const serviceAccountIamMember: (gsa: ServiceAccount, key: string, args: {
+    role: string;
+    member: string;
+}) => Effect.Effect<void>;
+//# sourceMappingURL=ServiceAccountIamMember.d.ts.map

package/lib/Iam/ServiceAccountIamMember.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ServiceAccountIamMember.d.ts","sourceRoot":"","sources":["../../src/Iam/ServiceAccountIamMember.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,MAAM,MAAM,eAAe,CAAC;AACxC,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAE1D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyCG;AACH,eAAO,MAAM,uBAAuB,QAC7B,cAAc,OACd,MAAM,QACL;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,KACrC,MAAM,CAAC,MAAM,CAAC,IAAI,CAMiB,CAAC"}

package/lib/Iam/ServiceAccountIamMember.js

@@ -0,0 +1,50 @@
+/**
+ * Bind a single `(role, member)` IAM grant onto a {@link ServiceAccount}.
+ *
+ * This is a **target-side binding** — it records the grant onto the
+ * GSA's binding bag (`stack.bindings[gsa]`); the ServiceAccount
+ * provider's `reconcile` later merges all such bindings (across all
+ * callers, including parallel ones from different stack stages) into
+ * a single `setIamPolicy` call on the GSA. Same pattern as
+ * `projectIamMember` / `subnetworkIamMember`.
+ *
+ * Identity for dedup: the rendered SID is `IamMember(<gsa>, <key>)`.
+ * The engine collapses binds by SID, so callers MUST supply a
+ * stack-unique `key` per (gsa, role, member) triple — otherwise a
+ * later bind silently overwrites an earlier one with the same key.
+ *
+ * The reason `key` exists: `member` is usually an `Output<string>`
+ * (e.g. `Output.interpolate\`...${cluster.projectId}...\``), and
+ * `Output` expressions stringify by their AST shape, not by the
+ * eventual value. Two interpolations of the same shape but different
+ * literal templates render the same SID. `key` sidesteps that by
+ * forcing a static, caller-supplied label into the SID.
+ *
+ * Use this for the "Pulumi `gcp.serviceAccount.IAMMember`" pattern:
+ * authoritative-for-(role, member)-tuple, additive (does not displace
+ * other members on the same role).
+ *
+ * @example Workload Identity binding for one cluster
+ * ```typescript
+ * yield* GCP.serviceAccountIamMember(gsa, "ClusterA-WorkloadIdentity", {
+ *   role: "roles/iam.workloadIdentityUser",
+ *   member: `serviceAccount:${clusterA.projectId}.svc.id.goog[researchers/build]`,
+ * });
+ * ```
+ *
+ * @example Same GSA, second cluster (separate key → distinct SID)
+ * ```typescript
+ * yield* GCP.serviceAccountIamMember(gsa, "ClusterB-WorkloadIdentity", {
+ *   role: "roles/iam.workloadIdentityUser",
+ *   member: `serviceAccount:${clusterB.projectId}.svc.id.goog[researchers/build]`,
+ * });
+ * ```
+ */
+export const serviceAccountIamMember = (gsa, key, args) => 
+// Tagged-template `.bind` records into the target's binding bag.
+// ServiceAccount's reconcile sees `bindings: ResourceBinding<…>[]`
+// and merges all entries by role into one setIamPolicy call.
+gsa.bind `IamMember(${gsa}, ${key})`({
+    iamBindings: [{ role: args.role, members: [args.member] }],
+});
+//# sourceMappingURL=ServiceAccountIamMember.js.map

package/lib/Iam/ServiceAccountIamMember.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ServiceAccountIamMember.js","sourceRoot":"","sources":["../../src/Iam/ServiceAccountIamMember.ts"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyCG;AACH,MAAM,CAAC,MAAM,uBAAuB,GAAG,CACrC,GAAmB,EACnB,GAAW,EACX,IAAsC,EACjB,EAAE;AACvB,iEAAiE;AACjE,mEAAmE;AACnE,6DAA6D;AAC7D,GAAG,CAAC,IAAI,CAAA,aAAa,GAAG,KAAK,GAAG,GAAG,CAAC;IAClC,WAAW,EAAE,CAAC,EAAE,IAAI,EAAE,IAAI,CAAC,IAAI,EAAE,OAAO,EAAE,CAAC,IAAI,CAAC,MAAM,CAAC,EAAE,CAAC;CAC3D,CAAmC,CAAC"}

package/lib/Iam/ServiceAccountKey.d.ts

@@ -0,0 +1,72 @@
+import { Resource } from "alchemy";
+import * as Provider from "alchemy/Provider";
+import type * as GCP from "../Providers.ts";
+/**
+ * A user-managed service account key (JSON credentials file). Lives
+ * under a {@link import("./ServiceAccount.ts").ServiceAccount} and
+ * produces a `privateKeyData` field (base64-encoded JSON key file)
+ * available ONLY on create — `get`/`list` never return it.
+ *
+ * The `privateKeyData` attribute is marked stable so the engine
+ * preserves it across reconciles (it cannot be re-read from the API).
+ * On cold recovery (state loss), if the key exists but
+ * `privateKeyData` is absent from state, the old key is deleted and a
+ * new one is created so the `privateKeyData` is re-obtained.
+ *
+ * SA keys carry no labels or description, so adoption cannot be gated
+ * by marker — the SA itself is alchemy-owned, and the key is managed
+ * exclusively through this resource.
+ *
+ * @section Creating a ServiceAccountKey
+ * @example Mint a JSON key for a GSA
+ * ```typescript
+ * const key = yield* GCP.ServiceAccountKey("TempBucketKey", {
+ *   serviceAccount: sa.name,  // projects/{p}/serviceAccounts/{email}
+ * });
+ * // key.privateKeyData is the base64-encoded JSON key file
+ * ```
+ */
+export type ServiceAccountKeyProps = {
+    /**
+     * The resource name of the parent service account, in the format
+     * `projects/{PROJECT_ID}/serviceAccounts/{EMAIL_ADDRESS}`.
+     * Immutable — changing it triggers a replacement (the key is
+     * scoped to the SA).
+     */
+    serviceAccount: string;
+    /**
+     * Key algorithm. Defaults to `KEY_ALG_RSA_2048`. Immutable after
+     * create.
+     */
+    keyAlgorithm?: "KEY_ALG_RSA_2048" | "KEY_ALG_RSA_1024";
+    /**
+     * Output format for the private key. Defaults to
+     * `TYPE_GOOGLE_CREDENTIALS_FILE` (the Google Credentials JSON
+     * format usable by gcloud, gsutil, and the gcsfuse CSI driver).
+     */
+    privateKeyType?: "TYPE_GOOGLE_CREDENTIALS_FILE" | "TYPE_PKCS12_FILE";
+};
+export type ServiceAccountKey = Resource<"GCP.ServiceAccountKey", ServiceAccountKeyProps, {
+    /** Full resource name: `projects/{p}/serviceAccounts/{email}/keys/{keyId}`. */
+    name: string;
+    /**
+     * Base64-encoded private key data (JSON key file). Only available
+     * on create — not returned by `get`/`list`. Preserved in alchemy
+     * state; on state loss the old key is deleted + a new one is
+     * created to re-obtain it.
+     */
+    privateKeyData: string | undefined;
+    /** Key algorithm used. */
+    keyAlgorithm: string | undefined;
+    /** Key type: `USER_MANAGED` or `SYSTEM_MANAGED`. */
+    keyType: string | undefined;
+    /** Key origin: `USER_PROVIDED` or `GOOGLE_PROVIDED`. */
+    keyOrigin: string | undefined;
+    /** Timestamp after which the key is valid (RFC 3339). */
+    validAfterTime: string | undefined;
+    /** Whether the key is disabled. */
+    disabled: boolean | undefined;
+}, never, GCP.Providers>;
+export declare const ServiceAccountKey: import("alchemy").ResourceClass<ServiceAccountKey>;
+export declare const ServiceAccountKeyProvider: () => import("effect/Layer").Layer<Provider.Provider<ServiceAccountKey>, never, import("@distilled.cloud/gcp").Credentials | import("effect/unstable/http/HttpClient").HttpClient>;
+//# sourceMappingURL=ServiceAccountKey.d.ts.map

package/lib/Iam/ServiceAccountKey.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ServiceAccountKey.d.ts","sourceRoot":"","sources":["../../src/Iam/ServiceAccountKey.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AAEnC,OAAO,KAAK,QAAQ,MAAM,kBAAkB,CAAC;AAE7C,OAAO,KAAK,KAAK,GAAG,MAAM,iBAAiB,CAAC;AAE5C;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,MAAM,MAAM,sBAAsB,GAAG;IACnC;;;;;OAKG;IACH,cAAc,EAAE,MAAM,CAAC;IACvB;;;OAGG;IACH,YAAY,CAAC,EAAE,kBAAkB,GAAG,kBAAkB,CAAC;IACvD;;;;OAIG;IACH,cAAc,CAAC,EAAE,8BAA8B,GAAG,kBAAkB,CAAC;CACtE,CAAC;AAEF,MAAM,MAAM,iBAAiB,GAAG,QAAQ,CACtC,uBAAuB,EACvB,sBAAsB,EACtB;IACE,+EAA+E;IAC/E,IAAI,EAAE,MAAM,CAAC;IACb;;;;;OAKG;IACH,cAAc,EAAE,MAAM,GAAG,SAAS,CAAC;IACnC,0BAA0B;IAC1B,YAAY,EAAE,MAAM,GAAG,SAAS,CAAC;IACjC,oDAAoD;IACpD,OAAO,EAAE,MAAM,GAAG,SAAS,CAAC;IAC5B,wDAAwD;IACxD,SAAS,EAAE,MAAM,GAAG,SAAS,CAAC;IAC9B,yDAAyD;IACzD,cAAc,EAAE,MAAM,GAAG,SAAS,CAAC;IACnC,mCAAmC;IACnC,QAAQ,EAAE,OAAO,GAAG,SAAS,CAAC;CAC/B,EACD,KAAK,EACL,GAAG,CAAC,SAAS,CACd,CAAC;AAEF,eAAO,MAAM,iBAAiB,oDAE7B,CAAC;AAYF,eAAO,MAAM,yBAAyB,oLA2LnC,CAAC"}

package/lib/Iam/ServiceAccountKey.js

@@ -0,0 +1,164 @@
+import { ConfigError } from "@distilled.cloud/gcp";
+import * as iam from "@distilled.cloud/gcp/unstable/iam-v1";
+import { Resource } from "alchemy";
+import { isResolved } from "alchemy/Diff";
+import * as Provider from "alchemy/Provider";
+import * as Effect from "effect/Effect";
+export const ServiceAccountKey = Resource("GCP.ServiceAccountKey");
+const toAttributes = (k) => ({
+    name: k.name ?? "",
+    privateKeyData: k.privateKeyData,
+    keyAlgorithm: k.keyAlgorithm,
+    keyType: k.keyType,
+    keyOrigin: k.keyOrigin,
+    validAfterTime: k.validAfterTime,
+    disabled: k.disabled,
+});
+export const ServiceAccountKeyProvider = () => Provider.effect(ServiceAccountKey, Effect.gen(function* () {
+    const createProjectsServiceAccountsKeys = yield* iam.createProjectsServiceAccountsKeys;
+    const deleteProjectsServiceAccountsKeys = yield* iam.deleteProjectsServiceAccountsKeys;
+    const listProjectsServiceAccountsKeys = yield* iam.listProjectsServiceAccountsKeys;
+    const getProjectsServiceAccountsKeys = yield* iam.getProjectsServiceAccountsKeys;
+    // Find a user-managed key by name (direct probe).
+    // NotFound → undefined (key doesn't exist). Forbidden is NOT
+    // swallowed — if the caller lacks permission to read this key,
+    // propagating the error is safer than treating it as "missing"
+    // and potentially creating a duplicate on the SA.
+    const observeKey = (keyName) => getProjectsServiceAccountsKeys({
+        name: keyName,
+        publicKeyType: "TYPE_GOOGLE_CREDENTIALS_FILE",
+    }).pipe(Effect.catchTag("NotFound", () => Effect.succeed(undefined)));
+    // List all user-managed keys for the SA. Used for cold recovery
+    // when the key name is not in state. Returns the first
+    // user-managed key found (the SA is dedicated to this resource,
+    // so there should be at most one user-managed key).
+    const findUserManagedKey = Effect.fn(function* (serviceAccount) {
+        const page = yield* listProjectsServiceAccountsKeys({
+            name: serviceAccount,
+            keyTypes: "USER_MANAGED",
+        });
+        const keys = page.keys ?? [];
+        if (keys.length === 0)
+            return undefined;
+        if (keys.length === 1)
+            return keys[0];
+        // Multiple user-managed keys — GCP allows multiple keys per
+        // SA, so creating another would silently succeed (not
+        // Conflict as an earlier comment assumed). Surface an error
+        // so the user cleans up the extra keys and re-runs.
+        return yield* Effect.fail(new ConfigError({
+            message: `Service account ${serviceAccount} has ${keys.length} user-managed keys; ` +
+                `cannot determine which to adopt. Delete the extra keys and re-run.`,
+        }));
+    });
+    return {
+        // privateKeyData is stable: it's set on create and never
+        // changes. The engine preserves it across reconciles and
+        // does not use it for drift detection.
+        stables: ["name", "privateKeyData", "keyAlgorithm", "keyType"],
+        diff: Effect.fn(function* ({ news, olds = {} }) {
+            if (!isResolved(news))
+                return undefined;
+            const priorSa = olds.serviceAccount;
+            const priorKeyAlgorithm = olds.keyAlgorithm;
+            const priorPrivateKeyType = olds.privateKeyType;
+            if ((priorSa && news.serviceAccount !== priorSa) ||
+                (priorKeyAlgorithm && news.keyAlgorithm !== priorKeyAlgorithm) ||
+                (priorPrivateKeyType &&
+                    news.privateKeyType !== priorPrivateKeyType)) {
+                return { action: "replace" };
+            }
+            return undefined;
+        }),
+        reconcile: Effect.fn(function* ({ id, news, output }) {
+            // 1. Observe — check if the key exists by name (from
+            //    state output). Fall back to listing user-managed
+            //    keys for cold recovery.
+            const keyName = output?.name;
+            let observed;
+            if (keyName) {
+                observed = yield* observeKey(keyName);
+            }
+            if (!observed) {
+                observed = yield* findUserManagedKey(news.serviceAccount);
+            }
+            // 2. Ensure — create if missing. If the key exists but
+            //    privateKeyData is not in state (state loss), delete
+            //    the old key and create a new one so privateKeyData is
+            //    re-obtained.
+            if (!observed) {
+                const created = yield* createProjectsServiceAccountsKeys({
+                    name: news.serviceAccount,
+                    body: {
+                        privateKeyType: news.privateKeyType ?? "TYPE_GOOGLE_CREDENTIALS_FILE",
+                        keyAlgorithm: news.keyAlgorithm ?? "KEY_ALG_RSA_2048",
+                    },
+                });
+                return toAttributes(created);
+            }
+            // Key exists. If it is the same key we created before, preserve
+            // privateKeyData from state. If the name differs, the key was
+            // swapped out-of-band — fall through to delete + recreate so
+            // privateKeyData matches the live key.
+            if (output?.privateKeyData && observed.name === output.name) {
+                return {
+                    ...toAttributes(observed),
+                    privateKeyData: output.privateKeyData,
+                };
+            }
+            // privateKeyData is missing from state. Only delete + recreate
+            // when we can PROVE the observed key is ours: output.name must
+            // be set and match. SA keys carry no labels, so on cold recovery
+            // (output undefined) a found key might be pre-existing or
+            // manually rotated — deleting it would destroy someone else's
+            // credentials. Fail instead and ask the user to clean up.
+            if (output?.name && observed.name === output.name) {
+                yield* deleteProjectsServiceAccountsKeys({
+                    name: observed.name,
+                }).pipe(Effect.catchTag("NotFound", () => Effect.void));
+                const created = yield* createProjectsServiceAccountsKeys({
+                    name: news.serviceAccount,
+                    body: {
+                        privateKeyType: news.privateKeyType ?? "TYPE_GOOGLE_CREDENTIALS_FILE",
+                        keyAlgorithm: news.keyAlgorithm ?? "KEY_ALG_RSA_2048",
+                    },
+                });
+                return toAttributes(created);
+            }
+            // Key exists but we can't prove ownership. Don't delete it.
+            return yield* Effect.fail(new ConfigError({
+                message: `Service account key ${observed.name} exists on ${news.serviceAccount} ` +
+                    `but cannot be verified as ours (no matching state). ` +
+                    `Delete it manually and re-run to create a fresh key.`,
+            }));
+        }),
+        delete: Effect.fn(function* ({ output }) {
+            yield* deleteProjectsServiceAccountsKeys({
+                name: output.name,
+            }).pipe(Effect.catchTag("NotFound", () => Effect.void), Effect.catchTag("Forbidden", () => Effect.void));
+        }),
+        read: Effect.fn(function* ({ id, output, olds }) {
+            const keyName = output?.name;
+            const serviceAccount = olds.serviceAccount;
+            let observed;
+            if (keyName) {
+                observed = yield* observeKey(keyName);
+            }
+            if (!observed && serviceAccount) {
+                observed = yield* findUserManagedKey(serviceAccount);
+            }
+            if (!observed)
+                return undefined;
+            // privateKeyData is not available from get/list — preserve it
+            // from state output only when it still describes this key.
+            const privateKeyData = output?.name && observed.name === output.name
+                ? output.privateKeyData
+                : undefined;
+            return {
+                ...toAttributes(observed),
+                privateKeyData,
+            };
+        }),
+    };
+}));
+//# sourceMappingURL=ServiceAccountKey.js.map

package/lib/Iam/ServiceAccountKey.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ServiceAccountKey.js","sourceRoot":"","sources":["../../src/Iam/ServiceAccountKey.ts"],"names":[],"mappings":"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"}

package/lib/Iam/index.d.ts

@@ -0,0 +1,6 @@
+export { ServiceAccount, ServiceAccountProvider } from "./ServiceAccount.ts";
+export type { ServiceAccountProps } from "./ServiceAccount.ts";
+export * from "./ServiceAccountIamMember.ts";
+export { ServiceAccountKey, ServiceAccountKeyProvider, } from "./ServiceAccountKey.ts";
+export type { ServiceAccountKeyProps } from "./ServiceAccountKey.ts";
+//# sourceMappingURL=index.d.ts.map

package/lib/Iam/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/Iam/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,sBAAsB,EAAE,MAAM,qBAAqB,CAAC;AAC7E,YAAY,EAAE,mBAAmB,EAAE,MAAM,qBAAqB,CAAC;AAC/D,cAAc,8BAA8B,CAAC;AAC7C,OAAO,EACL,iBAAiB,EACjB,yBAAyB,GAC1B,MAAM,wBAAwB,CAAC;AAChC,YAAY,EAAE,sBAAsB,EAAE,MAAM,wBAAwB,CAAC"}