@catladder/cli 0.0.0-main-2355fd7c → 0.0.0-main-018e2dee

package/dist/bundles/cli/index.js

@@ -475,6 +475,18 @@ class GcloudProjectInspector {
             .filter((binding) => { var _a; return (_a = binding.members) === null || _a === void 0 ? void 0 : _a.includes(member); })
             .map((binding) => binding.role);
     }
+    /** roles bound to the member without an iam condition */
+    async getUnconditionalRolesOfMember(projectId, member) {
+        return (await this.getIamBindings(projectId))
+            .filter((b) => { var _a; return !b.condition && ((_a = b.members) === null || _a === void 0 ? void 0 : _a.includes(member)); })
+            .map((b) => b.role);
+    }
+    /** roles bound to the member under an iam condition */
+    async getConditionalRolesOfMember(projectId, member) {
+        return (await this.getIamBindings(projectId))
+            .filter((b) => { var _a; return b.condition && ((_a = b.members) === null || _a === void 0 ? void 0 : _a.includes(member)); })
+            .map((b) => b.role);
+    }
     getEnabledServices(projectId) {
         if (!this.enabledServices.has(projectId)) {
             this.enabledServices.set(projectId, (0, child_process_promise_1.exec)(`gcloud services list --enabled --project=${projectId} --format="value(config.name)"`).then((result) => new Set(result.stdout
@@ -512,6 +524,7 @@ const serviceAccountNames_1 = __nccwpck_require__(67851);
 const serviceAccounts_1 = __nccwpck_require__(18190);
 const concurrency_1 = __nccwpck_require__(59723);
 const setupCloudRun_1 = __nccwpck_require__(92526);
+const checkLocalAccess_1 = __nccwpck_require__(80206);
 const GcloudProjectInspector_1 = __nccwpck_require__(50379);
 const getCloudRunConfig = (context) => {
     var _a;
@@ -531,7 +544,7 @@ const getCloudRunConfig = (context) => {
  * setup ran — deploys keep working and only the review teardown hits
  * the missing `roles/cloudsql.admin` as a 403 in ci.
  */
-const checkCloudRun = async (report, contexts) => {
+const checkCloudRun = async (report, contexts, config) => {
     var _a;
     const cloudRunContexts = contexts.filter((context) => { var _a; return (0, pipeline_1.isOfDeployType)((_a = context.deploy) === null || _a === void 0 ? void 0 : _a.config, "google-cloudrun"); });
     if (cloudRunContexts.length === 0)
@@ -602,6 +615,7 @@ const checkCloudRun = async (report, contexts) => {
             report.ok(`${label}: service account exists with all config-implied roles`);
         }
     }
+    await (0, checkLocalAccess_1.checkLocalAccess)(report, config, cloudRunContexts, inspector);
 };
 exports.checkCloudRun = checkCloudRun;
 //# sourceMappingURL=checkCloudRun.js.map
@@ -1052,6 +1066,111 @@ exports.checkGitlab = checkGitlab;
 
 /***/ }),
 
+/***/ 80206:
+/***/ ((__unused_webpack_module, exports, __nccwpck_require__) => {
+
+"use strict";
+
+Object.defineProperty(exports, "__esModule", ({ value: true }));
+exports.checkLocalAccess = void 0;
+const pipeline_1 = __nccwpck_require__(53695);
+const localAccess_1 = __nccwpck_require__(94216);
+const serviceAccounts_1 = __nccwpck_require__(18190);
+const concurrency_1 = __nccwpck_require__(59723);
+/**
+ * compares the read-only local access service accounts (`localAccess`
+ * in catladder.ts) with their declaration: missing account, missing and
+ * extra bindings, and an account that exists although nothing is
+ * declared any more. Expects an authenticated inspector.
+ */
+const checkLocalAccess = async (report, config, contexts, inspector) => {
+    const results = await (0, concurrency_1.mapWithConcurrency)(contexts, 5, async (context) => {
+        var _a;
+        const deployConfig = (_a = context.deploy) === null || _a === void 0 ? void 0 : _a.config;
+        if (!(0, pipeline_1.isOfDeployType)(deployConfig, "google-cloudrun"))
+            return null;
+        const label = `${context.env}:${context.name}`;
+        let declared;
+        try {
+            declared = (0, pipeline_1.getLocalAccessGcpRoles)(config, context.env);
+            (0, pipeline_1.getLocalAccessGcpCredentialsEnvVars)(config, context.name);
+        }
+        catch (e) {
+            return { label, invalid: e.message };
+        }
+        const { fullIdentifier } = (0, localAccess_1.getLocalAccessServiceAccountNames)(context, deployConfig.projectId);
+        const exists = await (0, serviceAccounts_1.accountExists)(fullIdentifier);
+        const member = `serviceAccount:${fullIdentifier}`;
+        const bound = exists
+            ? await inspector.getUnconditionalRolesOfMember(deployConfig.projectId, member)
+            : [];
+        const conditional = exists
+            ? await inspector.getConditionalRolesOfMember(deployConfig.projectId, member)
+            : [];
+        const keyCount = exists
+            ? (await (0, localAccess_1.listUserManagedKeyIds)(fullIdentifier)).length
+            : 0;
+        return {
+            label,
+            declared,
+            fullIdentifier,
+            exists,
+            bound,
+            conditional,
+            keyCount,
+        };
+    });
+    const relevant = results.filter((r) => r && ("invalid" in r || r.declared.length > 0 || r.exists));
+    if (relevant.length === 0)
+        return;
+    report.section("local access (read-only service accounts)");
+    for (const result of relevant) {
+        if (!result)
+            continue;
+        if ("invalid" in result) {
+            report.fail(`${result.label}: ${result.invalid}`);
+            continue;
+        }
+        const { label, declared, fullIdentifier, exists, bound, conditional, keyCount, } = result;
+        if (declared.length > 0 && (0, pipeline_1.getVaultConfig)(config).type === "gitlab") {
+            report.fail(`${label}: localAccess needs a vault that is not a CI variable store (the gitlab vault would expose the key to every CI job)`);
+            continue;
+        }
+        const heal = `run: catladder project setup`;
+        if (declared.length === 0) {
+            report.warn(`${label}: ${fullIdentifier} exists although no local access is declared`, heal);
+        }
+        else if (!exists) {
+            report.fail(`${label}: ${fullIdentifier} does not exist`, heal);
+        }
+        else {
+            const { missing, extra } = (0, pipeline_1.diffRoleBindings)(declared, bound);
+            if (missing.length > 0) {
+                report.fail(`${label}: local access account is missing roles: ${missing.join(", ")}`, heal);
+            }
+            if (extra.length > 0) {
+                report.fail(`${label}: local access account has undeclared roles: ${extra.join(", ")}`, heal);
+            }
+            if (conditional.length > 0) {
+                report.fail(`${label}: local access account has conditional roles (${conditional.join(", ")}) that setup does not remove`, "remove them by hand");
+            }
+            if (keyCount !== 1) {
+                report.fail(`${label}: local access account has ${keyCount} user-managed keys, expected exactly 1`, heal);
+            }
+            if (missing.length === 0 &&
+                extra.length === 0 &&
+                conditional.length === 0 &&
+                keyCount === 1) {
+                report.ok(`${label}: local access account has exactly the declared roles`);
+            }
+        }
+    }
+};
+exports.checkLocalAccess = checkLocalAccess;
+//# sourceMappingURL=checkLocalAccess.js.map
+
+/***/ }),
+
 /***/ 62878:
 /***/ ((__unused_webpack_module, exports, __nccwpck_require__) => {
 
@@ -1145,7 +1264,7 @@ const doctorProject = async (instance, onlyComponents) => {
     if ((0, pipeline_1.getEnabledPipelineTypes)(config).includes("gitlab")) {
         await (0, checkGitlab_1.checkGitlab)(instance, report, contexts);
     }
-    await (0, checkCloudRun_1.checkCloudRun)(report, contexts);
+    await (0, checkCloudRun_1.checkCloudRun)(report, contexts, config);
     await (0, checkGithubImageCasing_1.checkGithubImageCasing)(report, config);
     await (0, checkGithubReleaseWorkflow_1.checkGithubReleaseWorkflow)(report, config);
     await (0, checkGithub_1.checkGithub)(report, config);
@@ -1704,6 +1823,7 @@ Object.defineProperty(exports, "__esModule", ({ value: true }));
 exports.setupContext = void 0;
 const pipeline_1 = __nccwpck_require__(53695);
 const setupCloudRun_1 = __nccwpck_require__(92526);
+const setupLocalAccess_1 = __nccwpck_require__(3299);
 const setupKubernetes_1 = __nccwpck_require__(51796);
 const logSection_1 = __nccwpck_require__(74120);
 const setupContext = async (instance, context) => {
@@ -1711,6 +1831,7 @@ const setupContext = async (instance, context) => {
         var _a, _b;
         if ((0, pipeline_1.isOfDeployType)((_a = context.deploy) === null || _a === void 0 ? void 0 : _a.config, "google-cloudrun")) {
             await (0, setupCloudRun_1.setupCloudRun)(instance, context);
+            await (0, setupLocalAccess_1.setupLocalAccess)(instance, context);
         }
         const deployConfig = (_b = context.deploy) === null || _b === void 0 ? void 0 : _b.config;
         if ((0, pipeline_1.isOfDeployType)(deployConfig, "kubernetes")) {
@@ -2067,6 +2188,44 @@ exports.setupKubernetes = setupKubernetes;
 
 /***/ }),
 
+/***/ 3299:
+/***/ ((__unused_webpack_module, exports, __nccwpck_require__) => {
+
+"use strict";
+
+Object.defineProperty(exports, "__esModule", ({ value: true }));
+exports.setupLocalAccess = void 0;
+const pipeline_1 = __nccwpck_require__(53695);
+const getProjectConfig_1 = __nccwpck_require__(70478);
+const localAccess_1 = __nccwpck_require__(94216);
+/**
+ * provisions the local access (`localAccess` in catladder.ts)
+ * of a google cloud run component/env: a dedicated service account with
+ * exactly the declared bindings and its key in the secret store. Also
+ * removes what is no longer declared.
+ */
+const setupLocalAccess = async (instance, context) => {
+    var _a;
+    const config = (_a = context.deploy) === null || _a === void 0 ? void 0 : _a.config;
+    if (!(0, pipeline_1.isOfDeployType)(config, "google-cloudrun"))
+        return;
+    const projectConfig = await (0, getProjectConfig_1.getProjectConfig)();
+    const roles = (0, pipeline_1.getLocalAccessGcpRoles)(projectConfig, context.env);
+    // validates `credentialsEnvVar` (catenv silently skips invalid ones)
+    (0, pipeline_1.getLocalAccessGcpCredentialsEnvVars)(projectConfig, context.name);
+    if (roles.length > 0 && (0, pipeline_1.getVaultConfig)(projectConfig).type === "gitlab") {
+        // the gitlab vault stores secrets as CI variables available to every
+        // job on every branch: the key would leak to anyone who can push
+        throw new Error(`localAccess (${context.env}:${context.name}) needs a vault that is not a CI variable store (e.g. bitwarden): the gitlab vault would expose the service account key to every CI job. Configure \`vault\` or remove the localAccess declaration.`);
+    }
+    instance.log("sync local access service account...");
+    await (0, localAccess_1.syncLocalAccessServiceAccount)(instance, context, config.projectId, roles);
+};
+exports.setupLocalAccess = setupLocalAccess;
+//# sourceMappingURL=setupLocalAccess.js.map
+
+/***/ }),
+
 /***/ 63361:
 /***/ ((__unused_webpack_module, exports, __nccwpck_require__) => {
 
@@ -5790,6 +5949,7 @@ exports.uninstallCompletions = uninstallCompletions;
 Object.defineProperty(exports, "__esModule", ({ value: true }));
 exports.getJobOnlyEnvVarsResolved = exports.getEnvVarsResolved = exports.getGitlabVar = exports.getEnvironment = exports.getAllPipelineContexts = exports.getAllComponentsWithAllEnvsHierarchical = exports.getAllComponentsWithAllEnvsFlat = exports.getPipelineContextByChoice = exports.getProjectComponents = exports.invalidateProjectConfig = exports.getProjectConfig = exports.parseChoice = void 0;
 const pipeline_1 = __nccwpck_require__(53695);
+const keyFiles_1 = __nccwpck_require__(70180);
 const gitlab_1 = __nccwpck_require__(17697);
 const projects_1 = __nccwpck_require__(20575);
 var parseChoice_1 = __nccwpck_require__(70769);
@@ -5910,12 +6070,19 @@ const getEnvVarsResolved = async (io, env, componentName) => {
     const envionment = await (0, exports.getEnvironment)(env, componentName);
     // in the pipeline the secrets alreadyy exists  and bash will expand them
     // but here we need to manually load them
-    return resolveSecrets(io, [
+    const resolved = await resolveSecrets(io, [
         {
             envVars: envionment.envVars,
             secretEnvVarKeys: envionment.secretEnvVarKeys,
         },
     ]);
+    if (env !== "local")
+        return resolved;
+    // paths of the local access key files (written by catenv)
+    return {
+        ...resolved,
+        ...(await (0, keyFiles_1.getLocalAccessKeyFileVars)(await (0, exports.getProjectConfig)(), componentName)),
+    };
 };
 exports.getEnvVarsResolved = getEnvVarsResolved;
 /**
@@ -6230,6 +6397,189 @@ exports.fetchGcloudProjectNumber = fetchGcloudProjectNumber;
 
 /***/ }),
 
+/***/ 94216:
+/***/ ((__unused_webpack_module, exports, __nccwpck_require__) => {
+
+"use strict";
+
+Object.defineProperty(exports, "__esModule", ({ value: true }));
+exports.syncLocalAccessServiceAccount = exports.listUserManagedKeyIds = exports.parseServiceAccountKey = exports.getConditionalRolesOfMemberInBindings = exports.getRolesOfMemberInBindings = exports.getLocalAccessServiceAccountNames = void 0;
+const pipeline_1 = __nccwpck_require__(53695);
+const child_process_promise_1 = __nccwpck_require__(11542);
+const promises_1 = __nccwpck_require__(91943);
+const os_1 = __nccwpck_require__(70857);
+const path_1 = __nccwpck_require__(16928);
+const serviceAccountNames_1 = __nccwpck_require__(67851);
+const serviceAccounts_1 = __nccwpck_require__(18190);
+/**
+ * the dedicated read-only service account of a component/env that
+ * `project setup` provisions from the `localAccess` declaration.
+ * Shared with `project doctor` and catenv.
+ */
+const getLocalAccessServiceAccountNames = (context, projectId) => (0, serviceAccountNames_1.getGcloudServiceAccountNames)(context, {
+    name: pipeline_1.LOCAL_ACCESS_GCP_SA_NAME,
+    projectId,
+});
+exports.getLocalAccessServiceAccountNames = getLocalAccessServiceAccountNames;
+/**
+ * all unconditional roles bound to `member` in the given iam policy
+ * bindings. Conditional bindings are reported separately, see
+ * {@link getConditionalRolesOfMemberInBindings}.
+ */
+const getRolesOfMemberInBindings = (bindings, member) => bindings
+    .filter((binding) => !binding.condition)
+    .filter((binding) => { var _a; return (_a = binding.members) === null || _a === void 0 ? void 0 : _a.includes(member); })
+    .map((binding) => binding.role)
+    .sort();
+exports.getRolesOfMemberInBindings = getRolesOfMemberInBindings;
+/**
+ * roles bound to `member` under an iam condition. These cannot be
+ * removed by role name alone, so they are never touched by `project
+ * setup` — only reported.
+ */
+const getConditionalRolesOfMemberInBindings = (bindings, member) => bindings
+    .filter((binding) => binding.condition)
+    .filter((binding) => { var _a; return (_a = binding.members) === null || _a === void 0 ? void 0 : _a.includes(member); })
+    .map((binding) => binding.role)
+    .sort();
+exports.getConditionalRolesOfMemberInBindings = getConditionalRolesOfMemberInBindings;
+/**
+ * parses the output of `gcloud iam service-accounts keys create` and
+ * makes sure it is a usable service account key
+ */
+const parseServiceAccountKey = (raw) => {
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch (_a) {
+        throw new Error("gcloud did not return a valid service account key");
+    }
+    if (typeof parsed.private_key_id !== "string" ||
+        typeof parsed.private_key !== "string") {
+        throw new Error("gcloud did not return a valid service account key");
+    }
+    return { key: raw, privateKeyId: parsed.private_key_id };
+};
+exports.parseServiceAccountKey = parseServiceAccountKey;
+const getProjectBindings = async (projectId) => {
+    var _a;
+    return (_a = JSON.parse((await (0, child_process_promise_1.exec)(`gcloud projects get-iam-policy ${projectId} --format=json`))
+        .stdout).bindings) !== null && _a !== void 0 ? _a : [];
+};
+const listUserManagedKeyIds = async (fullIdentifier) => {
+    const keys = JSON.parse((await (0, child_process_promise_1.exec)(`gcloud iam service-accounts keys list --iam-account=${fullIdentifier} --managed-by=user --format=json`)).stdout);
+    return keys.map((key) => key.name.split("/").pop());
+};
+exports.listUserManagedKeyIds = listUserManagedKeyIds;
+/**
+ * makes the account's bindings equal to `roles`: adds missing, removes
+ * everything else (the account is dedicated, every other binding is
+ * drift). Idempotent — a no-op when nothing differs.
+ */
+const syncBindings = async (io, projectId, fullIdentifier, roles) => {
+    const member = `serviceAccount:${fullIdentifier}`;
+    const bindings = await getProjectBindings(projectId);
+    const conditional = (0, exports.getConditionalRolesOfMemberInBindings)(bindings, member);
+    if (conditional.length > 0) {
+        io.log(`⚠️ ${fullIdentifier} has conditional bindings (${conditional.join(", ")}) — setup does not touch them, remove them by hand`);
+    }
+    const { missing, extra } = (0, pipeline_1.diffRoleBindings)(roles, (0, exports.getRolesOfMemberInBindings)(bindings, member));
+    for (const role of missing) {
+        io.log(`  + ${role}`);
+        await (0, child_process_promise_1.exec)(`gcloud projects add-iam-policy-binding ${projectId} --member=${member} --role=${role} --condition=None`);
+    }
+    for (const role of extra) {
+        io.log(`  - ${role}`);
+        await (0, child_process_promise_1.exec)(`gcloud projects remove-iam-policy-binding ${projectId} --member=${member} --role=${role} --condition=None`);
+    }
+};
+/**
+ * brings the local access service account of a component/env in line
+ * with the declared `roles`:
+ *
+ * - roles declared: account exists, carries exactly these bindings,
+ *   and a key for it is in the secret store (under the `local` env, so
+ *   it is never mirrored to ci). The key is only created when the
+ *   stored one is missing or no longer valid — re-running is a no-op.
+ * - no roles declared: bindings are removed and the account (with its
+ *   keys) deleted if it exists.
+ */
+const syncLocalAccessServiceAccount = async (io, context, projectId, roles) => {
+    const { fullName, fullIdentifier } = (0, exports.getLocalAccessServiceAccountNames)(context, projectId);
+    const exists = await (0, serviceAccounts_1.accountExists)(fullIdentifier);
+    if (roles.length === 0) {
+        if (exists) {
+            io.log(`local access no longer declared, removing ${fullIdentifier}...`);
+            await syncBindings(io, projectId, fullIdentifier, []);
+            await (0, child_process_promise_1.exec)(`gcloud iam service-accounts delete ${fullIdentifier} --quiet --project="${projectId}"`);
+        }
+        return;
+    }
+    if (!exists) {
+        io.log(`creating local access service account ${fullIdentifier}...`);
+        await (0, child_process_promise_1.exec)(`gcloud iam service-accounts create ${fullName} --display-name="${context.fullConfig.customerName}-${context.fullConfig.appName} ${context.env}:${context.name} | Catladder local access (read-only)" --project="${projectId}" --description="Read-only access for local use (agents, scripts)"`);
+    }
+    await syncBindings(io, projectId, fullIdentifier, roles);
+    const secretName = (0, pipeline_1.getLocalAccessGcpSecretName)(context.env);
+    const vaultManager = await io.getVaultManager();
+    const rawName = (0, pipeline_1.getSecretVarName)("local", context.name, secretName);
+    // straight from the vault, NOT through the local cache: a stale cache
+    // (older than the first setup, or holding an older key) would make us
+    // believe the key is gone, delete the valid one and lock out every
+    // other machine.
+    const stored = (await vaultManager.vault.readAllSecrets(io))[rawName];
+    const validKeyIds = await (0, exports.listUserManagedKeyIds)(fullIdentifier);
+    let storedKeyId;
+    try {
+        storedKeyId = JSON.parse(stored).private_key_id;
+    }
+    catch (_a) {
+        // no (or unparsable) stored key
+    }
+    if (storedKeyId && validKeyIds.includes(storedKeyId)) {
+        // keep the cache in line with the vault
+        await vaultManager.cacheSecrets("local", context.name, {
+            [secretName]: stored,
+        });
+        // at most one key per account: also drop leftovers of a failed run
+        // or keys added by hand
+        await deleteKeys(fullIdentifier, validKeyIds.filter((id) => id !== storedKeyId));
+        return;
+    }
+    io.log("creating local access key...");
+    // create first: a failed create must not leave the vault empty
+    const { key, privateKeyId } = await createServiceAccountKey(fullIdentifier);
+    // straight into the vault, NOT through writeSecretsAndMirror: this
+    // key is for local use only and must never reach ci variables.
+    // A fresh key replaces the old one, a backup would be dead.
+    await vaultManager.writeSecrets("local", context.name, { [secretName]: key }, io, { backup: false });
+    // only now drop the keys that are not the new one
+    await deleteKeys(fullIdentifier, validKeyIds.filter((id) => id !== privateKeyId));
+};
+exports.syncLocalAccessServiceAccount = syncLocalAccessServiceAccount;
+const deleteKeys = async (fullIdentifier, keyIds) => {
+    for (const keyId of keyIds) {
+        await (0, child_process_promise_1.exec)(`gcloud iam service-accounts keys delete ${keyId} --quiet --iam-account=${fullIdentifier}`);
+    }
+};
+const createServiceAccountKey = async (fullIdentifier) => {
+    // a private temp file (0700 folder) instead of /dev/stdout | cat:
+    // the pipe hid gcloud's exit code
+    const folder = await (0, promises_1.mkdtemp)((0, path_1.join)((0, os_1.tmpdir)(), "catladder-local-access-"));
+    try {
+        const file = (0, path_1.join)(folder, "key.json");
+        await (0, child_process_promise_1.exec)(`gcloud iam service-accounts keys create "${file}" --iam-account=${fullIdentifier}`);
+        return (0, exports.parseServiceAccountKey)(await (0, promises_1.readFile)(file, "utf-8"));
+    }
+    finally {
+        await (0, promises_1.rm)(folder, { recursive: true, force: true });
+    }
+};
+//# sourceMappingURL=localAccess.js.map
+
+/***/ }),
+
 /***/ 74241:
 /***/ (function(__unused_webpack_module, exports, __nccwpck_require__) {
 
@@ -6319,12 +6669,19 @@ const child_process_promise_1 = __nccwpck_require__(11542);
 const secrets_1 = __nccwpck_require__(85200);
 const serviceAccountNames_1 = __nccwpck_require__(67851);
 const accountExists = async (fullIdentifier) => {
+    var _a, _b;
     try {
         await (0, child_process_promise_1.exec)(`gcloud iam service-accounts describe ${fullIdentifier}`);
         return true;
     }
-    catch (_a) {
-        return false;
+    catch (e) {
+        // only a missing account means "does not exist": an auth or
+        // permission error must not look like one (setup would skip the
+        // deletion, doctor would report it missing)
+        if (`${(_a = e === null || e === void 0 ? void 0 : e.stderr) !== null && _a !== void 0 ? _a : ""}${(_b = e === null || e === void 0 ? void 0 : e.message) !== null && _b !== void 0 ? _b : ""}`.includes("NOT_FOUND")) {
+            return false;
+        }
+        throw e;
     }
 };
 exports.accountExists = accountExists;
@@ -6622,6 +6979,145 @@ exports.startKubePortForward = startKubePortForward;
 
 /***/ }),
 
+/***/ 83228:
+/***/ ((__unused_webpack_module, exports, __nccwpck_require__) => {
+
+"use strict";
+
+Object.defineProperty(exports, "__esModule", ({ value: true }));
+exports.getDeclaredLocalAccessCredentialsEnvVars = exports.getDeclaredLocalAccessEnvs = void 0;
+const pipeline_1 = __nccwpck_require__(53695);
+/**
+ * the envs of a component declaring gcp local access. An invalid
+ * declaration yields none instead of throwing: catenv and the vault
+ * cache must keep working (`project doctor` and `project setup` report
+ * the invalid declaration loudly).
+ */
+const getDeclaredLocalAccessEnvs = (config, componentName) => {
+    try {
+        return (0, pipeline_1.getLocalAccessGcpEnvs)(config, componentName);
+    }
+    catch (_a) {
+        return [];
+    }
+};
+exports.getDeclaredLocalAccessEnvs = getDeclaredLocalAccessEnvs;
+/**
+ * the declared `credentialsEnvVar` names of a component, mapped to their
+ * env. Empty instead of throwing on an invalid declaration, see
+ * {@link getDeclaredLocalAccessEnvs}.
+ */
+const getDeclaredLocalAccessCredentialsEnvVars = (config, componentName) => {
+    try {
+        return (0, pipeline_1.getLocalAccessGcpCredentialsEnvVars)(config, componentName);
+    }
+    catch (_a) {
+        return {};
+    }
+};
+exports.getDeclaredLocalAccessCredentialsEnvVars = getDeclaredLocalAccessCredentialsEnvVars;
+//# sourceMappingURL=declared.js.map
+
+/***/ }),
+
+/***/ 70180:
+/***/ ((__unused_webpack_module, exports, __nccwpck_require__) => {
+
+"use strict";
+
+Object.defineProperty(exports, "__esModule", ({ value: true }));
+exports.writeLocalAccessKeyFiles = exports.getLocalAccessKeyFileVars = exports.getLocalAccessKeyFileVarName = exports.getLocalAccessKeyFileName = void 0;
+const pipeline_1 = __nccwpck_require__(53695);
+const promises_1 = __nccwpck_require__(91943);
+const fs_1 = __nccwpck_require__(79896);
+const path_1 = __nccwpck_require__(16928);
+const writePrivateFile_1 = __nccwpck_require__(14550);
+const declared_1 = __nccwpck_require__(83228);
+const gitProjectInformation_1 = __nccwpck_require__(86884);
+const sanitize = (s) => s.replace(/[^A-Za-z0-9]+/g, "_");
+/** file name of a component/env key, relative to the local access folder */
+const getLocalAccessKeyFileName = (env, componentName) => `gcp-${sanitize(env)}-${sanitize(componentName)}.json`;
+exports.getLocalAccessKeyFileName = getLocalAccessKeyFileName;
+/**
+ * env var exposing the key file path. Deliberately NOT
+ * GOOGLE_APPLICATION_CREDENTIALS: the key must only be used where a
+ * command opts in (isolated gcloud config, or a declared
+ * `credentialsEnvVar`), never by ADC implicitly.
+ */
+const getLocalAccessKeyFileVarName = (env) => `CATLADDER_LOCAL_ACCESS_GCP_${sanitize(env).toUpperCase()}_KEY_FILE`;
+exports.getLocalAccessKeyFileVarName = getLocalAccessKeyFileVarName;
+// inside .catladder/, which ignores itself (see vault/cache.ts)
+const getFolder = async () => (0, path_1.join)(await (0, gitProjectInformation_1.getProjectRootPath)(), ".catladder", "local-access");
+/**
+ * env vars pointing at the key files that exist for the component
+ * (only paths, no secrets): one per env, plus the declared
+ * `credentialsEnvVar` names
+ */
+const getLocalAccessKeyFileVars = async (config, componentName) => {
+    const folder = await getFolder();
+    const getPath = (env) => (0, path_1.join)(folder, (0, exports.getLocalAccessKeyFileName)(env, componentName));
+    return Object.fromEntries([
+        ...(0, declared_1.getDeclaredLocalAccessEnvs)(config, componentName).map((env) => [
+            (0, exports.getLocalAccessKeyFileVarName)(env),
+            getPath(env),
+        ]),
+        ...Object.entries((0, declared_1.getDeclaredLocalAccessCredentialsEnvVars)(config, componentName)).map(([name, env]) => [name, getPath(env)]),
+    ].filter(([, path]) => (0, fs_1.existsSync)(path)));
+};
+exports.getLocalAccessKeyFileVars = getLocalAccessKeyFileVars;
+/**
+ * writes the stored local access service account keys to gitignored
+ * files (mode 0600) and removes files of declarations that are gone.
+ * A no-op without any declaration (nothing is created). Never throws:
+ * a vault that cannot be reached or an invalid declaration (reported by
+ * `project doctor`) must not break catenv.
+ *
+ * The key is only read through the cache; if setup rotated it on another
+ * machine, refresh with `catenv --vault-mode refresh`.
+ */
+const writeLocalAccessKeyFiles = async (io, config) => {
+    const wanted = Object.keys(config.components).flatMap((componentName) => (0, declared_1.getDeclaredLocalAccessEnvs)(config, componentName).map((env) => ({
+        env,
+        componentName,
+        secretName: (0, pipeline_1.getSecretVarName)("local", componentName, (0, pipeline_1.getLocalAccessGcpSecretName)(env)),
+        fileName: (0, exports.getLocalAccessKeyFileName)(env, componentName),
+    })));
+    const folder = await getFolder();
+    if (wanted.length === 0 && !(0, fs_1.existsSync)(folder))
+        return;
+    try {
+        const secrets = wanted.length > 0
+            ? await (await io.getVaultManager()).readSecrets(wanted.map((w) => w.secretName), io)
+            : {};
+        await (0, promises_1.mkdir)(folder, { recursive: true, mode: 0o700 });
+        // the parent folder ignores itself
+        await (0, promises_1.writeFile)((0, path_1.join)(folder, "..", ".gitignore"), "*\n");
+        const written = new Set();
+        for (const { secretName, fileName, env, componentName } of wanted) {
+            const key = secrets[secretName];
+            if (!key) {
+                io.log(`⚠️ no local access key for ${env}:${componentName} in the secret store — run \`catladder project setup\` (or \`catenv --vault-mode refresh\` if it was set up on another machine)`);
+                continue;
+            }
+            const path = (0, path_1.join)(folder, fileName);
+            await (0, writePrivateFile_1.writePrivateFile)(path, key);
+            written.add(fileName);
+        }
+        for (const file of await (0, promises_1.readdir)(folder)) {
+            if (!written.has(file)) {
+                await (0, promises_1.rm)((0, path_1.join)(folder, file), { force: true });
+            }
+        }
+    }
+    catch (e) {
+        io.log(`⚠️ could not write local access keys: ${e.message}`);
+    }
+};
+exports.writeLocalAccessKeyFiles = writeLocalAccessKeyFiles;
+//# sourceMappingURL=keyFiles.js.map
+
+/***/ }),
+
 /***/ 55689:
 /***/ ((__unused_webpack_module, exports) => {
 
@@ -8034,6 +8530,38 @@ exports.getShell = getShell;
 
 /***/ }),
 
+/***/ 14550:
+/***/ ((__unused_webpack_module, exports, __nccwpck_require__) => {
+
+"use strict";
+
+Object.defineProperty(exports, "__esModule", ({ value: true }));
+exports.writePrivateFile = void 0;
+const promises_1 = __nccwpck_require__(91943);
+/**
+ * writes a file readable by the owner only. Goes through a 0600 temp
+ * file and a rename, so the content is never visible with looser
+ * permissions (writing first and chmod-ing afterwards would leave an
+ * existing 0644 file readable until the chmod).
+ */
+const writePrivateFile = async (path, content) => {
+    const tmp = `${path}.${process.pid}.tmp`;
+    try {
+        await (0, promises_1.writeFile)(tmp, content, { mode: 0o600 });
+        // the mode is only applied when the file is created
+        await (0, promises_1.chmod)(tmp, 0o600);
+        await (0, promises_1.rename)(tmp, path);
+    }
+    catch (e) {
+        await (0, promises_1.rm)(tmp, { force: true });
+        throw e;
+    }
+};
+exports.writePrivateFile = writePrivateFile;
+//# sourceMappingURL=writePrivateFile.js.map
+
+/***/ }),
+
 /***/ 42827:
 /***/ ((__unused_webpack_module, exports, __nccwpck_require__) => {
 
@@ -8140,30 +8668,21 @@ class BitwardenVault {
             : {};
         const notes = (0, yaml_1.stringify)({ ...previous, ...secrets });
         if (existing) {
-            await (0, bw_1.runBw)(bwSession, [
-                "edit",
-                "item",
-                existing.id,
-                encodePayload({ ...existing, notes }),
-            ]);
+            await (0, bw_1.runBw)(bwSession, ["edit", "item", existing.id], encodePayload({ ...existing, notes }));
         }
         else {
-            await (0, bw_1.runBw)(bwSession, [
-                "create",
-                "item",
-                encodePayload({
-                    type: SECURE_NOTE_TYPE,
-                    secureNote: { type: 0 },
-                    name,
-                    notes,
-                    ...(collection.organizationId
-                        ? {
-                            organizationId: collection.organizationId,
-                            collectionIds: [collection.id],
-                        }
-                        : {}),
-                }),
-            ]);
+            await (0, bw_1.runBw)(bwSession, ["create", "item"], encodePayload({
+                type: SECURE_NOTE_TYPE,
+                secureNote: { type: 0 },
+                name,
+                notes,
+                ...(collection.organizationId
+                    ? {
+                        organizationId: collection.organizationId,
+                        collectionIds: [collection.id],
+                    }
+                    : {}),
+            }));
         }
     }
 }
@@ -8210,6 +8729,7 @@ exports.GitlabVault = GitlabVault;
 Object.defineProperty(exports, "__esModule", ({ value: true }));
 exports.VaultManager = void 0;
 const pipeline_1 = __nccwpck_require__(53695);
+const declared_1 = __nccwpck_require__(83228);
 const BitwardenVault_1 = __nccwpck_require__(42827);
 const cache_1 = __nccwpck_require__(57011);
 const GitlabVault_1 = __nccwpck_require__(6020);
@@ -8292,6 +8812,15 @@ class VaultManager {
             ])));
         }
     }
+    /**
+     * updates the local cache only (the vault already holds the values),
+     * "local" env only
+     */
+    async cacheSecrets(env, componentName, secrets) {
+        if (env !== CACHED_ENV)
+            return;
+        await (0, cache_1.updateSecretsCache)(this.vault.id, env, componentName, secrets);
+    }
     /**
      * the subset of the vault secrets that may be cached: the declared
      * secrets of the "local" env, per component, as a hierarchy
@@ -8315,6 +8844,14 @@ class VaultManager {
         return Object.keys(local).length > 0 ? { [CACHED_ENV]: local } : {};
     }
     async declaredSecretKeys(componentName) {
+        return [
+            ...(await this.declaredEnvSecretKeys(componentName)),
+            // the local access keys `project setup` provisions are not part
+            // of any env's vars, but belong to the cached local secrets
+            ...(0, declared_1.getDeclaredLocalAccessEnvs)(this.config, componentName).map(pipeline_1.getLocalAccessGcpSecretName),
+        ];
+    }
+    async declaredEnvSecretKeys(componentName) {
         try {
             const { secretEnvVarKeys, jobOnlyVars } = await (0, pipeline_1.getEnvironment)({
                 config: this.config,
@@ -8424,14 +8961,40 @@ const getBwSession = async (io, { allowPrompt }) => {
 };
 exports.getBwSession = getBwSession;
 /**
- * runs a bw command with the given session and returns stdout
+ * runs a bw command with the given session and returns stdout.
+ *
+ * `input` is written to stdin: use it for payloads (e.g. the secrets of
+ * `bw create item`), which would otherwise be visible in `ps` and be
+ * echoed by node's "Command failed" error.
  */
-const runBw = async (session, args) => {
-    const { stdout } = await execFile("bw", [...args, "--raw", "--nointeraction"], {
-        env: { ...process.env, BW_SESSION: session },
-        maxBuffer: 50 * 1024 * 1024,
+const runBw = async (session, args, input) => {
+    const fullArgs = [...args, "--raw", "--nointeraction"];
+    const env = { ...process.env, BW_SESSION: session };
+    if (input === undefined) {
+        const { stdout } = await execFile("bw", fullArgs, {
+            env,
+            maxBuffer: 50 * 1024 * 1024,
+        });
+        return stdout;
+    }
+    return new Promise((resolve, reject) => {
+        const child = (0, child_process_1.spawn)("bw", fullArgs, {
+            env,
+            stdio: ["pipe", "pipe", "pipe"],
+        });
+        let stdout = "";
+        let stderr = "";
+        child.stdout.on("data", (data) => (stdout += data.toString("utf-8")));
+        child.stderr.on("data", (data) => (stderr += data.toString("utf-8")));
+        child.on("error", reject);
+        child.on("close", (code) => code === 0
+            ? resolve(stdout)
+            : reject(new Error(`bw ${args[0]} failed: ${stderr.trim()}`)));
+        child.stdin.on("error", () => {
+            // bw exiting early closes the pipe, the close handler reports why
+        });
+        child.stdin.end(input);
     });
-    return stdout;
 };
 exports.runBw = runBw;
 const runBwJson = async (session, args) => JSON.parse(await (0, exports.runBw)(session, args));
@@ -8449,6 +9012,7 @@ Object.defineProperty(exports, "__esModule", ({ value: true }));
 exports.updateSecretsCache = exports.writeSecretsCache = exports.readSecretsCache = void 0;
 const promises_1 = __nccwpck_require__(91943);
 const path_1 = __nccwpck_require__(16928);
+const writePrivateFile_1 = __nccwpck_require__(14550);
 const gitProjectInformation_1 = __nccwpck_require__(86884);
 const getCacheFolder = async () => (0, path_1.join)(await (0, gitProjectInformation_1.getProjectRootPath)(), ".catladder");
 const getCachePath = async () => (0, path_1.join)(await getCacheFolder(), "secrets.json");
@@ -8463,7 +9027,7 @@ const readSecretsCache = async () => {
 exports.readSecretsCache = readSecretsCache;
 const writeSecretsCache = async (vaultId, secrets) => {
     const folder = await getCacheFolder();
-    await (0, promises_1.mkdir)(folder, { recursive: true });
+    await (0, promises_1.mkdir)(folder, { recursive: true, mode: 0o700 });
     // the folder ignores itself, so the cache can never be committed
     await (0, promises_1.writeFile)((0, path_1.join)(folder, ".gitignore"), "*\n");
     const cache = {
@@ -8471,7 +9035,9 @@ const writeSecretsCache = async (vaultId, secrets) => {
         updatedAt: new Date().toISOString(),
         secrets,
     };
-    await (0, promises_1.writeFile)(await getCachePath(), JSON.stringify(cache, null, 2));
+    const path = await getCachePath();
+    // may hold key material (local access keys): owner only
+    await (0, writePrivateFile_1.writePrivateFile)(path, JSON.stringify(cache, null, 2));
 };
 exports.writeSecretsCache = writeSecretsCache;
 /**
@@ -19364,6 +19930,191 @@ __exportStar(__nccwpck_require__(91804), exports);
 __exportStar(__nccwpck_require__(94143), exports);
 __exportStar(__nccwpck_require__(98011), exports);
 __exportStar(__nccwpck_require__(61459), exports);
+__exportStar(__nccwpck_require__(54165), exports);
+//# sourceMappingURL=index.js.map
+
+/***/ }),
+
+/***/ 54165:
+/***/ ((__unused_webpack_module, exports, __nccwpck_require__) => {
+
+"use strict";
+
+Object.defineProperty(exports, "__esModule", ({ value: true }));
+exports.getLocalAccessGcpCredentialsEnvVars = exports.diffRoleBindings = exports.getLocalAccessGcpSecretName = exports.getLocalAccessGcpEnvs = exports.getLocalAccessGcpRoles = exports.getLocalAccessConfig = exports.getDeniedLocalAccessRoleReason = exports.LOCAL_ACCESS_GCP_SA_NAME = exports.LOCAL_ACCESS_GCP_PRESETS = void 0;
+const configruedEnvs_1 = __nccwpck_require__(38866);
+const getEnvConfig_1 = __nccwpck_require__(69578);
+const types_1 = __nccwpck_require__(79689);
+exports.LOCAL_ACCESS_GCP_PRESETS = {
+    // no run.viewer on purpose, see LocalAccessGcpPreset
+    logs: ["roles/logging.viewer"],
+    // not read-only, see LocalAccessGcpPreset; only reachable as a
+    // preset, getDeniedLocalAccessRoleReason rejects it in `roles`
+    vertex: ["roles/aiplatform.user"],
+};
+/** name prefix of the service account `project setup` creates (see getGcloudServiceAccountNames) */
+exports.LOCAL_ACCESS_GCP_SA_NAME = "local-diag";
+const ROLE_FORMAT = /^(roles\/[A-Za-z0-9_.]+|projects\/[a-z0-9-]+\/roles\/[A-Za-z0-9_.]+|organizations\/\d+\/roles\/[A-Za-z0-9_.]+)$/;
+/**
+ * roles that are read-only on paper but expose secrets: cloud run
+ * services/jobs carry their secrets as plain env vars, so anything that
+ * may read them reads every deployed secret. Denied even with
+ * `allowAnyRole`.
+ */
+const SECRET_EXPOSING_ROLES = {
+    "roles/viewer": "roles/viewer can read cloud run env vars (secrets)",
+    "roles/run.viewer": "roles/run.viewer can read cloud run env vars (secrets)",
+    "roles/secretmanager.secretAccessor": "this role reads secret values",
+    "roles/secretmanager.admin": "this role reads secret values",
+};
+/**
+ * roles granted without `allowAnyRole`. An explicit list instead of a
+ * name pattern: a role called `*.viewer` / `*.reader` says nothing about
+ * its permissions (custom roles can hold anything, and predefined ones
+ * like storage.objectViewer, cloudfunctions.viewer, compute.viewer or
+ * logging.privateLogViewer expose data or secrets).
+ */
+const SAFE_ROLES = [
+    "roles/logging.viewer",
+    "roles/monitoring.viewer",
+    "roles/errorreporting.viewer",
+];
+/** `roles/foo.bar.v1` -> `foo.bar` (version suffixes must not defeat the checks) */
+const getRoleName = (role) => { var _a; return ((_a = role.split("/").pop()) !== null && _a !== void 0 ? _a : role).replace(/(\.v\d+)+$/i, ""); };
+/**
+ * why a role may not be granted for local access, or undefined if it
+ * is acceptable.
+ *
+ * By default only the roles in {@link SAFE_ROLES} pass; custom roles
+ * and everything else need `allowAnyRole`. `allowAnyRole` lifts the
+ * allow-list, but the obvious write/admin/impersonation roles and the
+ * secret exposing roles stay denied.
+ */
+const getDeniedLocalAccessRoleReason = (role, options = {}) => {
+    var _a;
+    const secretReason = SECRET_EXPOSING_ROLES[role];
+    if (secretReason)
+        return secretReason;
+    const name = getRoleName(role);
+    if (name === "owner" || name === "editor") {
+        return "owner/editor are full write roles";
+    }
+    const last = (_a = name.split(".").pop()) !== null && _a !== void 0 ? _a : name;
+    if (/admin$/i.test(last)) {
+        return "admin roles can change resources";
+    }
+    if (/(editor|developer|writer|creator|deployer|invoker|builder|publisher|client|user|objectUser)$/i.test(last) &&
+        !/^iam\./.test(name)) {
+        return "this role can change resources";
+    }
+    if (/^iam\./.test(name) &&
+        /(serviceAccountUser|serviceAccountTokenCreator|serviceAccountKeyAdmin|workloadIdentityUser)$/.test(name)) {
+        return "this role allows impersonating service accounts";
+    }
+    if (!options.allowAnyRole && !SAFE_ROLES.includes(role)) {
+        return `only these roles are allowed: ${SAFE_ROLES.join(", ")} (set allowAnyRole: true to grant others at your own risk)`;
+    }
+    return undefined;
+};
+exports.getDeniedLocalAccessRoleReason = getDeniedLocalAccessRoleReason;
+/**
+ * the effective local access declaration of an env: the env's own
+ * declaration replaces the project default entirely
+ */
+const getLocalAccessConfig = (config, env) => {
+    var _a;
+    if (env === "local")
+        return undefined;
+    const envEntry = (_a = config.environments) === null || _a === void 0 ? void 0 : _a[env];
+    const declared = envEntry && envEntry.localAccess !== undefined
+        ? envEntry.localAccess
+        : config.localAccess;
+    return declared || undefined;
+};
+exports.getLocalAccessConfig = getLocalAccessConfig;
+/**
+ * the gcp roles local access grants in `env`: preset roles plus the
+ * explicit ones, deduplicated and sorted. Throws on an unknown preset,
+ * a malformed role or a denied (write/admin) role.
+ */
+const getLocalAccessGcpRoles = (config, env) => {
+    var _a, _b, _c;
+    const gcp = (_a = (0, exports.getLocalAccessConfig)(config, env)) === null || _a === void 0 ? void 0 : _a.gcp;
+    if (!gcp)
+        return [];
+    const roles = new Set();
+    for (const preset of (_b = gcp.presets) !== null && _b !== void 0 ? _b : []) {
+        const presetRoles = exports.LOCAL_ACCESS_GCP_PRESETS[preset];
+        if (!presetRoles) {
+            throw new Error(`localAccess (${env}): unknown gcp preset '${preset}', known: ${Object.keys(exports.LOCAL_ACCESS_GCP_PRESETS).join(", ")}`);
+        }
+        presetRoles.forEach((role) => roles.add(role));
+    }
+    for (const role of (_c = gcp.roles) !== null && _c !== void 0 ? _c : []) {
+        if (!ROLE_FORMAT.test(role)) {
+            throw new Error(`localAccess (${env}): '${role}' is not a valid role (expected e.g. roles/logging.viewer)`);
+        }
+        const reason = (0, exports.getDeniedLocalAccessRoleReason)(role, {
+            allowAnyRole: gcp.allowAnyRole,
+        });
+        if (reason) {
+            throw new Error(`localAccess (${env}): role '${role}' is not allowed (${reason})`);
+        }
+        roles.add(role);
+    }
+    return [...roles].sort();
+};
+exports.getLocalAccessGcpRoles = getLocalAccessGcpRoles;
+/**
+ * the envs of a component that declare gcp local access. Empty for
+ * components that do not deploy to google cloud run.
+ */
+const getLocalAccessGcpEnvs = (config, componentName) => (0, configruedEnvs_1.getAllEnvs)(config, componentName).filter((env) => 
+// only google cloud run envs have a project to grant roles in; the
+// env's own `deploy` overrides the component's
+(0, types_1.isOfDeployType)((0, getEnvConfig_1.getEnvConfig)(config, componentName, env).deploy, "google-cloudrun") && (0, exports.getLocalAccessGcpRoles)(config, env).length > 0);
+exports.getLocalAccessGcpEnvs = getLocalAccessGcpEnvs;
+/**
+ * name of the secret (stored under the `local` env of the component)
+ * holding the service account key of `env`'s local access
+ */
+const getLocalAccessGcpSecretName = (env) => `LOCAL_ACCESS_GCP_${env.replace(/[^A-Za-z0-9]+/g, "_").toUpperCase()}_CREDENTIALS`;
+exports.getLocalAccessGcpSecretName = getLocalAccessGcpSecretName;
+/**
+ * the bindings to add and remove so that `current` matches `desired`.
+ * The local access account is dedicated, so every binding it carries
+ * beyond the declaration is extra.
+ */
+const diffRoleBindings = (desired, current) => ({
+    missing: desired.filter((role) => !current.includes(role)),
+    extra: current.filter((role) => !desired.includes(role)),
+});
+exports.diffRoleBindings = diffRoleBindings;
+const ENV_VAR_NAME_FORMAT = /^[A-Za-z_][A-Za-z0-9_]*$/;
+/**
+ * the extra env var names (`credentialsEnvVar`) under which the local
+ * env of a component exports the key file path, mapped to the env whose
+ * key they point at. Throws on a malformed name or on two envs
+ * exporting the same name (e.g. a project default declaring it).
+ */
+const getLocalAccessGcpCredentialsEnvVars = (config, componentName) => {
+    var _a, _b;
+    const vars = {};
+    for (const env of (0, exports.getLocalAccessGcpEnvs)(config, componentName)) {
+        const name = (_b = (_a = (0, exports.getLocalAccessConfig)(config, env)) === null || _a === void 0 ? void 0 : _a.gcp) === null || _b === void 0 ? void 0 : _b.credentialsEnvVar;
+        if (!name)
+            continue;
+        if (!ENV_VAR_NAME_FORMAT.test(name)) {
+            throw new Error(`localAccess (${env}): credentialsEnvVar '${name}' is not a valid env var name`);
+        }
+        if (vars[name]) {
+            throw new Error(`localAccess (${componentName}): credentialsEnvVar '${name}' is declared by both ${vars[name]} and ${env}; declare it in one env only (environments.<env>.localAccess)`);
+        }
+        vars[name] = env;
+    }
+    return vars;
+};
+exports.getLocalAccessGcpCredentialsEnvVars = getLocalAccessGcpCredentialsEnvVars;
 //# sourceMappingURL=index.js.map
 
 /***/ }),