# Villa Market secrets

> secrets.villamarket.ai stores API keys and passwords for Villa services, encrypted (AES-256-GCM) in DynamoDB. People sign in with their SSH key; services read with their AWS IAM role.

## Rules for AI agents
- Never print, echo, log, paste or summarise a secret value, not even its length. Do not read one "to check it".
- Never ask a person to paste a secret into chat. Tell them to run `villa-secret put GROUP NAME` (hidden prompt, or `--dialog` for a macOS pop-up) themselves.
- In code, fetch secrets at runtime with the service's IAM role (below). Never put them in env files, source, tickets or commit messages.

## People (SSH key)
- Install: `curl -fsSL https://secrets.villamarket.ai/villa-secret -o ~/.local/bin/villa-secret && chmod +x ~/.local/bin/villa-secret`
- `villa-secret whoami` · `villa-secret ls [GROUP]` · `villa-secret put GROUP NAME` · `villa-secret get GROUP NAME` · `villa-secret console`
- The key is `~/.ssh/id_ed25519` (or `id_ecdsa`, `id_rsa`, or `--key`). Signing is `ssh-keygen -Y sign -n villa-secrets`.

## Services (AWS IAM role)
- An admin adds the role ARN to the group's readers in https://secrets.villamarket.ai/admin.
- Code: https://secrets.villamarket.ai/client.py → `fetch_secret(group, name)`. It signs sts:GetCallerIdentity with header `x-villa-secrets-server: secrets.villamarket.ai`.

## API
- `GET /v1/challenge` → sign `villa-secrets session\n<challenge>` → `POST /v1/session {challenge, signature}` → Bearer token (15 min)
- `GET /v1/groups`, `GET|PUT|DELETE /v1/groups/{group}/secrets/{NAME}`, `GET /v1/audit?group=`
- `POST /v1/machine/secret {group, name, iam}` for services