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

package/dist/bundles/skills/catladder-secrets/SKILL.md

@@ -6,7 +6,7 @@ description: Managing environment variables and secrets in a catladder project.
 # Env vars and secrets with catladder
 
 Environment variables are declared per component in `catladder.ts`;
-secret *values* are never checked into the repo.
+secret _values_ are never checked into the repo.
 
 ## Declaring variables
 
@@ -93,7 +93,7 @@ A few secrets are not typed in by a human but created by
 (`GCLOUD_DEPLOY_credentialsKey`) and the kubernetes deploy credentials
 (`KUBE_TOKEN`, `KUBE_CA_PEM`, `KUBE_URL`). They travel the same route as
 every other secret — vault first, then the enabled CI backends — but
-they are *hidden*: they never show up in `secrets-list`, in the editor
+they are _hidden_: they never show up in `secrets-list`, in the editor
 or in a pulled document, and they must never be set by hand.
 
 Re-running `project setup` **rotates** them (a fresh credential is
@@ -105,7 +105,7 @@ over, so re-run `project setup` to provision them into the new vault.
 ## GitHub pipelines
 
 GitHub Actions cannot read the vault at runtime; secrets are mirrored
-into GitHub *environment* secrets (one GitHub environment per catladder
+into GitHub _environment_ secrets (one GitHub environment per catladder
 env). Sync them with:
 
 ```sh
@@ -122,6 +122,38 @@ direnv) for the `local` environment. If a var is missing locally,
 check its declaration in `catladder.ts` and re-run `yarn catenv` before
 suspecting anything else.
 
+### Read-only cloud access for local use
+
+For google cloud run components, `localAccess` in `catladder.ts`
+(project default at the top level, per env in `environments.<env>`,
+`false` to disable) declares read-only access for local use, e.g.
+`localAccess: { gcp: { presets: ["logs"] } }`. `catladder project setup`
+creates a service account per component/env with exactly those roles and
+stores its key in the secret store under the `local` env (never mirrored
+to CI); `catladder project doctor` reports drift. `catenv` writes the key
+to `.catladder/local-access/gcp-<env>-<component>.json` (0600, gitignored)
+and exports its path as `CATLADDER_LOCAL_ACCESS_GCP_<ENV>_KEY_FILE` — not
+as `GOOGLE_APPLICATION_CREDENTIALS`, use it with an isolated
+`CLOUDSDK_CONFIG`, never `gcloud auth` on the personal config. The
+`logs` preset is `roles/logging.viewer` only (project-wide); extra `roles`
+must be `roles/{logging,monitoring,errorreporting}.viewer` (never `roles/viewer`/`roles/run.viewer`:
+cloud run revisions carry secrets as plain env vars), unless
+`allowAnyRole: true` (also needed for custom roles); write/admin roles are always rejected. Needs a
+non-CI vault (e.g. bitwarden) — `project setup` refuses with the gitlab
+vault. After a key rotation on another machine, run
+`catenv --vault-mode refresh`.
+
+The `vertex` preset grants `roles/aiplatform.user` (to call Vertex AI
+models, e.g. local evals). It is **not** read-only: it can use and bill
+every Vertex AI API of the project and create/change/delete Vertex AI
+resources; it is only accepted as a preset, never in `roles`. Add
+`credentialsEnvVar: "GOOGLE_APPLICATION_CREDENTIALS"` (in one env only)
+to have catenv export the key path under that name as well, so google
+client libraries use it without `gcloud auth application-default login`.
+The variable lands in the component's `.env` (e.g. `apps/web/.env`), not
+in a root `.env`: scripts run from the repo root must load that file
+(`node --env-file-if-exists=apps/web/.env …`).
+
 ## Related skills
 
 - `catladder-config` — general catladder.ts structure and regeneration

package/dist/packages/pipeline/src/index.d.ts

@@ -20,3 +20,4 @@ export * from "./utils/measureTime";
 export * from "../../bash/src/index.js";
 export * from "./catenv";
 export * from "./agentSkills";
+export * from "./localAccess";

package/dist/packages/pipeline/src/index.js

@@ -36,4 +36,5 @@ __exportStar(require("./utils/measureTime"), exports);
 __exportStar(require("../../bash/src/index.js"), exports);
 __exportStar(require("./catenv"), exports);
 __exportStar(require("./agentSkills"), exports);
+__exportStar(require("./localAccess"), exports);
 //# sourceMappingURL=index.js.map

package/dist/packages/pipeline/src/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../../../packages/pipeline/src/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;AAAA,6CAA2B;AAC3B,6CAA2B;AAC3B,+CAA6B;AAC7B,6CAA2B;AAC3B,0CAAwB;AACxB,0CAAwB;AACxB,2CAAyB;AACzB,+DAA6C;AAC7C,+DAA6C;AAC7C,2CAAyB;AACzB,0CAAwB;AACxB,4CAA0B;AAC1B,0CAAwB;AACxB,2CAAyB;AACzB,2CAAyB;AACzB,kDAAgC;AAChC,4CAA0B;AAC1B,qDAAmC;AACnC,sDAAoC;AACpC,kDAAgC;AAChC,2CAAyB;AACzB,gDAA8B"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../../../packages/pipeline/src/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;AAAA,6CAA2B;AAC3B,6CAA2B;AAC3B,+CAA6B;AAC7B,6CAA2B;AAC3B,0CAAwB;AACxB,0CAAwB;AACxB,2CAAyB;AACzB,+DAA6C;AAC7C,+DAA6C;AAC7C,2CAAyB;AACzB,0CAAwB;AACxB,4CAA0B;AAC1B,0CAAwB;AACxB,2CAAyB;AACzB,2CAAyB;AACzB,kDAAgC;AAChC,4CAA0B;AAC1B,qDAAmC;AACnC,sDAAoC;AACpC,kDAAgC;AAChC,2CAAyB;AACzB,gDAA8B;AAC9B,gDAA8B"}

package/dist/packages/pipeline/src/localAccess/index.d.ts

@@ -0,0 +1,53 @@
+import type { Config, LocalAccessConfig, LocalAccessGcpPreset } from "../types";
+export declare const LOCAL_ACCESS_GCP_PRESETS: Record<LocalAccessGcpPreset, string[]>;
+/** name prefix of the service account `project setup` creates (see getGcloudServiceAccountNames) */
+export declare const LOCAL_ACCESS_GCP_SA_NAME = "local-diag";
+/**
+ * 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.
+ */
+export declare const getDeniedLocalAccessRoleReason: (role: string, options?: {
+    allowAnyRole?: boolean;
+}) => string | undefined;
+/**
+ * the effective local access declaration of an env: the env's own
+ * declaration replaces the project default entirely
+ */
+export declare const getLocalAccessConfig: (config: Pick<Config, "localAccess" | "environments">, env: string) => Exclude<LocalAccessConfig, false> | undefined;
+/**
+ * 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.
+ */
+export declare const getLocalAccessGcpRoles: (config: Pick<Config, "localAccess" | "environments">, env: string) => string[];
+/**
+ * the envs of a component that declare gcp local access. Empty for
+ * components that do not deploy to google cloud run.
+ */
+export declare const getLocalAccessGcpEnvs: (config: Config, componentName: string) => string[];
+/**
+ * name of the secret (stored under the `local` env of the component)
+ * holding the service account key of `env`'s local access
+ */
+export declare const getLocalAccessGcpSecretName: (env: string) => string;
+/**
+ * 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.
+ */
+export declare const diffRoleBindings: (desired: string[], current: string[]) => {
+    missing: string[];
+    extra: string[];
+};
+/**
+ * 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).
+ */
+export declare const getLocalAccessGcpCredentialsEnvVars: (config: Config, componentName: string) => Record<string, string>;

package/dist/packages/pipeline/src/localAccess/index.js

@@ -0,0 +1,177 @@
+"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 = require("../config/configruedEnvs");
+const getEnvConfig_1 = require("../context/getEnvConfig");
+const types_1 = require("../deploy/types");
+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

package/dist/packages/pipeline/src/localAccess/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../../../../packages/pipeline/src/localAccess/index.ts"],"names":[],"mappings":";;;AAAA,6DAAsD;AACtD,0DAAuD;AACvD,2CAAiD;AAGpC,QAAA,wBAAwB,GACnC;IACE,qDAAqD;IACrD,IAAI,EAAE,CAAC,sBAAsB,CAAC;IAC9B,+DAA+D;IAC/D,+DAA+D;IAC/D,MAAM,EAAE,CAAC,uBAAuB,CAAC;CAClC,CAAC;AAEJ,oGAAoG;AACvF,QAAA,wBAAwB,GAAG,YAAY,CAAC;AAErD,MAAM,WAAW,GACf,iHAAiH,CAAC;AAEpH;;;;;GAKG;AACH,MAAM,qBAAqB,GAA2B;IACpD,cAAc,EAAE,oDAAoD;IACpE,kBAAkB,EAAE,wDAAwD;IAC5E,oCAAoC,EAAE,+BAA+B;IACrE,2BAA2B,EAAE,+BAA+B;CAC7D,CAAC;AAEF;;;;;;GAMG;AACH,MAAM,UAAU,GAAG;IACjB,sBAAsB;IACtB,yBAAyB;IACzB,6BAA6B;CAC9B,CAAC;AAEF,oFAAoF;AACpF,MAAM,WAAW,GAAG,CAAC,IAAY,EAAE,EAAE,WACnC,OAAA,CAAC,MAAA,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,GAAG,EAAE,mCAAI,IAAI,CAAC,CAAC,OAAO,CAAC,aAAa,EAAE,EAAE,CAAC,CAAA,EAAA,CAAC;AAE7D;;;;;;;;GAQG;AACI,MAAM,8BAA8B,GAAG,CAC5C,IAAY,EACZ,UAAsC,EAAE,EACpB,EAAE;;IACtB,MAAM,YAAY,GAAG,qBAAqB,CAAC,IAAI,CAAC,CAAC;IACjD,IAAI,YAAY;QAAE,OAAO,YAAY,CAAC;IAEtC,MAAM,IAAI,GAAG,WAAW,CAAC,IAAI,CAAC,CAAC;IAC/B,IAAI,IAAI,KAAK,OAAO,IAAI,IAAI,KAAK,QAAQ,EAAE,CAAC;QAC1C,OAAO,mCAAmC,CAAC;IAC7C,CAAC;IACD,MAAM,IAAI,GAAG,MAAA,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,GAAG,EAAE,mCAAI,IAAI,CAAC;IAC3C,IAAI,SAAS,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC;QACzB,OAAO,kCAAkC,CAAC;IAC5C,CAAC;IACD,IACE,+FAA+F,CAAC,IAAI,CAClG,IAAI,CACL;QACD,CAAC,QAAQ,CAAC,IAAI,CAAC,IAAI,CAAC,EACpB,CAAC;QACD,OAAO,gCAAgC,CAAC;IAC1C,CAAC;IACD,IACE,QAAQ,CAAC,IAAI,CAAC,IAAI,CAAC;QACnB,8FAA8F,CAAC,IAAI,CACjG,IAAI,CACL,EACD,CAAC;QACD,OAAO,iDAAiD,CAAC;IAC3D,CAAC;IACD,IAAI,CAAC,OAAO,CAAC,YAAY,IAAI,CAAC,UAAU,CAAC,QAAQ,CAAC,IAAI,CAAC,EAAE,CAAC;QACxD,OAAO,iCAAiC,UAAU,CAAC,IAAI,CAAC,IAAI,CAAC,4DAA4D,CAAC;IAC5H,CAAC;IACD,OAAO,SAAS,CAAC;AACnB,CAAC,CAAC;AAnCW,QAAA,8BAA8B,kCAmCzC;AAEF;;;GAGG;AACI,MAAM,oBAAoB,GAAG,CAClC,MAAoD,EACpD,GAAW,EACoC,EAAE;;IACjD,IAAI,GAAG,KAAK,OAAO;QAAE,OAAO,SAAS,CAAC;IACtC,MAAM,QAAQ,GAAG,MAAA,MAAM,CAAC,YAAY,0CAAG,GAAG,CAAC,CAAC;IAC5C,MAAM,QAAQ,GACZ,QAAQ,IAAI,QAAQ,CAAC,WAAW,KAAK,SAAS;QAC5C,CAAC,CAAC,QAAQ,CAAC,WAAW;QACtB,CAAC,CAAC,MAAM,CAAC,WAAW,CAAC;IACzB,OAAO,QAAQ,IAAI,SAAS,CAAC;AAC/B,CAAC,CAAC;AAXW,QAAA,oBAAoB,wBAW/B;AAEF;;;;GAIG;AACI,MAAM,sBAAsB,GAAG,CACpC,MAAoD,EACpD,GAAW,EACD,EAAE;;IACZ,MAAM,GAAG,GAAG,MAAA,IAAA,4BAAoB,EAAC,MAAM,EAAE,GAAG,CAAC,0CAAE,GAAG,CAAC;IACnD,IAAI,CAAC,GAAG;QAAE,OAAO,EAAE,CAAC;IAEpB,MAAM,KAAK,GAAG,IAAI,GAAG,EAAU,CAAC;IAChC,KAAK,MAAM,MAAM,IAAI,MAAA,GAAG,CAAC,OAAO,mCAAI,EAAE,EAAE,CAAC;QACvC,MAAM,WAAW,GAAG,gCAAwB,CAAC,MAAM,CAAC,CAAC;QACrD,IAAI,CAAC,WAAW,EAAE,CAAC;YACjB,MAAM,IAAI,KAAK,CACb,gBAAgB,GAAG,0BAA0B,MAAM,aAAa,MAAM,CAAC,IAAI,CAAC,gCAAwB,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CACnH,CAAC;QACJ,CAAC;QACD,WAAW,CAAC,OAAO,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,KAAK,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC;IACjD,CAAC;IACD,KAAK,MAAM,IAAI,IAAI,MAAA,GAAG,CAAC,KAAK,mCAAI,EAAE,EAAE,CAAC;QACnC,IAAI,CAAC,WAAW,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC;YAC5B,MAAM,IAAI,KAAK,CACb,gBAAgB,GAAG,OAAO,IAAI,4DAA4D,CAC3F,CAAC;QACJ,CAAC;QACD,MAAM,MAAM,GAAG,IAAA,sCAA8B,EAAC,IAAI,EAAE;YAClD,YAAY,EAAE,GAAG,CAAC,YAAY;SAC/B,CAAC,CAAC;QACH,IAAI,MAAM,EAAE,CAAC;YACX,MAAM,IAAI,KAAK,CACb,gBAAgB,GAAG,YAAY,IAAI,qBAAqB,MAAM,GAAG,CAClE,CAAC;QACJ,CAAC;QACD,KAAK,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;IAClB,CAAC;IACD,OAAO,CAAC,GAAG,KAAK,CAAC,CAAC,IAAI,EAAE,CAAC;AAC3B,CAAC,CAAC;AAlCW,QAAA,sBAAsB,0BAkCjC;AAEF;;;GAGG;AACI,MAAM,qBAAqB,GAAG,CACnC,MAAc,EACd,aAAqB,EACX,EAAE,CACZ,IAAA,2BAAU,EAAC,MAAM,EAAE,aAAa,CAAC,CAAC,MAAM,CACtC,CAAC,GAAG,EAAE,EAAE;AACN,mEAAmE;AACnE,+CAA+C;AAC/C,IAAA,sBAAc,EACZ,IAAA,2BAAY,EAAC,MAAM,EAAE,aAAa,EAAE,GAAG,CAAC,CAAC,MAAM,EAC/C,iBAAiB,CAClB,IAAI,IAAA,8BAAsB,EAAC,MAAM,EAAE,GAAG,CAAC,CAAC,MAAM,GAAG,CAAC,CACtD,CAAC;AAZS,QAAA,qBAAqB,yBAY9B;AAEJ;;;GAGG;AACI,MAAM,2BAA2B,GAAG,CAAC,GAAW,EAAE,EAAE,CACzD,oBAAoB,GAAG,CAAC,OAAO,CAAC,gBAAgB,EAAE,GAAG,CAAC,CAAC,WAAW,EAAE,cAAc,CAAC;AADxE,QAAA,2BAA2B,+BAC6C;AAErF;;;;GAIG;AACI,MAAM,gBAAgB,GAAG,CAC9B,OAAiB,EACjB,OAAiB,EACuB,EAAE,CAAC,CAAC;IAC5C,OAAO,EAAE,OAAO,CAAC,MAAM,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC;IAC1D,KAAK,EAAE,OAAO,CAAC,MAAM,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC;CACzD,CAAC,CAAC;AANU,QAAA,gBAAgB,oBAM1B;AAEH,MAAM,mBAAmB,GAAG,0BAA0B,CAAC;AAEvD;;;;;GAKG;AACI,MAAM,mCAAmC,GAAG,CACjD,MAAc,EACd,aAAqB,EACG,EAAE;;IAC1B,MAAM,IAAI,GAA2B,EAAE,CAAC;IACxC,KAAK,MAAM,GAAG,IAAI,IAAA,6BAAqB,EAAC,MAAM,EAAE,aAAa,CAAC,EAAE,CAAC;QAC/D,MAAM,IAAI,GAAG,MAAA,MAAA,IAAA,4BAAoB,EAAC,MAAM,EAAE,GAAG,CAAC,0CAAE,GAAG,0CAAE,iBAAiB,CAAC;QACvE,IAAI,CAAC,IAAI;YAAE,SAAS;QACpB,IAAI,CAAC,mBAAmB,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC;YACpC,MAAM,IAAI,KAAK,CACb,gBAAgB,GAAG,yBAAyB,IAAI,+BAA+B,CAChF,CAAC;QACJ,CAAC;QACD,IAAI,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC;YACf,MAAM,IAAI,KAAK,CACb,gBAAgB,aAAa,yBAAyB,IAAI,yBAAyB,IAAI,CAAC,IAAI,CAAC,QAAQ,GAAG,+DAA+D,CACxK,CAAC;QACJ,CAAC;QACD,IAAI,CAAC,IAAI,CAAC,GAAG,GAAG,CAAC;IACnB,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC,CAAC;AArBW,QAAA,mCAAmC,uCAqB9C"}

package/dist/packages/pipeline/src/types/config.d.ts

@@ -201,6 +201,13 @@ export type EnvironmentConfig = {
      * axes separately.
      */
     inherit?: EnvironmentInheritConfig;
+    /**
+     * read-only access to this env's cloud resources for LOCAL use
+     * (agents, scripts), see {@link LocalAccessConfig}. Overrides the
+     * project default (top-level `localAccess`) entirely; `false`
+     * switches it off for this env.
+     */
+    localAccess?: LocalAccessConfig;
 };
 /**
  * what an environment inherits from another environment.
@@ -236,6 +243,65 @@ export type EnvironmentsConfig = Record<string, EnvironmentConfig | false>;
  */
 export declare const getEnvironmentConfig: (environments: EnvironmentsConfig | undefined, env: string) => EnvironmentConfig | undefined;
 export declare const isEnvironmentDisabled: (environments: EnvironmentsConfig | undefined, env: string) => boolean;
+/**
+ * named bundles of gcp roles for {@link LocalAccessGcpConfig}
+ *
+ * - `logs`: `roles/logging.viewer` only. Deliberately NOT
+ *   `roles/run.viewer`: cloud run services/jobs are deployed with
+ *   their secrets as plain env vars, so anything with `run.*.get`
+ *   can read every deployed secret.
+ * - `vertex`: `roles/aiplatform.user`, to call Vertex AI models (e.g.
+ *   for local evals). NOT read-only: it may use (and bill) every Vertex
+ *   AI API of the project and create, change and delete Vertex AI
+ *   resources (datasets, endpoints, models, jobs). It reads no other
+ *   service's data. Only available as a preset, `roles` rejects it.
+ */
+export type LocalAccessGcpPreset = "logs" | "vertex";
+export type LocalAccessGcpConfig = {
+    /** preset role bundles, see {@link LocalAccessGcpPreset} */
+    presets?: LocalAccessGcpPreset[];
+    /**
+     * additional explicit roles (e.g. `roles/monitoring.viewer`).
+     * Write/admin roles are rejected; everything else you grant here is
+     * your responsibility — the key file lives on developer machines.
+     */
+    roles?: string[];
+    /**
+     * lifts the default allow-list (only a few known-safe roles:
+     * logging/monitoring/errorreporting viewers; custom roles need this).
+     * Write/admin/impersonation roles and roles exposing secrets
+     * (`roles/viewer`, `roles/run.viewer`, secret accessors) stay denied.
+     * What you grant beyond the allow-list is your responsibility.
+     */
+    allowAnyRole?: boolean;
+    /**
+     * also export the key file path under this env var name in the
+     * `local` env of the component (in addition to
+     * `CATLADDER_LOCAL_ACCESS_GCP_<ENV>_KEY_FILE`), e.g.
+     * `GOOGLE_APPLICATION_CREDENTIALS` so google client libraries use the
+     * key instead of a personal ADC login. Every process that loads the
+     * component's env then acts as the service account, so declare it in
+     * one env only (two envs exporting the same name are rejected).
+     * Overrides a var of the same name declared in `vars` while the key
+     * file exists.
+     */
+    credentialsEnvVar?: string;
+};
+/**
+ * which access LOCAL use gets for an env (read-only, unless a preset
+ * like `vertex` says otherwise). `project setup`
+ * creates a dedicated service account per component/env, grants exactly
+ * these bindings (and removes bindings no longer declared) and stores
+ * its key in the secret store under the `local` env — never in CI
+ * variables. catenv writes the key to a gitignored file.
+ *
+ * `false` disables it. Without a declaration nothing is created: the
+ * env stays reachable with the personal gcloud login only.
+ */
+export type LocalAccessConfig = {
+    /** google cloud (only for components deploying to google cloud run) */
+    gcp?: LocalAccessGcpConfig;
+} | false;
 export type EnvironmentInheritConfig = string | {
     /** env whose per-component config overrides are inherited */
     config?: string;
@@ -451,6 +517,15 @@ export type Config<C extends ConfigProps = never> = {
      *   A single component opts out with `env.<name>: false` instead.
      */
     environments?: EnvironmentsConfig;
+    /**
+     * project default for the read-only access LOCAL use gets per env
+     * (see {@link LocalAccessConfig}), overridable per env in
+     * `environments.<env>.localAccess`. Never applies to the `local` env.
+     *
+     * @example
+     * localAccess: { gcp: { presets: ["logs"] } }
+     */
+    localAccess?: LocalAccessConfig;
     /**
      * components (sub apps)
      */

package/dist/packages/pipeline/src/types/config.js.map

@@ -1 +1 @@
-{"version":3,"file":"config.js","sourceRoot":"","sources":["../../../../../../../packages/pipeline/src/types/config.ts"],"names":[],"mappings":";;;AAmBa,QAAA,qBAAqB,GAAG;IACnC,YAAY;IACZ,IAAI;IACJ,eAAe;CACP,CAAC;AAoBJ,MAAM,eAAe,GAAG,CAC7B,OAA2B,EACO,EAAE,CACpC,OAAO,OAAO,KAAK,QAAQ,IAAI,OAAO,KAAK,IAAI,IAAI,QAAQ,IAAI,OAAO,CAAC;AAH5D,QAAA,eAAe,mBAG6C;AAElE,MAAM,gBAAgB,GAAG,CAC9B,CAA0B,EAC1B,CAAqB,EACZ,EAAE;IACX,IAAI,CAAC,KAAK,SAAS,IAAI,CAAC,KAAK,KAAK;QAAE,OAAO,KAAK,CAAC;IACjD,IAAI,IAAA,uBAAe,EAAC,CAAC,CAAC;QAAE,OAAO,IAAA,uBAAe,EAAC,CAAC,CAAC,IAAI,CAAC,CAAC,MAAM,KAAK,CAAC,CAAC,MAAM,CAAC;IAC3E,OAAO,CAAC,KAAK,CAAC,CAAC;AACjB,CAAC,CAAC;AAPW,QAAA,gBAAgB,oBAO3B;AAEF;;;GAGG;AACU,QAAA,SAAS,GAAG;IACvB,GAAG,EAAE;QACH,QAAQ,EAAE,CAAC,YAAY,CAAC;KACzB;IACD,MAAM,EAAE;QACN,QAAQ,EAAE,CAAC,IAAI,CAAC;KACjB;IACD,KAAK,EAAE;QACL,QAAQ,EAAE,CAAC,eAAe,CAAC;KAC5B;IACD,IAAI,EAAE;QACJ,QAAQ,EAAE,CAAC,eAAe,CAAC;KAC5B;IACD,KAAK,EAAE;QACL,QAAQ,EAAE,EAAE;KACb;CACO,CAAC;AAEE,QAAA,YAAY,GAAG,MAAM,CAAC,IAAI,CAAC,iBAAS,CAAC,CAAC;AACtC,QAAA,iBAAiB,GAAG,oBAAyB,CAAC;AAGpD,MAAM,aAAa,GAAG,CAAC,GAAW,EAAkB,EAAE;IAC3D,OAAO,GAAG,IAAI,iBAAS,CAAC;AAC1B,CAAC,CAAC;AAFW,QAAA,aAAa,iBAExB;AAmMF;;;GAGG;AACI,MAAM,oBAAoB,GAAG,CAClC,YAA4C,EAC5C,GAAW,EACoB,EAAE,CAAC,CAAA,YAAY,aAAZ,YAAY,uBAAZ,YAAY,CAAG,GAAG,CAAC,KAAI,SAAS,CAAC;AAHxD,QAAA,oBAAoB,wBAGoC;AAE9D,MAAM,qBAAqB,GAAG,CACnC,YAA4C,EAC5C,GAAW,EACF,EAAE,CAAC,CAAA,YAAY,aAAZ,YAAY,uBAAZ,YAAY,CAAG,GAAG,CAAC,MAAK,KAAK,CAAC;AAH/B,QAAA,qBAAqB,yBAGU"}
+{"version":3,"file":"config.js","sourceRoot":"","sources":["../../../../../../../packages/pipeline/src/types/config.ts"],"names":[],"mappings":";;;AAmBa,QAAA,qBAAqB,GAAG;IACnC,YAAY;IACZ,IAAI;IACJ,eAAe;CACP,CAAC;AAoBJ,MAAM,eAAe,GAAG,CAC7B,OAA2B,EACO,EAAE,CACpC,OAAO,OAAO,KAAK,QAAQ,IAAI,OAAO,KAAK,IAAI,IAAI,QAAQ,IAAI,OAAO,CAAC;AAH5D,QAAA,eAAe,mBAG6C;AAElE,MAAM,gBAAgB,GAAG,CAC9B,CAA0B,EAC1B,CAAqB,EACZ,EAAE;IACX,IAAI,CAAC,KAAK,SAAS,IAAI,CAAC,KAAK,KAAK;QAAE,OAAO,KAAK,CAAC;IACjD,IAAI,IAAA,uBAAe,EAAC,CAAC,CAAC;QAAE,OAAO,IAAA,uBAAe,EAAC,CAAC,CAAC,IAAI,CAAC,CAAC,MAAM,KAAK,CAAC,CAAC,MAAM,CAAC;IAC3E,OAAO,CAAC,KAAK,CAAC,CAAC;AACjB,CAAC,CAAC;AAPW,QAAA,gBAAgB,oBAO3B;AAEF;;;GAGG;AACU,QAAA,SAAS,GAAG;IACvB,GAAG,EAAE;QACH,QAAQ,EAAE,CAAC,YAAY,CAAC;KACzB;IACD,MAAM,EAAE;QACN,QAAQ,EAAE,CAAC,IAAI,CAAC;KACjB;IACD,KAAK,EAAE;QACL,QAAQ,EAAE,CAAC,eAAe,CAAC;KAC5B;IACD,IAAI,EAAE;QACJ,QAAQ,EAAE,CAAC,eAAe,CAAC;KAC5B;IACD,KAAK,EAAE;QACL,QAAQ,EAAE,EAAE;KACb;CACO,CAAC;AAEE,QAAA,YAAY,GAAG,MAAM,CAAC,IAAI,CAAC,iBAAS,CAAC,CAAC;AACtC,QAAA,iBAAiB,GAAG,oBAAyB,CAAC;AAGpD,MAAM,aAAa,GAAG,CAAC,GAAW,EAAkB,EAAE;IAC3D,OAAO,GAAG,IAAI,iBAAS,CAAC;AAC1B,CAAC,CAAC;AAFW,QAAA,aAAa,iBAExB;AA2MF;;;GAGG;AACI,MAAM,oBAAoB,GAAG,CAClC,YAA4C,EAC5C,GAAW,EACoB,EAAE,CAAC,CAAA,YAAY,aAAZ,YAAY,uBAAZ,YAAY,CAAG,GAAG,CAAC,KAAI,SAAS,CAAC;AAHxD,QAAA,oBAAoB,wBAGoC;AAE9D,MAAM,qBAAqB,GAAG,CACnC,YAA4C,EAC5C,GAAW,EACF,EAAE,CAAC,CAAA,YAAY,aAAZ,YAAY,uBAAZ,YAAY,CAAG,GAAG,CAAC,MAAK,KAAK,CAAC;AAH/B,QAAA,qBAAqB,yBAGU"}

package/dist/skills/catladder-secrets/SKILL.md

@@ -6,7 +6,7 @@ description: Managing environment variables and secrets in a catladder project.
 # Env vars and secrets with catladder
 
 Environment variables are declared per component in `catladder.ts`;
-secret *values* are never checked into the repo.
+secret _values_ are never checked into the repo.
 
 ## Declaring variables
 
@@ -93,7 +93,7 @@ A few secrets are not typed in by a human but created by
 (`GCLOUD_DEPLOY_credentialsKey`) and the kubernetes deploy credentials
 (`KUBE_TOKEN`, `KUBE_CA_PEM`, `KUBE_URL`). They travel the same route as
 every other secret — vault first, then the enabled CI backends — but
-they are *hidden*: they never show up in `secrets-list`, in the editor
+they are _hidden_: they never show up in `secrets-list`, in the editor
 or in a pulled document, and they must never be set by hand.
 
 Re-running `project setup` **rotates** them (a fresh credential is
@@ -105,7 +105,7 @@ over, so re-run `project setup` to provision them into the new vault.
 ## GitHub pipelines
 
 GitHub Actions cannot read the vault at runtime; secrets are mirrored
-into GitHub *environment* secrets (one GitHub environment per catladder
+into GitHub _environment_ secrets (one GitHub environment per catladder
 env). Sync them with:
 
 ```sh
@@ -122,6 +122,38 @@ direnv) for the `local` environment. If a var is missing locally,
 check its declaration in `catladder.ts` and re-run `yarn catenv` before
 suspecting anything else.
 
+### Read-only cloud access for local use
+
+For google cloud run components, `localAccess` in `catladder.ts`
+(project default at the top level, per env in `environments.<env>`,
+`false` to disable) declares read-only access for local use, e.g.
+`localAccess: { gcp: { presets: ["logs"] } }`. `catladder project setup`
+creates a service account per component/env with exactly those roles and
+stores its key in the secret store under the `local` env (never mirrored
+to CI); `catladder project doctor` reports drift. `catenv` writes the key
+to `.catladder/local-access/gcp-<env>-<component>.json` (0600, gitignored)
+and exports its path as `CATLADDER_LOCAL_ACCESS_GCP_<ENV>_KEY_FILE` — not
+as `GOOGLE_APPLICATION_CREDENTIALS`, use it with an isolated
+`CLOUDSDK_CONFIG`, never `gcloud auth` on the personal config. The
+`logs` preset is `roles/logging.viewer` only (project-wide); extra `roles`
+must be `roles/{logging,monitoring,errorreporting}.viewer` (never `roles/viewer`/`roles/run.viewer`:
+cloud run revisions carry secrets as plain env vars), unless
+`allowAnyRole: true` (also needed for custom roles); write/admin roles are always rejected. Needs a
+non-CI vault (e.g. bitwarden) — `project setup` refuses with the gitlab
+vault. After a key rotation on another machine, run
+`catenv --vault-mode refresh`.
+
+The `vertex` preset grants `roles/aiplatform.user` (to call Vertex AI
+models, e.g. local evals). It is **not** read-only: it can use and bill
+every Vertex AI API of the project and create/change/delete Vertex AI
+resources; it is only accepted as a preset, never in `roles`. Add
+`credentialsEnvVar: "GOOGLE_APPLICATION_CREDENTIALS"` (in one env only)
+to have catenv export the key path under that name as well, so google
+client libraries use it without `gcloud auth application-default login`.
+The variable lands in the component's `.env` (e.g. `apps/web/.env`), not
+in a root `.env`: scripts run from the repo root must load that file
+(`node --env-file-if-exists=apps/web/.env …`).
+
 ## Related skills
 
 - `catladder-config` — general catladder.ts structure and regeneration