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

package/dist/bundles/catenv/index.js

@@ -331,6 +331,7 @@ exports.createVaultManagerGetter = createVaultManagerGetter;
 
 Object.defineProperty(exports, "__esModule", ({ value: true }));
 const getProjectConfig_1 = __nccwpck_require__(70478);
+const keyFiles_1 = __nccwpck_require__(70180);
 const printVariables_1 = __nccwpck_require__(32507);
 const verboseBanner_1 = __nccwpck_require__(95423);
 const writeDotEnvFiles_1 = __nccwpck_require__(16699);
@@ -356,6 +357,8 @@ exports["default"] = async (choice, options) => {
     if (options === null || options === void 0 ? void 0 : options.verbose) {
         (0, verboseBanner_1.printVerboseBanner)();
     }
+    // before the env vars are resolved: they point at the key files
+    await (0, keyFiles_1.writeLocalAccessKeyFiles)(io, config);
     await Promise.all([
         (0, pipeline_1.generatePipelineFiles)(context),
         (0, writeDotEnvFiles_1.writeDotEnvFiles)(context, choice),
@@ -671,6 +674,7 @@ program.parse();
 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);
@@ -791,12 +795,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;
 /**
@@ -931,6 +942,145 @@ exports.gitProjectInformation = gitProjectInformation;
 
 /***/ }),
 
+/***/ 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) => {
 
@@ -1347,6 +1497,38 @@ exports.getProjectNamespace = getProjectNamespace;
 
 /***/ }),
 
+/***/ 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__) => {
 
@@ -1453,30 +1635,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],
+                    }
+                    : {}),
+            }));
         }
     }
 }
@@ -1523,6 +1696,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);
@@ -1605,6 +1779,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
@@ -1628,6 +1811,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,
@@ -1737,14 +1928,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));
@@ -1762,6 +1979,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");
@@ -1776,7 +1994,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 = {
@@ -1784,7 +2002,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;
 /**
@@ -12677,6 +12897,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
 
 /***/ }),