#16663: feat: GCP Secret Manager integration for external secrets management

Closes #13610 **Labels:** `size: XS` `enhancement` `security` ## Summary Adds native GCP Secret Manager integration so credentials can be stored in an encrypted, access-controlled secrets store instead of plaintext files on disk. ## What - **Secret reference syntax** — `${gcp:secret-name}` in config files, resolved at runtime - **GcpSecretProvider** — fetches secrets via `@google-cloud/secret-manager` (optional, dynamically imported) - **In-memory cache** with configurable TTL and stale-while-revalidate fallback - **Per-agent isolation** — each agent uses its own GCP service account; IAM bindings enforce access at the GCP level - **CLI commands** — `openclaw secrets setup|test|list|set|migrate` - **Migration scripts** — bootstrap GCP, migrate plaintext secrets, set per-secret IAM bindings - **Config schema** — new `secrets` section in `openclaw.json` (Zod-validated) - **Async post-processing** — `resolveConfigSecrets()` runs after `loadConfig()`; existing sync call sites unchanged - **Full documentation** — concept page, GCP Console guide, worked multi-agent example ## Files | File | Purpose | |---|---| | `src/config/secret-resolution.ts` | Core module — ref parsing, GcpSecretProvider, cache, config tree walking | | `src/config/secret-resolution.test.ts` | 74 unit tests | | `src/commands/secrets.ts` | CLI commands | | `src/commands/secrets.test.ts` | 22 CLI tests | | `docs/concepts/secrets.md` | Full documentation with worked multi-agent example | | `docs/concepts/secrets-gcp-console-guide.md` | Step-by-step GCP Console setup guide | | `scripts/secrets/bootstrap-gcp.sh` | Enable APIs, create service accounts, generate keys | | `scripts/secrets/migrate-secrets.sh` | Scan, store, verify, purge plaintext credentials | | `scripts/secrets/set-iam-bindings.sh` | Set per-secret IAM bindings for agent isolation | | `src/config/config.ts` | Re-exports | | `src/config/types.openclaw.ts` | TypeScript types | | `src/config/zod-schema.ts` | Schema validation | | `test/setup.ts` | Default GCP mock for test env | | `package.json` | `@google-cloud/secret-manager` as devDependency | ## Design decisions - **Option A (async post-processing):** `loadConfig()` stays synchronous; `resolveConfigSecrets()` is a separate async step. Least invasive. - **Optional dependency:** `@google-cloud/secret-manager` is dynamically imported. Clear error if not installed. - **Backward compatible:** No `secrets` config = no behavior change. Entirely opt-in. - **Per-agent isolation via IAM:** Not application-level filtering — GCP itself blocks unauthorized access. ## Testing - 96 tests (74 unit + 22 CLI), all passing - 0 lint errors (oxlint --type-aware) - End-to-end tested on live GCP Secret Manager with real credentials - Per-agent isolation verified: agents cannot read each other's secrets (PERMISSION_DENIED) ## Requirements & Design docs - [Requirements](https://github.com/amor71/openclaw-secrets/blob/main/REQUIREMENTS-gcp-secrets.md) - [Design](https://github.com/amor71/openclaw-secrets/blob/main/DESIGN-gcp-secrets.md) - [Source + scripts](https://github.com/amor71/openclaw-secrets) > 🤖 This PR was developed with AI assistance (Claude Opus via OpenClaw), per CONTRIBUTING.md guidelines. <!-- greptile_comment --> <h3>Greptile Summary</h3> This PR adds comprehensive secrets management support for GCP, AWS, Azure, and HashiCorp Vault, along with rotation reminders and auto-rotation for gateway tokens. The implementation includes secret reference syntax (`${provider:secret-name}`), in-memory caching with TTL, lazy-loaded optional dependencies, CLI commands, migration scripts, and extensive test coverage (96 tests). **Key changes:** - Core secret resolution with 4 provider implementations (GCP, AWS, Azure, Vault) - Auto-rotation system for gateway tokens with configurable intervals - Rotation reminder system with snooze capabilities - Per-agent isolation via IAM bindings (GCP) - CLI commands for setup, testing, listing, setting, and migrating secrets - Full backward compatibility (opt-in via `secrets` config section) **Issues found:** - Schema mismatch: `zod-schema.ts:634-651` only allows `gcp` provider but code registers both `gcp` and `aws` in `buildSecretProviders()`, causing AWS configs to fail validation - Documentation inconsistency: `docs/concepts/secrets.md` lists AWS/Azure/Vault as "Planned" but they're fully implemented with tests - Minor redundancy in AWS provider: `setSecret()` calls `PutSecretValueCommand` after `CreateSecretCommand` when the create already stores the value <h3>Confidence Score: 3/5</h3> - Safe to merge after fixing schema validation for AWS provider - Strong implementation with comprehensive tests (96 passing), proper error handling, and security best practices. However, the schema bug prevents AWS provider configs from validating, which will cause runtime failures for users trying AWS. Documentation mismatches are minor but should be corrected. The auto-rotation and multi-provider features add complexity that warrants careful review of edge cases. - `src/config/zod-schema.ts` needs AWS/Azure/Vault provider schemas added _{Last reviewed commit: 6ec4efc} <!-- greptile_other_comments_section --> <!-- /greptile_comment -->