Troubleshooting and decisions
Related: cognito-and-auth · secrets-and-configuration · test-account-and-integration-tests
Cognito
| Symptom | Cause | Fix |
|---|---|---|
Unable to verify secret hash | Used Client Secret ID instead of secret value | Cognito → Show client secret |
| Login works locally, CI fails | Missing VILLA_COGNITO_CLIENT_SECRET in GitHub | Add repo secret |
| SignUp succeeds, login fails | User not confirmed | Console confirm or confirm_sign_up |
NotAuthorizedException | Wrong password or auth flow disabled | Enable ALLOW_USER_PASSWORD_AUTH |
PyPI / packaging
| Issue | Resolution |
|---|---|
Name villa-backend-sdk rejected | Published as villa-market-backend-sdk |
| twine metadata 2.4 error | Cap setuptools<77 in pyproject.toml |
Testing strategy
| Decision | Rationale |
|---|---|
| SignUp API for test user, not IAM admin | Matches real app users; no admin credentials in CI |
| Shared test account in repo JSON | Credentials are dev-only; secret stays in env |
| Unit vs integration split | Unit mocked; integration uses live Cognito JWT |
Documentation
| Decision | Rationale |
|---|---|
docs/knowledge/ Obsidian notes | Summarized decisions + wikilinks for humans/agents |
AGENTS.md at repo root | Cursor/agent quick reference |
| S3 static site from markdown | Shareable manual without GitHub access |
Security
VILLA_COGNITO_CLIENT_SECRET or PYPI_KEYgit-secrets blocks accidental commits; it is not a secret store