Credential Broker — authenticate agents to your cloud
TFactory’s agents increasingly need to reach real services and cloud environments to plan, generate, and run tests — a staging API, a Kubernetes cluster, a Google/AWS/Azure project. The Credential Broker (epic #62) gives them a secure, declarative way to obtain those credentials without ever putting a secret in the repo, and with an honest accounting of what leaves your network.
The problem it solves
Before the broker, the only way to give an agent a credential was a raw environment variable or a key checked into config. That is:
- unsafe — secrets leak into shells, logs, and git history;
- inflexible — no way to pull from the vault your org already runs;
- opaque — nothing told you what a run would reach over the network.
The broker replaces all three with a pluggable resolution layer + an explicit egress gate.
What it does
-
Pluggable backends
Resolve secrets from a vault — Azure Key Vault, AWS Secrets Manager, GCP Secret Manager, HashiCorp Vault — or local encrypted files (sops / age / agenix). One ref syntax, lazily-loaded SDKs.
-
Ephemeral by design
File credentials (kubeconfig, GCP ADC) are written 0600 to a per-task scratch dir and wiped when the task ends. Values are redacted from logs. Never persisted in the clear.
-
Honest egress
Off by default — no cloud credential is resolved unless the project opts in.
tfactory_secrets.cli auditprints a secret-free manifest of exactly what would leave your network, with a 🔒 / 🏠 / ☁️ badge.
Why we built it this way
| Decision | Why |
|---|---|
| Agents first (not the test sandbox) | The immediate need was agents reaching cloud APIs to plan/generate tests. Sandbox-test injection is a deliberate fast-follow (#73). |
| Extend, don’t replace | The broker builds on TFactory’s existing core/mcp_credentials.py chain (K8s / AWS-IRSA / Azure-MI / GCP-ADC) — it adds a “fetch from a vault” head, it doesn’t reinvent ambient auth. |
| Pass-through in v1 | Resolve → inject → wipe. Minting short-lived federated credentials (OIDC → STS / Workload Identity) is a fast-follow (#74) so v1 ships sooner. |
| Egress opt-in + manifest | The same honest posture as TFactory’s BYO-LLM egress badge: you should always be able to see what a run touches before it runs. |
Reference syntax
env:STAGING_API_TOKEN # an environment variable
sops:secrets.enc.yaml#api_token # a sops-encrypted file + key
agenix:db-password.age # an agenix / age file
vault:secret/data/staging#token # HashiCorp Vault (KV-v1/v2)
azurekv://my-vault/STAGING-TOKEN # Azure Key Vault
aws-sm://staging/api#token # AWS Secrets Manager (JSON field)
gcp-sm://my-project/sa-key # GCP Secret Manager (optional /version)
Try it
# 1. Declare creds + opt into egress in .tfactory.yml
egress:
enabled: true
credentials:
gcp: { ref: "gcp-sm://my-proj/tfactory-sa", as: GOOGLE_APPLICATION_CREDENTIALS, kind: file }
# 2. See exactly what would leave your network (secret-free)
python -m tfactory_secrets.cli audit .
# 3. Check which backends are wired here
python -m tfactory_secrets.cli doctor
Full reference: guides/credentials.md.
Design: docs/plans/2026-05-30-credential-broker-design.md.