@intentius/chant-lexicon-gcp 0.124.33 → 0.124.35

package/dist/op/activities/gcp-iam.d.ts

@@ -0,0 +1,82 @@
+/**
+ * IAMPolicyMember (#4233): one member in one role on one resource's IAM policy.
+ *
+ * GCP has no REST resource for a single binding member. The member lives inside
+ * the target's policy, read with `getIamPolicy` and written whole with
+ * `setIamPolicy`. So this mapper does not fit the GET-then-create plan the other
+ * kinds use: apply reads the policy, adds the member to the role's binding when
+ * it is missing and writes the policy back with its `etag`; delete removes it
+ * the same way. Other members and bindings are kept as read (a merge, never an
+ * overwrite), and a write that loses an `etag` race is retried.
+ *
+ * Targets are the kinds `resourceRef` can name that have an IAM policy chant can
+ * reach: Project, RunService, IAMServiceAccount, StorageBucket, PubSubTopic,
+ * PubSubSubscription and SecretManagerSecret. Any other target is reported as
+ * not attempted, the way a kind with no mapper is.
+ */
+import type { GcpResource, ResourceMapper } from "./gcp-apply.js";
+/** The CNRM IAMPolicyMember spec chant reads. */
+export interface IamPolicyMemberSpec {
+    member?: string;
+    role?: string;
+    resourceRef?: {
+        kind?: string;
+        name?: string;
+        external?: string;
+        apiVersion?: string;
+    };
+    condition?: {
+        title?: string;
+        description?: string;
+        expression?: string;
+    };
+    location?: string;
+}
+interface Binding {
+    role: string;
+    members?: string[];
+    condition?: {
+        title?: string;
+        description?: string;
+        expression?: string;
+    };
+}
+interface Policy {
+    version?: number;
+    etag?: string;
+    bindings?: Binding[];
+}
+/** Where a target's policy is read and written. */
+export interface IamTarget {
+    /** Real-GCP host for the target's service. */
+    host: string;
+    /** The target's resource path, used in messages and in the read body. */
+    path: string;
+    get: (base: string) => {
+        method: "GET" | "POST";
+        url: string;
+        body?: unknown;
+    };
+    set: (base: string, policy: Policy) => {
+        method: "POST" | "PUT";
+        url: string;
+        body: unknown;
+    };
+}
+/** The default host this mapper reports; a target's own host replaces it when there is no endpoint override. */
+export declare const IAM_DEFAULT_HOST = "https://iam.googleapis.com";
+/**
+ * Resolve `resourceRef` to the target's policy endpoints, or undefined for a
+ * target chant cannot reach. `manifest` is the rest of the applied manifest, so
+ * a RunService named by `name` takes its region from its own spec. Pure.
+ */
+export declare function iamTarget(spec: IamPolicyMemberSpec, project: string, manifest?: readonly GcpResource[], env?: NodeJS.ProcessEnv): IamTarget | undefined;
+/** True when the policy grants the spec's member in its role (and condition). Pure. */
+export declare function policyHasMember(policy: Policy, spec: IamPolicyMemberSpec): boolean;
+/** The policy with the spec's member added to its binding, every other binding kept. Pure. */
+export declare function withMember(policy: Policy, spec: IamPolicyMemberSpec): Policy;
+/** The policy with the spec's member removed; a binding left with no members is dropped. Pure. */
+export declare function withoutMember(policy: Policy, spec: IamPolicyMemberSpec): Policy;
+export declare const iamPolicyMemberMapper: ResourceMapper;
+export {};
+//# sourceMappingURL=gcp-iam.d.ts.map

package/dist/op/activities/gcp-iam.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"gcp-iam.d.ts","sourceRoot":"","sources":["../../../src/op/activities/gcp-iam.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AACH,OAAO,KAAK,EAAW,WAAW,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAExE,iDAAiD;AACjD,MAAM,WAAW,mBAAmB;IAClC,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,WAAW,CAAC,EAAE;QAAE,IAAI,CAAC,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;QAAC,UAAU,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IACvF,SAAS,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,MAAM,CAAC;QAAC,WAAW,CAAC,EAAE,MAAM,CAAC;QAAC,UAAU,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IAC1E,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,UAAU,OAAO;IACf,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;IACnB,SAAS,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,MAAM,CAAC;QAAC,WAAW,CAAC,EAAE,MAAM,CAAC;QAAC,UAAU,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;CAC3E;AAED,UAAU,MAAM;IACd,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,QAAQ,CAAC,EAAE,OAAO,EAAE,CAAC;CACtB;AAED,mDAAmD;AACnD,MAAM,WAAW,SAAS;IACxB,8CAA8C;IAC9C,IAAI,EAAE,MAAM,CAAC;IACb,yEAAyE;IACzE,IAAI,EAAE,MAAM,CAAC;IACb,GAAG,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK;QAAE,MAAM,EAAE,KAAK,GAAG,MAAM,CAAC;QAAC,GAAG,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,OAAO,CAAA;KAAE,CAAC;IAC/E,GAAG,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,KAAK;QAAE,MAAM,EAAE,MAAM,GAAG,KAAK,CAAC;QAAC,GAAG,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,OAAO,CAAA;KAAE,CAAC;CAC/F;AAED,gHAAgH;AAChH,eAAO,MAAM,gBAAgB,+BAA+B,CAAC;AAqB7D;;;;GAIG;AACH,wBAAgB,SAAS,CACvB,IAAI,EAAE,mBAAmB,EACzB,OAAO,EAAE,MAAM,EACf,QAAQ,GAAE,SAAS,WAAW,EAAO,EACrC,GAAG,GAAE,MAAM,CAAC,UAAwB,GACnC,SAAS,GAAG,SAAS,CAgDvB;AAYD,uFAAuF;AACvF,wBAAgB,eAAe,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,mBAAmB,GAAG,OAAO,CAElF;AAED,8FAA8F;AAC9F,wBAAgB,UAAU,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,mBAAmB,GAAG,MAAM,CAY5E;AAED,kGAAkG;AAClG,wBAAgB,aAAa,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,mBAAmB,GAAG,MAAM,CAS/E;AAkED,eAAO,MAAM,qBAAqB,EAAE,cA8CnC,CAAC"}

package/dist/op/activities/gcp-iam.js

@@ -0,0 +1,215 @@
+/** The default host this mapper reports; a target's own host replaces it when there is no endpoint override. */
+export const IAM_DEFAULT_HOST = "https://iam.googleapis.com";
+const enc = encodeURIComponent;
+function region(env = process.env) {
+    return env.GCP_REGION || "us-central1";
+}
+/** A `:getIamPolicy` / `:setIamPolicy` pair on a REST resource path (the Google API convention). */
+function verbTarget(host, version, path, getMethod) {
+    return {
+        host,
+        path,
+        get: (base) => getMethod === "GET"
+            ? { method: "GET", url: `${base}/${version}/${path}:getIamPolicy?options.requestedPolicyVersion=3` }
+            : { method: "POST", url: `${base}/${version}/${path}:getIamPolicy`, body: { options: { requestedPolicyVersion: 3 } } },
+        set: (base, policy) => ({ method: "POST", url: `${base}/${version}/${path}:setIamPolicy`, body: { policy } }),
+    };
+}
+/**
+ * Resolve `resourceRef` to the target's policy endpoints, or undefined for a
+ * target chant cannot reach. `manifest` is the rest of the applied manifest, so
+ * a RunService named by `name` takes its region from its own spec. Pure.
+ */
+export function iamTarget(spec, project, manifest = [], env = process.env) {
+    const ref = spec.resourceRef ?? {};
+    const external = typeof ref.external === "string" && ref.external !== "" ? ref.external : undefined;
+    const name = typeof ref.name === "string" && ref.name !== "" ? ref.name : undefined;
+    switch (ref.kind) {
+        case "Project": {
+            const id = external ? external.replace(/^projects\//, "") : (name ?? project);
+            return verbTarget("https://cloudresourcemanager.googleapis.com", "v1", `projects/${enc(id)}`, "POST");
+        }
+        case "RunService": {
+            if (external)
+                return verbTarget("https://run.googleapis.com", "v2", external, "GET");
+            if (!name)
+                return undefined;
+            const declared = manifest.find((r) => r.kind === "RunService" && r.metadata?.name === name);
+            const location = declared?.spec?.location;
+            const loc = typeof location === "string" ? location : (spec.location ?? region(env));
+            return verbTarget("https://run.googleapis.com", "v2", `projects/${enc(project)}/locations/${enc(loc)}/services/${enc(name)}`, "GET");
+        }
+        case "IAMServiceAccount": {
+            if (external?.startsWith("projects/"))
+                return verbTarget(IAM_DEFAULT_HOST, "v1", external, "POST");
+            const email = external ?? (name ? `${name}@${project}.iam.gserviceaccount.com` : undefined);
+            if (!email)
+                return undefined;
+            return verbTarget(IAM_DEFAULT_HOST, "v1", `projects/${enc(project)}/serviceAccounts/${email}`, "POST");
+        }
+        case "PubSubTopic":
+        case "PubSubSubscription": {
+            const collection = ref.kind === "PubSubTopic" ? "topics" : "subscriptions";
+            const path = external ?? (name ? `projects/${enc(project)}/${collection}/${enc(name)}` : undefined);
+            return path ? verbTarget("https://pubsub.googleapis.com", "v1", path, "GET") : undefined;
+        }
+        case "SecretManagerSecret": {
+            const path = external ?? (name ? `projects/${enc(project)}/secrets/${enc(name)}` : undefined);
+            return path ? verbTarget("https://secretmanager.googleapis.com", "v1", path, "GET") : undefined;
+        }
+        case "StorageBucket": {
+            const bucket = external ? external.replace(/^(gs:\/\/|projects\/_\/buckets\/)/, "") : name;
+            if (!bucket)
+                return undefined;
+            // GCS has its own IAM shape: GET and PUT on `b/<bucket>/iam`, with the policy as the body.
+            const url = (base) => `${base}/storage/v1/b/${enc(bucket)}/iam`;
+            return {
+                host: "https://storage.googleapis.com",
+                path: `b/${bucket}`,
+                get: (base) => ({ method: "GET", url: `${url(base)}?optionsRequestedPolicyVersion=3` }),
+                set: (base, policy) => ({ method: "PUT", url: url(base), body: policy }),
+            };
+        }
+        default:
+            return undefined;
+    }
+}
+function sameCondition(a, b) {
+    if (!a && !b)
+        return true;
+    if (!a || !b)
+        return false;
+    return (a.expression ?? "") === (b.expression ?? "") && (a.title ?? "") === (b.title ?? "");
+}
+function findBinding(policy, spec) {
+    return policy.bindings?.find((b) => b.role === spec.role && sameCondition(b.condition, spec.condition));
+}
+/** True when the policy grants the spec's member in its role (and condition). Pure. */
+export function policyHasMember(policy, spec) {
+    return findBinding(policy, spec)?.members?.includes(spec.member ?? "") ?? false;
+}
+/** The policy with the spec's member added to its binding, every other binding kept. Pure. */
+export function withMember(policy, spec) {
+    const member = spec.member;
+    const bindings = (policy.bindings ?? []).map((b) => ({ ...b, members: [...(b.members ?? [])] }));
+    const existing = bindings.find((b) => b.role === spec.role && sameCondition(b.condition, spec.condition));
+    if (existing) {
+        if (!existing.members.includes(member))
+            existing.members.push(member);
+    }
+    else {
+        bindings.push({ role: spec.role, members: [member], ...(spec.condition ? { condition: spec.condition } : {}) });
+    }
+    // A conditional binding needs policy version 3; otherwise keep what was read.
+    const version = spec.condition || bindings.some((b) => b.condition) ? 3 : policy.version;
+    return { ...policy, bindings, ...(version !== undefined ? { version } : {}) };
+}
+/** The policy with the spec's member removed; a binding left with no members is dropped. Pure. */
+export function withoutMember(policy, spec) {
+    const bindings = (policy.bindings ?? [])
+        .map((b) => b.role === spec.role && sameCondition(b.condition, spec.condition)
+        ? { ...b, members: (b.members ?? []).filter((m) => m !== spec.member) }
+        : b)
+        .filter((b) => (b.members ?? []).length > 0);
+    return { ...policy, bindings };
+}
+function specOf(resource) {
+    const spec = (resource.spec ?? {});
+    const name = resource.metadata?.name ?? "?";
+    if (!spec.member)
+        throw new Error(`IAMPolicyMember ${name} has no spec.member`);
+    if (!spec.role)
+        throw new Error(`IAMPolicyMember ${name} has no spec.role`);
+    return spec;
+}
+function targetOf(resource, ctx, env) {
+    const target = iamTarget(specOf(resource), ctx.project, ctx.manifest, env);
+    if (!target) {
+        const ref = resource.spec?.resourceRef;
+        throw new Error(`IAMPolicyMember ${resource.metadata?.name ?? "?"}: no IAM policy endpoint for resourceRef kind ${ref?.kind ?? "(none)"}`);
+    }
+    // No endpoint override: each target's own service host. An override (floci-gcp) serves every service.
+    const base = ctx.base === IAM_DEFAULT_HOST ? target.host : ctx.base;
+    return { target, base };
+}
+async function readPolicy(target, base, http, signal) {
+    const req = target.get(base);
+    const res = await http(req.method, req.url, req.body, signal);
+    if (res.status >= 300)
+        return res;
+    let policy;
+    try {
+        policy = JSON.parse(res.text);
+    }
+    catch {
+        policy = {};
+    }
+    return { ...res, policy };
+}
+/** How many times a write that loses an `etag` race (409, or 412 on GCS) is retried. */
+const ETAG_ATTEMPTS = 3;
+async function writeWith(resource, ctx, http, signal, change) {
+    const spec = specOf(resource);
+    const { target, base } = targetOf(resource, ctx);
+    const name = resource.metadata?.name ?? "?";
+    for (let attempt = 1;; attempt++) {
+        const read = await readPolicy(target, base, http, signal);
+        if (!read.policy)
+            throw new Error(`IAMPolicyMember ${name}: reading the policy of ${target.path} failed (${read.status}): ${read.text}`);
+        const next = change(read.policy, spec);
+        if (!next)
+            return false;
+        const req = target.set(base, next);
+        const res = await http(req.method, req.url, req.body, signal);
+        if (res.status < 300)
+            return true;
+        if ((res.status === 409 || res.status === 412) && attempt < ETAG_ATTEMPTS)
+            continue;
+        throw new Error(`IAMPolicyMember ${name}: writing the policy of ${target.path} failed (${res.status}): ${res.text}`);
+    }
+}
+export const iamPolicyMemberMapper = {
+    kind: "IAMPolicyMember",
+    defaultHost: IAM_DEFAULT_HOST,
+    accepts(resource, ctx) {
+        return iamTarget((resource.spec ?? {}), ctx.project, ctx.manifest) !== undefined;
+    },
+    plan(resource, ctx) {
+        // Only the read is a single URL here; apply and delete go through `custom`.
+        const { target, base } = targetOf(resource, ctx);
+        const get = target.get(base);
+        return { getUrl: get.url, create: { method: "POST", url: get.url, body: get.body ?? {} } };
+    },
+    custom: {
+        async apply(resource, ctx, http, signal) {
+            const created = await writeWith(resource, ctx, http, signal, (policy, spec) => policyHasMember(policy, spec) ? undefined : withMember(policy, spec));
+            return { created, updated: false };
+        },
+        async delete(resource, ctx, http, signal) {
+            return writeWith(resource, ctx, http, signal, (policy, spec) => policyHasMember(policy, spec) ? withoutMember(policy, spec) : undefined);
+        },
+        async read(resource, ctx, http, signal) {
+            const spec = specOf(resource);
+            const { target, base } = targetOf(resource, ctx);
+            const read = await readPolicy(target, base, http, signal);
+            if (!read.policy)
+                return read;
+            // The binding member is the resource: absent from the policy reads as absent.
+            if (!policyHasMember(read.policy, spec))
+                return { status: 404, text: `${spec.member} has no ${spec.role} on ${target.path}` };
+            const binding = findBinding(read.policy, spec);
+            return {
+                status: 200,
+                // `resourceRef` is the declared one: the policy read is that target's, so the binding is on it.
+                text: JSON.stringify({
+                    member: spec.member,
+                    role: spec.role,
+                    resource: target.path,
+                    ...(spec.resourceRef ? { resourceRef: spec.resourceRef } : {}),
+                    ...(binding?.condition ? { condition: binding.condition } : {}),
+                    ...(read.policy.etag ? { etag: read.policy.etag } : {}),
+                }),
+            };
+        },
+    },
+};

package/dist/op/activities/index.d.ts

@@ -4,7 +4,7 @@
  * (`gcpApply`), which maps CNRM resources to GCP REST calls since GCP has no
  * native deployment service to shell out to.
  */
-export { gcpApply, gcpDelete, applyResource, deleteResource, waitForOperation, longRunningOperation, bucketInsertBody, pubSubTopicBody, pubSubSubscriptionBody, cloudRunServiceBody, secretBody, serviceAccountBody, storageBucketMapper, pubSubTopicMapper, pubSubSubscriptionMapper, cloudRunServiceMapper, secretManagerSecretMapper, gcpServiceAccountMapper, MAPPERS, referencedNames, orderByReferences, pruneOrphans, toApplyResult, type GcpNotAttempted, type GcpNotPrunable, chantOwnershipLabels, isChantOwned, resolveGcpEndpoint, resolveGcpProject, parseManifest, } from "./gcp-apply.js";
+export { gcpApply, gcpDelete, applyResource, deleteResource, waitForOperation, longRunningOperation, bucketInsertBody, pubSubTopicBody, pubSubSubscriptionBody, cloudRunServiceBody, secretBody, serviceAccountBody, storageBucketMapper, pubSubTopicMapper, pubSubSubscriptionMapper, cloudRunServiceMapper, secretManagerSecretMapper, gcpServiceAccountMapper, MAPPERS, referencedNames, orderByReferences, pruneOrphans, toApplyResult, type GcpNotAttempted, type GcpNotPrunable, chantOwnershipLabels, isChantOwned, resolveGcpEndpoint, resolveGcpProject, projectRefProject, parseManifest, } from "./gcp-apply.js";
 export type { GcpApplyArgs, GcpResource, CnrmStorageBucket, BucketInsertBody, PubSubTopicBody, ResourceMapper, OperationSpec, ListSpec, ApplyPlan, GcpHttp, } from "./gcp-apply.js";
 export { flociGcpUp, flociGcpDown, flociGcpRunCommand, flociGcpRmCommand, flociGcpExistsCommand, flociGcpHealthUrl, flociGcpEndpoint, } from "./floci-gcp.js";
 export type { FlociGcpUpArgs, FlociGcpDownArgs } from "./floci-gcp.js";

package/dist/op/activities/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/op/activities/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,OAAO,EACL,QAAQ,EACR,SAAS,EACT,aAAa,EACb,cAAc,EACd,gBAAgB,EAChB,oBAAoB,EACpB,gBAAgB,EAChB,eAAe,EACf,sBAAsB,EACtB,mBAAmB,EACnB,UAAU,EACV,kBAAkB,EAClB,mBAAmB,EACnB,iBAAiB,EACjB,wBAAwB,EACxB,qBAAqB,EACrB,yBAAyB,EACzB,uBAAuB,EACvB,OAAO,EACP,eAAe,EACf,iBAAiB,EACjB,YAAY,EACZ,aAAa,EACb,KAAK,eAAe,EACpB,KAAK,cAAc,EACnB,oBAAoB,EACpB,YAAY,EACZ,kBAAkB,EAClB,iBAAiB,EACjB,aAAa,GACd,MAAM,aAAa,CAAC;AACrB,YAAY,EACV,YAAY,EACZ,WAAW,EACX,iBAAiB,EACjB,gBAAgB,EAChB,eAAe,EACf,cAAc,EACd,aAAa,EACb,QAAQ,EACR,SAAS,EACT,OAAO,GACR,MAAM,aAAa,CAAC;AAIrB,OAAO,EACL,UAAU,EACV,YAAY,EACZ,kBAAkB,EAClB,iBAAiB,EACjB,qBAAqB,EACrB,iBAAiB,EACjB,gBAAgB,GACjB,MAAM,aAAa,CAAC;AACrB,YAAY,EAAE,cAAc,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/op/activities/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,OAAO,EACL,QAAQ,EACR,SAAS,EACT,aAAa,EACb,cAAc,EACd,gBAAgB,EAChB,oBAAoB,EACpB,gBAAgB,EAChB,eAAe,EACf,sBAAsB,EACtB,mBAAmB,EACnB,UAAU,EACV,kBAAkB,EAClB,mBAAmB,EACnB,iBAAiB,EACjB,wBAAwB,EACxB,qBAAqB,EACrB,yBAAyB,EACzB,uBAAuB,EACvB,OAAO,EACP,eAAe,EACf,iBAAiB,EACjB,YAAY,EACZ,aAAa,EACb,KAAK,eAAe,EACpB,KAAK,cAAc,EACnB,oBAAoB,EACpB,YAAY,EACZ,kBAAkB,EAClB,iBAAiB,EACjB,iBAAiB,EACjB,aAAa,GACd,MAAM,aAAa,CAAC;AACrB,YAAY,EACV,YAAY,EACZ,WAAW,EACX,iBAAiB,EACjB,gBAAgB,EAChB,eAAe,EACf,cAAc,EACd,aAAa,EACb,QAAQ,EACR,SAAS,EACT,OAAO,GACR,MAAM,aAAa,CAAC;AAIrB,OAAO,EACL,UAAU,EACV,YAAY,EACZ,kBAAkB,EAClB,iBAAiB,EACjB,qBAAqB,EACrB,iBAAiB,EACjB,gBAAgB,GACjB,MAAM,aAAa,CAAC;AACrB,YAAY,EAAE,cAAc,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC"}

package/dist/op/activities/index.js

@@ -4,7 +4,7 @@
  * (`gcpApply`), which maps CNRM resources to GCP REST calls since GCP has no
  * native deployment service to shell out to.
  */
-export { gcpApply, gcpDelete, applyResource, deleteResource, waitForOperation, longRunningOperation, bucketInsertBody, pubSubTopicBody, pubSubSubscriptionBody, cloudRunServiceBody, secretBody, serviceAccountBody, storageBucketMapper, pubSubTopicMapper, pubSubSubscriptionMapper, cloudRunServiceMapper, secretManagerSecretMapper, gcpServiceAccountMapper, MAPPERS, referencedNames, orderByReferences, pruneOrphans, toApplyResult, chantOwnershipLabels, isChantOwned, resolveGcpEndpoint, resolveGcpProject, parseManifest, } from "./gcp-apply.js";
+export { gcpApply, gcpDelete, applyResource, deleteResource, waitForOperation, longRunningOperation, bucketInsertBody, pubSubTopicBody, pubSubSubscriptionBody, cloudRunServiceBody, secretBody, serviceAccountBody, storageBucketMapper, pubSubTopicMapper, pubSubSubscriptionMapper, cloudRunServiceMapper, secretManagerSecretMapper, gcpServiceAccountMapper, MAPPERS, referencedNames, orderByReferences, pruneOrphans, toApplyResult, chantOwnershipLabels, isChantOwned, resolveGcpEndpoint, resolveGcpProject, projectRefProject, parseManifest, } from "./gcp-apply.js";
 // floci-gcp (GCP emulator) lifecycle — the typed twin of aws's flociUp/Down, so
 // the trio's GCP op boots/tears down the emulator as a modeled step, not a shell.
 export { flociGcpUp, flociGcpDown, flociGcpRunCommand, flociGcpRmCommand, flociGcpExistsCommand, flociGcpHealthUrl, flociGcpEndpoint, } from "./floci-gcp.js";

package/dist/serializer.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"serializer.d.ts","sourceRoot":"","sources":["../src/serializer.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAMH,OAAO,KAAK,EAAE,UAAU,EAAsC,MAAM,6BAA6B,CAAC;AAiClG;;;;;;;GAOG;AACH,wBAAgB,UAAU,CAAC,UAAU,EAAE,MAAM,GAAG;IAAE,UAAU,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GAAG,IAAI,CAW1F;AAsED;;GAEG;AACH,eAAO,MAAM,aAAa,EAAE,UA6F3B,CAAC"}
+{"version":3,"file":"serializer.d.ts","sourceRoot":"","sources":["../src/serializer.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAMH,OAAO,KAAK,EAAE,UAAU,EAAsC,MAAM,6BAA6B,CAAC;AAiClG;;;;;;;GAOG;AACH,wBAAgB,UAAU,CAAC,UAAU,EAAE,MAAM,GAAG;IAAE,UAAU,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GAAG,IAAI,CAW1F;AAsED;;GAEG;AACH,eAAO,MAAM,aAAa,EAAE,UAiG3B,CAAC"}

package/dist/serializer.js

@@ -131,6 +131,7 @@ export const gcpSerializer = {
             }
         }
         const documents = [];
+        const unresolved = [];
         for (const [name, entity] of entities) {
             if (isPropertyDeclarable(entity))
                 continue;
@@ -140,7 +141,7 @@ export const gcpSerializer = {
             const gvk = resolveGVK(entityType);
             if (!gvk)
                 continue;
-            const props = toYAMLValue(isResourceDeclarable(entity) ? entity.props : undefined, entityNames);
+            const props = resolvePseudoParameters(toYAMLValue(isResourceDeclarable(entity) ? entity.props : undefined, entityNames), name, unresolved);
             if (!props)
                 continue;
             // Build the Config Connector manifest structure
@@ -181,6 +182,8 @@ export const gcpSerializer = {
             const yamlDoc = emitK8sManifest(manifest);
             documents.push(yamlDoc);
         }
+        if (unresolved.length > 0)
+            throw new Error(unresolvedMessage(unresolved));
         const primary = documents.join("\n---\n");
         const warnings = unwritableOutputWarnings(outputs);
         return warnings.length > 0 ? { primary, warnings } : primary;
@@ -196,6 +199,38 @@ const PSEUDO_ENV_MAP = {
     "GCP::Region": { envVar: "GCP_REGION", fallback: "us-central1" },
     "GCP::Zone": { envVar: "GCP_ZONE", fallback: "us-central1-a" },
 };
+/**
+ * Replace each GCP pseudo-parameter (`{ Ref: "GCP::Region" }`) in a
+ * serialized resource with its environment variable's value (#4200).
+ * Config Connector has no parameters, so a `Ref` left in the YAML reaches
+ * the API as an object. A variable that isn't set is recorded, and the
+ * build refuses with every one named.
+ */
+function resolvePseudoParameters(value, entity, unresolved) {
+    if (Array.isArray(value))
+        return value.map((v) => resolvePseudoParameters(v, entity, unresolved));
+    if (value === null || typeof value !== "object")
+        return value;
+    const obj = value;
+    const keys = Object.keys(obj);
+    if (keys.length === 1 && keys[0] === "Ref" && typeof obj.Ref === "string" && obj.Ref in PSEUDO_ENV_MAP) {
+        const { envVar } = PSEUDO_ENV_MAP[obj.Ref];
+        const resolved = process.env[envVar];
+        if (resolved)
+            return resolved;
+        unresolved.push({ entity, ref: obj.Ref, envVar });
+        return value;
+    }
+    const out = {};
+    for (const [k, v] of Object.entries(obj))
+        out[k] = resolvePseudoParameters(v, entity, unresolved);
+    return out;
+}
+function unresolvedMessage(unresolved) {
+    const vars = [...new Set(unresolved.map((u) => u.envVar))];
+    const lines = unresolved.map((u) => `  ${u.entity}: ${u.ref} needs ${u.envVar}`);
+    return `gcp: ${vars.join(", ")} ${vars.length === 1 ? "is" : "are"} not set, and Config Connector YAML can't carry a pseudo-parameter. Set ${vars.length === 1 ? "it" : "them"} at build, or pass the value explicitly:\n${lines.join("\n")}`;
+}
 /**
  * Resolve an annotation value to a plain string.
  * PseudoParameter intrinsics are resolved from environment variables;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@intentius/chant-lexicon-gcp",
-  "version": "0.124.33",
+  "version": "0.124.35",
   "description": "Google Cloud lexicon for chant — declarative IaC in TypeScript",
   "license": "Apache-2.0",
   "homepage": "https://intentius.io/chant",
@@ -76,6 +76,6 @@
     "typescript": "^5.9.3"
   },
   "peerDependencies": {
-    "@intentius/chant": "^0.124.33"
+    "@intentius/chant": "^0.124.35"
   }
 }

package/src/api/read-client.ts

@@ -22,7 +22,11 @@
  *
  * Coverage is exactly the applier's dispatch table (`MAPPERS`) — StorageBucket,
  * PubSubTopic, PubSubSubscription, SecretManagerSecret, IAMServiceAccount,
- * RunService. The kubectl path could fetch any CNRM kind the cluster knew
+ * RunService, IAMPolicyMember and the Cloud Run load balancer kinds
+ * (ComputeAddress, ComputeRegionNetworkEndpointGroup, ComputeBackendService,
+ * ComputeURLMap, ComputeTargetHTTPProxy, ComputeForwardingRule; #4233). An
+ * IAMPolicyMember is read through its target's policy and is present when the
+ * policy grants its member the role. The kubectl path could fetch any CNRM kind the cluster knew
  * about, so this is narrower on paper. It is not narrower in practice for
  * anything chant can act on: a kind with no mapper cannot be applied either, so
  * observing it produced a live tree nothing could ever reconcile against.
@@ -44,11 +48,14 @@ export interface GcpReadClientOptions {
   http?: GcpReadHttp;
 }
 
-/** Injectable HTTP client — mirrors the applier's `GcpHttp`. */
-export type GcpReadHttp = (method: string, url: string) => Promise<{ status: number; text: string }>;
+/** Injectable HTTP client — mirrors the applier's `GcpHttp`. A body is sent only for a POST read (`:getIamPolicy`). */
+export type GcpReadHttp = (method: string, url: string, body?: unknown) => Promise<{ status: number; text: string }>;
 
-const defaultHttp: GcpReadHttp = async (method, url) => {
-  const res = await fetch(url, { method });
+const defaultHttp: GcpReadHttp = async (method, url, body) => {
+  const res = await fetch(url, {
+    method,
+    ...(body === undefined ? {} : { headers: { "content-type": "application/json" }, body: JSON.stringify(body) }),
+  });
   return { status: res.status, text: await res.text() };
 };
 
@@ -100,21 +107,33 @@ export async function getResource(
     spec: (declared?.spec as Record<string, unknown> | undefined) ?? declared ?? {},
   };
 
-  let getUrl: string;
-  try {
-    getUrl = mapper.plan(resource, { base, project: client.project }).getUrl;
-  } catch (err) {
-    // A mapper that cannot plan from the declared spec cannot produce a URL, so
-    // there is nothing to read — a hole, never an absence.
-    throw new GcpReadError(`could not build a read URL for ${kind}/${name}: ${err instanceof Error ? err.message : String(err)}`);
+  const ctx = { base, project: client.project };
+  if (mapper.accepts && !mapper.accepts(resource, ctx)) {
+    throw new GcpReadError(`no REST read for ${kind}/${name}: its target has no endpoint chant can read`);
   }
 
   const http = client.http ?? defaultHttp;
   let res: { status: number; text: string };
-  try {
-    res = await http("GET", getUrl);
-  } catch (err) {
-    throw new GcpReadError(err instanceof Error ? err.message : String(err));
+  if (mapper.custom) {
+    try {
+      res = await mapper.custom.read(resource, ctx, (method, url, body) => http(method, url, body));
+    } catch (err) {
+      throw new GcpReadError(`could not read ${kind}/${name}: ${err instanceof Error ? err.message : String(err)}`);
+    }
+  } else {
+    let getUrl: string;
+    try {
+      getUrl = mapper.plan(resource, ctx).getUrl;
+    } catch (err) {
+      // A mapper that cannot plan from the declared spec cannot produce a URL, so
+      // there is nothing to read — a hole, never an absence.
+      throw new GcpReadError(`could not build a read URL for ${kind}/${name}: ${err instanceof Error ? err.message : String(err)}`);
+    }
+    try {
+      res = await http("GET", getUrl);
+    } catch (err) {
+      throw new GcpReadError(err instanceof Error ? err.message : String(err));
+    }
   }
 
   if (res.status === 404) throw new GcpReadError(`${kind}/${name} not found`, 404);

package/src/composites/cloud-run-service.ts

@@ -34,6 +34,8 @@ export interface CloudRunServiceProps {
   publicAccess?: boolean;
   /** Environment variables. */
   env?: Array<{ name: string; value: string }>;
+  /** Service account the service runs as: an email, or the account id of an IAMServiceAccount in the project. */
+  serviceAccount?: string;
   /** Additional labels. */
   labels?: Record<string, string>;
   /** Namespace for all resources. */
@@ -75,6 +77,7 @@ export const CloudRunServiceComposite = Composite((props: CloudRunServiceProps)
     maxInstanceCount = 100,
     publicAccess = false,
     env,
+    serviceAccount,
     labels: extraLabels = {},
     namespace,
     defaults: defs,
@@ -112,6 +115,9 @@ export const CloudRunServiceComposite = Composite((props: CloudRunServiceProps)
         maxInstanceCount,
       },
       containers,
+      ...(serviceAccount && {
+        serviceAccountRef: serviceAccount.includes("@") ? { external: serviceAccount } : { name: serviceAccount },
+      }),
     },
   }, defs?.service));
 

package/src/composites/composites.test.ts

@@ -83,6 +83,13 @@ describe("CloudRunServiceComposite", () => {
     expect(result.service).toBeDefined();
   });
 
+  test("serviceAccount sets serviceAccountRef: an account id by name, an email as external (#4240)", () => {
+    const byName = CloudRunServiceComposite({ name: "api", image: "i", serviceAccount: "run-sa" });
+    expect((p(byName.service).template as Record<string, unknown>).serviceAccountRef).toEqual({ name: "run-sa" });
+    const byEmail = CloudRunServiceComposite({ name: "api", image: "i", serviceAccount: "x@o.iam.gserviceaccount.com" });
+    expect((p(byEmail.service).template as Record<string, unknown>).serviceAccountRef).toEqual({ external: "x@o.iam.gserviceaccount.com" });
+  });
+
   test("sets projectRef and location, which the RunService CRD requires", () => {
     const result = CloudRunServiceComposite({
       name: "api",

package/src/deep-observe.test.ts

@@ -124,6 +124,21 @@ describe("toCnrmTree — each REST shape in the declared vocabulary (#1210)", ()
     expect(tree).toEqual({ metadata: { name: "t" }, messageRetentionDuration: "86400s" });
   });
 
+  test("run service: the v2 serviceAccount email maps back to the declared serviceAccountRef (#4240)", () => {
+    const same = toCnrmTree(
+      "RunService",
+      { name: "projects/my-project/locations/us-central1/services/web", template: { serviceAccount: "run-sa@my-project.iam.gserviceaccount.com" } },
+      ctx,
+    ) as { template: Record<string, unknown> };
+    expect(same.template).toEqual({ serviceAccountRef: { name: "run-sa" } });
+    const other = toCnrmTree(
+      "RunService",
+      { name: "projects/my-project/locations/us-central1/services/web", template: { serviceAccount: "x@other.iam.gserviceaccount.com" } },
+      ctx,
+    ) as { template: Record<string, unknown> };
+    expect(other.template).toEqual({ serviceAccountRef: { external: "x@other.iam.gserviceaccount.com" } });
+  });
+
   test("bucket: GCS's iamConfiguration and lifecycle map onto the CNRM field names", () => {
     const tree = toCnrmTree(
       "StorageBucket",
@@ -235,7 +250,7 @@ describe("observeResourcesDeepGcp — over REST (#1209)", () => {
   });
 
   test("a kind the applier cannot write is unsupported-kind, and is never queried", async () => {
-    const out = await observe(entities([["e", "GCP::Compute::Address", { metadata: { name: "a" } }]]));
+    const out = await observe(entities([["e", "GCP::Compute::Network", { metadata: { name: "n" } }]]));
     expect(out.unobserved?.e?.reason).toBe("unsupported-kind");
     expect(fetchMock).not.toHaveBeenCalled();
   });