From d2abc37268ec79829bb12ba78f0734c482161192 Mon Sep 17 00:00:00 2001 From: Colin Smith <7762103+colinmxs@users.noreply.github.com> Date: Thu, 9 Apr 2026 08:51:05 -0600 Subject: [PATCH] Release 1.0.0-beta.22: Cognito-native auth, CORS unification, RBAC consolidation, Trivy supply chain fix MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit ⚠️ BREAKING CHANGE: Authentication replaced with AWS Cognito. The legacy generic OIDC implementation has been removed with no backward compatibility layer. Existing deployments must re-bootstrap. Cognito First-Boot Authentication: - Cognito User Pool, App Client, and Domain provisioned in Infrastructure stack - CognitoJWTValidator replaces GenericOIDCJWTValidator - New system/ module for first-boot setup, Cognito user/group management - New cognito_idp_service for federated identity provider CRUD via Cognito IdP APIs - First-boot page with admin account creation (race-condition-safe DynamoDB writes) - Frontend auth flow rewritten for Cognito OAuth 2.0 + PKCE - Runtime-provisioner and runtime-updater Lambda functions removed (2,800+ lines) - Backend OIDC service, token exchange, and discovery endpoints removed (1,318 lines) - 2,057 lines of new Cognito test coverage (IdP service, JWT validator, first-boot, system) RBAC Consolidation: - Single require_app_roles dependency replaces 6 role-checking functions/decorators - User roles enriched from stored DynamoDB profile during token processing - Profile cache invalidation on sync for immediate role updates - JSON array parsing for custom:roles claim (Entra ID compatibility) - jwt_role_mappings updates allowed on system_admin role CORS Unification: - buildCorsOrigins() shared helper across all 6 CDK stacks - S3 CORS made conditional, ExposedHeaders→ExposeHeaders fix - Python APIs read CORS_ORIGINS env var (replaces allow_origins=['*']) Security: - Trivy action upgraded v0.28.0→v0.35.0 — old SHA was compromised in March 2026 supply chain attack (GHSA-69fq-xp46-6x23) CI/CD: - CDK_DOMAIN_NAME and CDK_CORS_ORIGINS added to all workflow jobs - App API synth-cdk actually skipped on PRs (guard was missing despite beta.20 docs) - SSM StringParameter creation guarded against empty values Bootstrap: - seed_bootstrap_data.py sole owner of RBAC role seeding (removed from app startup) - system_admin role seeded with jwt_role_mappings=['system_admin'] - Additive JWT mapping seeding for existing deployments Documentation: - 54,665 lines of outdated specs and AI artifacts purged (121 files) Dependencies: - Python: fastapi 0.135.3, uvicorn 0.44.0, boto3 1.42.83, strands-agents 1.34.1, bedrock-agentcore 1.6.0, google-genai 1.70.0, ruff 0.15.9, mypy 1.20.0 - Frontend: Angular 21.2.7, katex 0.16.45, mermaid 11.14.0, Analog.js alpha.26 - Infrastructure: aws-cdk-lib 2.248.0, aws-cdk 2.1117.0, ts-jest 29.4.9 --- .claude/skills/cors-deployment/SKILL.md | 87 + .claude/skills/release-notes/SKILL.md | 91 + .github/ACTIONS-REFERENCE.md | 22 +- .github/agents/devops-agent.agent.md | 292 -- .github/docs/deploy/step-01-prerequisites.md | 23 +- .github/docs/deploy/step-03-github-config.md | 38 +- .github/docs/deploy/step-04-deploy.md | 5 +- .github/docs/deploy/step-05-verify.md | 27 +- .github/docs/deploy/troubleshooting.md | 31 +- .github/workflows/app-api.yml | 4 + .github/workflows/bootstrap-data-seeding.yml | 12 - .github/workflows/frontend.yml | 2 + .github/workflows/gateway.yml | 6 + .github/workflows/inference-api.yml | 10 +- .github/workflows/infrastructure.yml | 6 + .github/workflows/nightly-deploy-pipeline.yml | 3 + .github/workflows/nightly.yml | 6 +- .kiro/specs/agent-core-tests/.config.kiro | 1 - .kiro/specs/agent-core-tests/design.md | 318 -- .kiro/specs/agent-core-tests/requirements.md | 360 -- .kiro/specs/agent-core-tests/tasks.md | 216 -- .kiro/specs/api-route-tests/.config.kiro | 1 - .kiro/specs/api-route-tests/design.md | 332 -- .kiro/specs/api-route-tests/requirements.md | 207 - .kiro/specs/api-route-tests/tasks.md | 187 - .kiro/specs/auth-rbac-tests/.config.kiro | 1 - .kiro/specs/auth-rbac-tests/design.md | 478 --- .kiro/specs/auth-rbac-tests/requirements.md | 288 -- .kiro/specs/auth-rbac-tests/tasks.md | 233 -- .../backend-architecture-cleanup/design.md | 770 ---- .../requirements.md | 204 - .../backend-architecture-cleanup/tasks.md | 284 -- .../specs/bootstrap-data-seeding/.config.kiro | 1 - .kiro/specs/bootstrap-data-seeding/design.md | 403 -- .../bootstrap-data-seeding/requirements.md | 116 - .kiro/specs/bootstrap-data-seeding/tasks.md | 153 - .../cognito-first-boot-auth/.config.kiro | 1 + .kiro/specs/cognito-first-boot-auth/design.md | 888 +++++ .../cognito-first-boot-auth/requirements.md | 201 + .kiro/specs/cognito-first-boot-auth/tasks.md | 297 ++ .kiro/specs/config-cleanup-audit/.config.kiro | 1 - .kiro/specs/config-cleanup-audit/design.md | 333 -- .../config-cleanup-audit/requirements.md | 277 -- .kiro/specs/config-cleanup-audit/tasks.md | 309 -- .../environment-agnostic-refactor/design.md | 1172 ------ .../requirements.md | 186 - .../task-10.1-summary.md | 153 - .../environment-agnostic-refactor/tasks.md | 436 --- .../github-actions-documentation/.config.kiro | 1 - .../github-actions-documentation/design.md | 505 --- .../requirements.md | 162 - .../github-actions-documentation/tasks.md | 132 - .../github-actions-job-summaries/.config.kiro | 1 - .../github-actions-job-summaries/design.md | 249 -- .../requirements.md | 160 - .../github-actions-job-summaries/tasks.md | 200 - .../FRONTEND_AUTH_STRATEGY.md | 259 -- .../multi-runtime-auth-providers/design.md | 970 ----- .../requirements.md | 231 -- .../multi-runtime-auth-providers/tasks.md | 333 -- .../nodejs24-actions-upgrade/.config.kiro | 1 - .../specs/nodejs24-actions-upgrade/design.md | 139 - .../nodejs24-actions-upgrade/requirements.md | 93 - .kiro/specs/nodejs24-actions-upgrade/tasks.md | 146 - .../rag-ingestion-stack/DEPLOYMENT_GUIDE.md | 464 --- .../IMPLEMENTATION_SUMMARY.md | 413 -- .../rag-ingestion-stack/MIGRATION_GUIDE.md | 311 -- .../MIGRATION_IMPLEMENTATION.md | 310 -- .../rag-ingestion-stack/READY_TO_DEPLOY.md | 238 -- .kiro/specs/rag-ingestion-stack/design.md | 1171 ------ .../specs/rag-ingestion-stack/requirements.md | 389 -- .../task-7-verification-results.md | 319 -- .kiro/specs/rag-ingestion-stack/tasks.md | 443 --- .kiro/specs/runtime-config/design.md | 764 ---- .kiro/specs/runtime-config/requirements.md | 159 - .../specs/runtime-config/task-2.4-summary.md | 119 - .../specs/runtime-config/task-3.1-summary.md | 249 -- .../specs/runtime-config/task-3.2-summary.md | 235 -- .../specs/runtime-config/task-3.3-summary.md | 132 - .../specs/runtime-config/task-3.4-summary.md | 163 - .../task-3.5-completion-summary.md | 209 - .../task-5.2-app-initializer-test-summary.md | 87 - .../tasks-3.3-and-3.4-completion-summary.md | 263 -- .kiro/specs/runtime-config/tasks.md | 519 --- .../specs/shared-tables-refactor/.config.kiro | 1 - .kiro/specs/shared-tables-refactor/design.md | 605 --- .../shared-tables-refactor/requirements.md | 127 - .kiro/specs/shared-tables-refactor/tasks.md | 190 - .kiro/specs/ssm-parameters-audit/.config.kiro | 1 - .kiro/specs/ssm-parameters-audit/design.md | 767 ---- .../ssm-parameters-audit/requirements.md | 121 - .kiro/specs/ssm-parameters-audit/tasks.md | 110 - .../specs/supply-chain-hardening/.config.kiro | 1 - .kiro/specs/supply-chain-hardening/design.md | 611 --- .../supply-chain-hardening/requirements.md | 231 -- .kiro/specs/supply-chain-hardening/tasks.md | 221 -- .kiro/specs/versioning-strategy/.config.kiro | 1 - .kiro/specs/versioning-strategy/design.md | 531 --- .../specs/versioning-strategy/requirements.md | 164 - .kiro/specs/versioning-strategy/tasks.md | 175 - .kiro/steering/cors-configuration.md | 80 + .kiro/steering/devops.md | 22 +- .kiro/steering/release-notes.md | 91 + .kiro/steering/structure.md | 1 - CLAUDE.MD | 380 +- CODE_REVIEW_TOKEN_STORAGE.md | 216 -- GEMINI.md | 88 - README.md | 7 +- RELEASE_NOTES.md | 197 + VERSION | 2 +- backend/README.md | 7 - .../runtime-provisioner/README.md | 199 - .../runtime-provisioner/lambda_function.py | 1113 ------ .../runtime-provisioner/requirements.txt | 1 - .../runtime-provisioner/tests/__init__.py | 0 .../runtime-provisioner/tests/conftest.py | 333 -- .../runtime-provisioner/tests/test_handler.py | 113 - .../runtime-provisioner/tests/test_helpers.py | 255 -- .../runtime-provisioner/tests/test_insert.py | 199 - .../runtime-provisioner/tests/test_modify.py | 370 -- .../runtime-provisioner/tests/test_remove.py | 103 - .../tests/test_runtime_name.py | 65 - .../runtime-updater/README.md | 198 - .../runtime-updater/lambda_function.py | 745 ---- .../runtime-updater/requirements.txt | 1 - .../runtime-updater/tests/__init__.py | 0 .../runtime-updater/tests/conftest.py | 290 -- .../tests/test_event_parsing.py | 85 - .../runtime-updater/tests/test_handler.py | 181 - .../runtime-updater/tests/test_helpers.py | 122 - .../tests/test_notifications.py | 148 - .../runtime-updater/tests/test_parallel.py | 97 - .../runtime-updater/tests/test_providers.py | 116 - .../runtime-updater/tests/test_retry.py | 293 -- .../runtime-updater/tests/test_smoke.py | 70 - backend/pyproject.toml | 22 +- backend/scripts/seed_bootstrap_data.py | 479 +-- .../agents/main_agent/quota/event_recorder.py | 6 +- .../session/tests/test_compaction.py | 4 +- .../tests/test_compaction_integration.py | 7 + backend/src/apis/app_api/admin/README.md | 4 +- .../app_api/admin/auth_providers/routes.py | 21 - backend/src/apis/app_api/admin/routes.py | 2 + backend/src/apis/app_api/auth/models.py | 66 - backend/src/apis/app_api/auth/routes.py | 370 +- backend/src/apis/app_api/auth/service.py | 320 -- backend/src/apis/app_api/files/routes.py | 8 +- backend/src/apis/app_api/main.py | 43 +- backend/src/apis/app_api/models/routes.py | 4 +- .../sessions/tests/test_cache_savings.py | 10 +- backend/src/apis/app_api/system/__init__.py | 17 + .../apis/app_api/system/cognito_service.py | 193 + backend/src/apis/app_api/system/models.py | 25 + backend/src/apis/app_api/system/repository.py | 130 + backend/src/apis/app_api/system/routes.py | 168 + backend/src/apis/app_api/tools/routes.py | 10 +- backend/src/apis/app_api/users/models.py | 11 + backend/src/apis/app_api/users/routes.py | 53 +- backend/src/apis/inference_api/main.py | 22 +- backend/src/apis/shared/auth/__init__.py | 28 +- .../apis/shared/auth/cognito_jwt_validator.py | 133 + backend/src/apis/shared/auth/dependencies.py | 263 +- .../apis/shared/auth/generic_jwt_validator.py | 338 -- backend/src/apis/shared/auth/rbac.py | 189 +- .../auth_providers/cognito_idp_service.py | 310 ++ .../src/apis/shared/auth_providers/models.py | 14 + .../apis/shared/auth_providers/repository.py | 18 +- .../src/apis/shared/auth_providers/service.py | 238 +- backend/src/apis/shared/oauth/routes.py | 4 +- backend/src/apis/shared/rbac/admin_service.py | 17 +- backend/src/apis/shared/rbac/service.py | 4 +- backend/src/apis/shared/rbac/system_admin.py | 6 +- .../agents/main_agent/session/conftest.py | 51 +- backend/tests/auth/test_auth_routes.py | 308 +- .../tests/auth/test_cognito_jwt_validator.py | 400 ++ backend/tests/auth/test_dependencies.py | 150 +- .../tests/auth/test_generic_jwt_validator.py | 586 --- backend/tests/auth/test_oidc_auth_service.py | 269 -- backend/tests/auth/test_pkce.py | 59 - backend/tests/auth/test_rbac.py | 198 +- .../tests/rbac/test_app_role_admin_service.py | 16 +- backend/tests/routes/test_auth.py | 118 +- backend/tests/routes/test_pbt_auth_sweep.py | 55 +- .../routes/test_pbt_request_validation.py | 4 +- .../shared/test_auth_providers_extended.py | 1 + .../tests/shared/test_cognito_idp_service.py | 1177 ++++++ backend/tests/system/__init__.py | 1 + backend/tests/system/test_first_boot.py | 286 ++ backend/tests/system/test_system.py | 278 ++ backend/tests/test_seed_system_admin_jwt.py | 145 +- backend/uv.lock | 211 +- codeql-alerts.json | 3372 ----------------- docs/ADMIN_COST_DASHBOARD_SPEC.md | 1148 ------ docs/ARCHITECTURE_DEBT.md | 152 - docs/ASSISTANT_EMAIL_SHARING_PLAN.md | 275 -- docs/AWS_PROFILE_GUIDE.md | 375 -- docs/CONFIG_INVENTORY.md | 158 - docs/QUOTA_MANAGEMENT_PHASE1_SPEC.md | 1911 ---------- ...MANAGEMENT_PHASE2_IMPLEMENTATION_STATUS.md | 400 -- docs/QUOTA_MANAGEMENT_PHASE2_SPEC.md | 1421 ------- docs/QUOTA_QUICK_START.md | 328 -- docs/QUOTA_VALIDATION_GUIDE.md | 904 ----- docs/RBAC_IMPLEMENTATION.md | 367 -- docs/SESSION_DELETION_SPEC.md | 1078 ------ docs/USER_ADMIN_SPEC.md | 2310 ----------- docs/USER_COST_TRACKING_SPEC.md | 2193 ----------- .../QUOTA_IMPLEMENTATION_SUMMARY.md | 438 --- docs/feature-summaries/RBAC_IMPLEMENTATION.md | 16 +- docs/specs/ADMIN_COST_DASHBOARD_SPEC.md | 1148 ------ docs/specs/APP_ROLES_RBAC_SPEC.md | 2053 ---------- docs/specs/CONTEXT_SUMMARIZATION_SPEC.md | 566 --- docs/specs/FILE_MULTIMODAL_CHAT_SPEC.md | 808 ---- docs/specs/FILE_UPLOAD_FEATURE_SPEC.md | 651 ---- docs/specs/SESSION_DELETION_SPEC.md | 1078 ------ docs/specs/TOOL_RBAC_SPEC.md | 1508 -------- docs/specs/USER_ADMIN_SPEC.md | 2310 ----------- docs/specs/USER_COST_TRACKING_SPEC.md | 2193 ----------- docs/specs/assistant-preview-refactor.md | 671 ---- frontend/ai.client/package-lock.json | 730 ++-- frontend/ai.client/package.json | 32 +- .../pages/provider-form.page.ts | 47 + .../pages/provider-list.page.ts | 252 +- .../manage-models/manage-models.page.html | 8 +- .../admin/manage-models/model-form.page.html | 46 +- .../app/admin/roles/pages/role-form.page.ts | 2 +- frontend/ai.client/src/app/app.routes.ts | 6 + .../services/preview-chat.service.spec.ts | 20 +- .../services/preview-chat.service.ts | 17 +- .../src/app/auth/auth-api.service.spec.ts | 101 - .../src/app/auth/auth-api.service.ts | 64 - .../ai.client/src/app/auth/auth.guard.spec.ts | 7 + frontend/ai.client/src/app/auth/auth.guard.ts | 21 +- .../src/app/auth/auth.interceptor.spec.ts | 30 +- .../src/app/auth/auth.interceptor.ts | 12 +- .../src/app/auth/auth.service.spec.ts | 404 +- .../ai.client/src/app/auth/auth.service.ts | 422 ++- .../src/app/auth/callback/callback.page.ts | 3 +- .../auth/callback/callback.service.spec.ts | 105 +- .../src/app/auth/callback/callback.service.ts | 82 +- .../src/app/auth/first-boot.guard.ts | 23 + .../app/auth/first-boot/first-boot.page.css | 5 + .../app/auth/first-boot/first-boot.page.ts | 315 ++ frontend/ai.client/src/app/auth/index.ts | 1 - .../src/app/auth/login/login.page.ts | 304 +- .../src/app/auth/parse-roles.spec.ts | 118 + .../ai.client/src/app/auth/parse-roles.ts | 44 + frontend/ai.client/src/app/auth/user.model.ts | 1 + .../src/app/auth/user.service.spec.ts | 76 +- .../ai.client/src/app/auth/user.service.ts | 49 +- .../app/components/sidenav/sidenav.spec.ts | 4 +- .../src/app/components/sidenav/sidenav.ts | 4 +- .../src/app/services/config.service.spec.ts | 6 +- .../src/app/services/config.service.ts | 54 + .../src/app/services/system.service.spec.ts | 92 + .../src/app/services/system.service.ts | 99 + .../services/chat/chat-http.service.spec.ts | 48 +- .../services/chat/chat-http.service.ts | 79 +- .../environments/environment.production.ts | 6 +- .../ai.client/src/environments/environment.ts | 6 +- infrastructure/cdk.context.json | 5 +- infrastructure/lib/app-api-stack.ts | 396 +- infrastructure/lib/config.ts | 107 +- infrastructure/lib/frontend-stack.ts | 54 +- infrastructure/lib/inference-api-stack.ts | 221 +- infrastructure/lib/infrastructure-stack.ts | 131 +- infrastructure/lib/rag-ingestion-stack.ts | 19 +- .../lib/sagemaker-fine-tuning-stack.ts | 18 +- infrastructure/package-lock.json | 68 +- infrastructure/package.json | 10 +- infrastructure/test/app-api-stack.test.ts | 164 +- infrastructure/test/config.test.ts | 64 +- infrastructure/test/cors.test.ts | 258 ++ infrastructure/test/helpers/mock-config.ts | 19 +- .../test/inference-api-stack.test.ts | 99 +- .../test/infrastructure-stack.test.ts | 6 +- .../test/rag-ingestion-stack.test.ts | 25 +- .../test/sagemaker-fine-tuning-stack.test.ts | 16 +- .../test/stack-dependencies.test.ts | 1 - package-lock.json | 6 - scripts/common/load-env.sh | 6 +- deploy.sh => scripts/deploy.sh | 0 scripts/stack-bootstrap/seed.sh | 18 +- scripts/stack-frontend/build.sh | 26 + scripts/stack-frontend/install.sh | 34 +- specs/ADMIN_OAUTH_PROVIDER_SPEC.md | 281 -- specs/QUOTA_BUDGET_MODEL_DOWNGRADE.md | 732 ---- 286 files changed, 9257 insertions(+), 65030 deletions(-) create mode 100644 .claude/skills/cors-deployment/SKILL.md create mode 100644 .claude/skills/release-notes/SKILL.md delete mode 100644 .github/agents/devops-agent.agent.md delete mode 100644 .kiro/specs/agent-core-tests/.config.kiro delete mode 100644 .kiro/specs/agent-core-tests/design.md delete mode 100644 .kiro/specs/agent-core-tests/requirements.md delete mode 100644 .kiro/specs/agent-core-tests/tasks.md delete mode 100644 .kiro/specs/api-route-tests/.config.kiro delete mode 100644 .kiro/specs/api-route-tests/design.md delete mode 100644 .kiro/specs/api-route-tests/requirements.md delete mode 100644 .kiro/specs/api-route-tests/tasks.md delete mode 100644 .kiro/specs/auth-rbac-tests/.config.kiro delete mode 100644 .kiro/specs/auth-rbac-tests/design.md delete mode 100644 .kiro/specs/auth-rbac-tests/requirements.md delete mode 100644 .kiro/specs/auth-rbac-tests/tasks.md delete mode 100644 .kiro/specs/backend-architecture-cleanup/design.md delete mode 100644 .kiro/specs/backend-architecture-cleanup/requirements.md delete mode 100644 .kiro/specs/backend-architecture-cleanup/tasks.md delete mode 100644 .kiro/specs/bootstrap-data-seeding/.config.kiro delete mode 100644 .kiro/specs/bootstrap-data-seeding/design.md delete mode 100644 .kiro/specs/bootstrap-data-seeding/requirements.md delete mode 100644 .kiro/specs/bootstrap-data-seeding/tasks.md create mode 100644 .kiro/specs/cognito-first-boot-auth/.config.kiro create mode 100644 .kiro/specs/cognito-first-boot-auth/design.md create mode 100644 .kiro/specs/cognito-first-boot-auth/requirements.md create mode 100644 .kiro/specs/cognito-first-boot-auth/tasks.md delete mode 100644 .kiro/specs/config-cleanup-audit/.config.kiro delete mode 100644 .kiro/specs/config-cleanup-audit/design.md delete mode 100644 .kiro/specs/config-cleanup-audit/requirements.md delete mode 100644 .kiro/specs/config-cleanup-audit/tasks.md delete mode 100644 .kiro/specs/environment-agnostic-refactor/design.md delete mode 100644 .kiro/specs/environment-agnostic-refactor/requirements.md delete mode 100644 .kiro/specs/environment-agnostic-refactor/task-10.1-summary.md delete mode 100644 .kiro/specs/environment-agnostic-refactor/tasks.md delete mode 100644 .kiro/specs/github-actions-documentation/.config.kiro delete mode 100644 .kiro/specs/github-actions-documentation/design.md delete mode 100644 .kiro/specs/github-actions-documentation/requirements.md delete mode 100644 .kiro/specs/github-actions-documentation/tasks.md delete mode 100644 .kiro/specs/github-actions-job-summaries/.config.kiro delete mode 100644 .kiro/specs/github-actions-job-summaries/design.md delete mode 100644 .kiro/specs/github-actions-job-summaries/requirements.md delete mode 100644 .kiro/specs/github-actions-job-summaries/tasks.md delete mode 100644 .kiro/specs/multi-runtime-auth-providers/FRONTEND_AUTH_STRATEGY.md delete mode 100644 .kiro/specs/multi-runtime-auth-providers/design.md delete mode 100644 .kiro/specs/multi-runtime-auth-providers/requirements.md delete mode 100644 .kiro/specs/multi-runtime-auth-providers/tasks.md delete mode 100644 .kiro/specs/nodejs24-actions-upgrade/.config.kiro delete mode 100644 .kiro/specs/nodejs24-actions-upgrade/design.md delete mode 100644 .kiro/specs/nodejs24-actions-upgrade/requirements.md delete mode 100644 .kiro/specs/nodejs24-actions-upgrade/tasks.md delete mode 100644 .kiro/specs/rag-ingestion-stack/DEPLOYMENT_GUIDE.md delete mode 100644 .kiro/specs/rag-ingestion-stack/IMPLEMENTATION_SUMMARY.md delete mode 100644 .kiro/specs/rag-ingestion-stack/MIGRATION_GUIDE.md delete mode 100644 .kiro/specs/rag-ingestion-stack/MIGRATION_IMPLEMENTATION.md delete mode 100644 .kiro/specs/rag-ingestion-stack/READY_TO_DEPLOY.md delete mode 100644 .kiro/specs/rag-ingestion-stack/design.md delete mode 100644 .kiro/specs/rag-ingestion-stack/requirements.md delete mode 100644 .kiro/specs/rag-ingestion-stack/task-7-verification-results.md delete mode 100644 .kiro/specs/rag-ingestion-stack/tasks.md delete mode 100644 .kiro/specs/runtime-config/design.md delete mode 100644 .kiro/specs/runtime-config/requirements.md delete mode 100644 .kiro/specs/runtime-config/task-2.4-summary.md delete mode 100644 .kiro/specs/runtime-config/task-3.1-summary.md delete mode 100644 .kiro/specs/runtime-config/task-3.2-summary.md delete mode 100644 .kiro/specs/runtime-config/task-3.3-summary.md delete mode 100644 .kiro/specs/runtime-config/task-3.4-summary.md delete mode 100644 .kiro/specs/runtime-config/task-3.5-completion-summary.md delete mode 100644 .kiro/specs/runtime-config/task-5.2-app-initializer-test-summary.md delete mode 100644 .kiro/specs/runtime-config/tasks-3.3-and-3.4-completion-summary.md delete mode 100644 .kiro/specs/runtime-config/tasks.md delete mode 100644 .kiro/specs/shared-tables-refactor/.config.kiro delete mode 100644 .kiro/specs/shared-tables-refactor/design.md delete mode 100644 .kiro/specs/shared-tables-refactor/requirements.md delete mode 100644 .kiro/specs/shared-tables-refactor/tasks.md delete mode 100644 .kiro/specs/ssm-parameters-audit/.config.kiro delete mode 100644 .kiro/specs/ssm-parameters-audit/design.md delete mode 100644 .kiro/specs/ssm-parameters-audit/requirements.md delete mode 100644 .kiro/specs/ssm-parameters-audit/tasks.md delete mode 100644 .kiro/specs/supply-chain-hardening/.config.kiro delete mode 100644 .kiro/specs/supply-chain-hardening/design.md delete mode 100644 .kiro/specs/supply-chain-hardening/requirements.md delete mode 100644 .kiro/specs/supply-chain-hardening/tasks.md delete mode 100644 .kiro/specs/versioning-strategy/.config.kiro delete mode 100644 .kiro/specs/versioning-strategy/design.md delete mode 100644 .kiro/specs/versioning-strategy/requirements.md delete mode 100644 .kiro/specs/versioning-strategy/tasks.md create mode 100644 .kiro/steering/cors-configuration.md create mode 100644 .kiro/steering/release-notes.md delete mode 100644 CODE_REVIEW_TOKEN_STORAGE.md delete mode 100644 GEMINI.md delete mode 100644 backend/lambda-functions/runtime-provisioner/README.md delete mode 100644 backend/lambda-functions/runtime-provisioner/lambda_function.py delete mode 100644 backend/lambda-functions/runtime-provisioner/requirements.txt delete mode 100644 backend/lambda-functions/runtime-provisioner/tests/__init__.py delete mode 100644 backend/lambda-functions/runtime-provisioner/tests/conftest.py delete mode 100644 backend/lambda-functions/runtime-provisioner/tests/test_handler.py delete mode 100644 backend/lambda-functions/runtime-provisioner/tests/test_helpers.py delete mode 100644 backend/lambda-functions/runtime-provisioner/tests/test_insert.py delete mode 100644 backend/lambda-functions/runtime-provisioner/tests/test_modify.py delete mode 100644 backend/lambda-functions/runtime-provisioner/tests/test_remove.py delete mode 100644 backend/lambda-functions/runtime-provisioner/tests/test_runtime_name.py delete mode 100644 backend/lambda-functions/runtime-updater/README.md delete mode 100644 backend/lambda-functions/runtime-updater/lambda_function.py delete mode 100644 backend/lambda-functions/runtime-updater/requirements.txt delete mode 100644 backend/lambda-functions/runtime-updater/tests/__init__.py delete mode 100644 backend/lambda-functions/runtime-updater/tests/conftest.py delete mode 100644 backend/lambda-functions/runtime-updater/tests/test_event_parsing.py delete mode 100644 backend/lambda-functions/runtime-updater/tests/test_handler.py delete mode 100644 backend/lambda-functions/runtime-updater/tests/test_helpers.py delete mode 100644 backend/lambda-functions/runtime-updater/tests/test_notifications.py delete mode 100644 backend/lambda-functions/runtime-updater/tests/test_parallel.py delete mode 100644 backend/lambda-functions/runtime-updater/tests/test_providers.py delete mode 100644 backend/lambda-functions/runtime-updater/tests/test_retry.py delete mode 100644 backend/lambda-functions/runtime-updater/tests/test_smoke.py delete mode 100644 backend/src/apis/app_api/auth/models.py delete mode 100644 backend/src/apis/app_api/auth/service.py create mode 100644 backend/src/apis/app_api/system/__init__.py create mode 100644 backend/src/apis/app_api/system/cognito_service.py create mode 100644 backend/src/apis/app_api/system/models.py create mode 100644 backend/src/apis/app_api/system/repository.py create mode 100644 backend/src/apis/app_api/system/routes.py create mode 100644 backend/src/apis/shared/auth/cognito_jwt_validator.py delete mode 100644 backend/src/apis/shared/auth/generic_jwt_validator.py create mode 100644 backend/src/apis/shared/auth_providers/cognito_idp_service.py create mode 100644 backend/tests/auth/test_cognito_jwt_validator.py delete mode 100644 backend/tests/auth/test_generic_jwt_validator.py delete mode 100644 backend/tests/auth/test_oidc_auth_service.py delete mode 100644 backend/tests/auth/test_pkce.py create mode 100644 backend/tests/shared/test_cognito_idp_service.py create mode 100644 backend/tests/system/__init__.py create mode 100644 backend/tests/system/test_first_boot.py create mode 100644 backend/tests/system/test_system.py delete mode 100644 codeql-alerts.json delete mode 100644 docs/ADMIN_COST_DASHBOARD_SPEC.md delete mode 100644 docs/ARCHITECTURE_DEBT.md delete mode 100644 docs/ASSISTANT_EMAIL_SHARING_PLAN.md delete mode 100644 docs/AWS_PROFILE_GUIDE.md delete mode 100644 docs/CONFIG_INVENTORY.md delete mode 100644 docs/QUOTA_MANAGEMENT_PHASE1_SPEC.md delete mode 100644 docs/QUOTA_MANAGEMENT_PHASE2_IMPLEMENTATION_STATUS.md delete mode 100644 docs/QUOTA_MANAGEMENT_PHASE2_SPEC.md delete mode 100644 docs/QUOTA_QUICK_START.md delete mode 100644 docs/QUOTA_VALIDATION_GUIDE.md delete mode 100644 docs/RBAC_IMPLEMENTATION.md delete mode 100644 docs/SESSION_DELETION_SPEC.md delete mode 100644 docs/USER_ADMIN_SPEC.md delete mode 100644 docs/USER_COST_TRACKING_SPEC.md delete mode 100644 docs/feature-summaries/QUOTA_IMPLEMENTATION_SUMMARY.md delete mode 100644 docs/specs/ADMIN_COST_DASHBOARD_SPEC.md delete mode 100644 docs/specs/APP_ROLES_RBAC_SPEC.md delete mode 100644 docs/specs/CONTEXT_SUMMARIZATION_SPEC.md delete mode 100644 docs/specs/FILE_MULTIMODAL_CHAT_SPEC.md delete mode 100644 docs/specs/FILE_UPLOAD_FEATURE_SPEC.md delete mode 100644 docs/specs/SESSION_DELETION_SPEC.md delete mode 100644 docs/specs/TOOL_RBAC_SPEC.md delete mode 100644 docs/specs/USER_ADMIN_SPEC.md delete mode 100644 docs/specs/USER_COST_TRACKING_SPEC.md delete mode 100644 docs/specs/assistant-preview-refactor.md delete mode 100644 frontend/ai.client/src/app/auth/auth-api.service.spec.ts delete mode 100644 frontend/ai.client/src/app/auth/auth-api.service.ts create mode 100644 frontend/ai.client/src/app/auth/first-boot.guard.ts create mode 100644 frontend/ai.client/src/app/auth/first-boot/first-boot.page.css create mode 100644 frontend/ai.client/src/app/auth/first-boot/first-boot.page.ts create mode 100644 frontend/ai.client/src/app/auth/parse-roles.spec.ts create mode 100644 frontend/ai.client/src/app/auth/parse-roles.ts create mode 100644 frontend/ai.client/src/app/services/system.service.spec.ts create mode 100644 frontend/ai.client/src/app/services/system.service.ts create mode 100644 infrastructure/test/cors.test.ts delete mode 100644 package-lock.json rename deploy.sh => scripts/deploy.sh (100%) mode change 100644 => 100755 scripts/stack-frontend/install.sh delete mode 100644 specs/ADMIN_OAUTH_PROVIDER_SPEC.md delete mode 100644 specs/QUOTA_BUDGET_MODEL_DOWNGRADE.md diff --git a/.claude/skills/cors-deployment/SKILL.md b/.claude/skills/cors-deployment/SKILL.md new file mode 100644 index 00000000..21315a57 --- /dev/null +++ b/.claude/skills/cors-deployment/SKILL.md @@ -0,0 +1,87 @@ +--- +name: cors-deployment +description: CORS configuration across all CDK stacks, GitHub Actions workflows, and Python backends. Use when modifying CORS origins, adding new stacks that need CORS, debugging CORS errors in deployed environments, or touching any workflow env vars related to CDK_DOMAIN_NAME or CDK_CORS_ORIGINS. +--- + +# CORS Deployment Configuration + +## Architecture + +CORS is configured via a two-layer model applied identically to every stack: + +1. `CDK_DOMAIN_NAME` → auto-applied as `https://{value}` (always) +2. `CDK_CORS_ORIGINS` → additional global origins (optional, comma-separated) +3. Per-section `CDK_*_CORS_ORIGINS` → stack-specific extras (optional) + +localhost is NEVER auto-included. Use `CDK_CORS_ORIGINS=http://localhost:4200` for local dev. + +## The Helper + +Every stack uses `buildCorsOrigins(config, additionalOrigins?)` from `infrastructure/lib/config.ts`. This returns a deduplicated `string[]`. + +```typescript +// Container env var (Fargate / AgentCore Runtime) +CORS_ORIGINS: buildCorsOrigins(config, config.appApi.additionalCorsOrigins).join(','), + +// S3 bucket CORS rule +cors: [{ allowedOrigins: buildCorsOrigins(config, config.fileUpload?.additionalCorsOrigins) }] +``` + +## Config Derivation (config.ts) + +``` +CDK_DOMAIN_NAME → domainName → "https://{domainName}" (always first) +CDK_CORS_ORIGINS → extraCorsOrigins (appended) +Result: config.corsOrigins = "https://{domainName},{extras}" +``` + +Both are joined into `config.corsOrigins`. The helper then splits, deduplicates, and optionally appends section extras. + +## Python Backend + +Both `app_api/main.py` and `inference_api/main.py` read `CORS_ORIGINS` env var: + +```python +_cors_origins = os.environ.get("CORS_ORIGINS", "").split(",") +``` + +No hardcoded fallback. If `CORS_ORIGINS` is empty, no origins are allowed. + +## Workflow Requirements + +`CDK_DOMAIN_NAME` and `CDK_CORS_ORIGINS` MUST be in the **job-level** `env:` block (not workflow-level) because they use `vars.*` which requires `environment:` on the job. + +Every workflow that runs synth or deploy must include: +```yaml +env: + CDK_DOMAIN_NAME: ${{ vars.CDK_DOMAIN_NAME }} + CDK_CORS_ORIGINS: ${{ vars.CDK_CORS_ORIGINS }} +``` + +## Per-Section Config Interfaces + +Every config section that consumes CORS has `additionalCorsOrigins?: string`: +- `AppApiConfig.additionalCorsOrigins` +- `InferenceApiConfig.additionalCorsOrigins` +- `FrontendConfig.additionalCorsOrigins` +- `FileUploadConfig.additionalCorsOrigins` +- `RagIngestionConfig.additionalCorsOrigins` +- `AssistantsConfig.additionalCorsOrigins` +- `FineTuningConfig.additionalCorsOrigins` + +## Adding CORS to a New Stack + +1. Import `buildCorsOrigins` from `./config` +2. Call `buildCorsOrigins(config, config.mySection.additionalCorsOrigins)` +3. Add `additionalCorsOrigins?: string` to the section's config interface +4. Load it in `loadConfig()`: `additionalCorsOrigins: process.env.CDK_MY_SECTION_CORS_ORIGINS || ...` +5. Add `CDK_DOMAIN_NAME` and `CDK_CORS_ORIGINS` to the workflow job env +6. Add a test in `infrastructure/test/cors.test.ts` + +## Common Mistakes + +- Putting `vars.*` in workflow-level `env:` → resolves to empty string +- Hardcoding `http://localhost:4200` in buildCorsOrigins or Python fallback +- Forgetting to add `CDK_DOMAIN_NAME` to a new workflow's synth/deploy jobs +- Using `config.domainName` directly instead of `buildCorsOrigins()` +- Setting `corsOrigins` in `cdk.context.json` (overrides domain derivation) diff --git a/.claude/skills/release-notes/SKILL.md b/.claude/skills/release-notes/SKILL.md new file mode 100644 index 00000000..ef0a5baa --- /dev/null +++ b/.claude/skills/release-notes/SKILL.md @@ -0,0 +1,91 @@ +--- +name: release-notes +description: Write and update RELEASE_NOTES.md for this monorepo. Use when creating release notes, updating an existing release entry, or preparing a release. Covers the squash-merge branch model, how to identify changes across divergent main/develop histories, writing style, section structure, and common pitfalls. +--- + +# Writing Release Notes + +## Branch Model & Why This Is Hard + +This repo uses a squash-merge workflow: `develop` accumulates feature branches via merge commits, and when a release is cut, `develop` is squash-merged into `main`. This means `main` and `develop` have **divergent git histories** — you cannot do a simple `git log main..develop` to get a clean diff. Commit SHAs on `main` don't correspond to anything on `develop`. + +## How to Identify What Changed + +### Step 1: Find the boundary + +Look at the last squash-merge commit on `main` to determine when the previous release was cut: + +```bash +git log main --oneline -5 +``` + +Then find the corresponding release tag or date. Use that date as your boundary. + +### Step 2: List commits on develop since the boundary + +```bash +git log develop --oneline --no-merges --since="" +``` + +This gives you the raw commit list, but **do not rely solely on commit messages**. Dependabot commits are usually accurate, but human commits often have vague or incomplete messages. + +### Step 3: Inspect the actual code changes + +For every non-trivial commit, read the diff or at minimum the `--stat` output: + +```bash +git show --stat +git show --no-patch # full commit message +``` + +For feature commits, read the changed files to understand what was actually built — not just what the message claims. Look for: + +- New API endpoints (routes files) +- New or modified models/schemas +- New frontend pages or components +- Infrastructure changes (CDK stacks, config) +- New test files (indicates new functionality) +- Dependency changes (pyproject.toml, package.json) + +### Step 4: Group by category + +Organize changes into the standard sections used by prior releases. Review the existing release notes in the file for the established pattern. Typical sections include: + +- **Highlights** — 2-3 sentence summary of the release theme +- **New features** — each gets its own H2 with subsections for backend/frontend/infra +- **Bug fixes** — concise list +- **Security** — vulnerability patches, CodeQL fixes +- **Dependency upgrades** — table format +- **CI/CD improvements** — workflow changes +- **Test fixes** — test-only changes +- **Deployment notes** — what operators need to do differently + +## Writing Style + +- Match the tone and depth of the existing release notes in the file. They are detailed and technical — written for developers who will deploy and maintain this system. +- Every feature section should explain **what** changed, **why** it matters, and **how** it works at a technical level. +- Use specific file names, endpoint paths, and class names when relevant. +- Include line counts for large test additions (e.g., "4,200+ lines of new tests"). +- For dependency upgrades, use a markdown table with From/To columns. +- The Highlights section should read as a standalone summary — someone skimming only that paragraph should understand the release. + +## Header Format + +```markdown +# Release Notes — v1.0.0-beta.XX + +**Release Date:** +**Previous Release:** v1.0.0-beta.XX-1 () + +--- +``` + +The new release goes at the **top** of the file. Do not modify previous release sections. + +## Common Pitfalls + +- **Don't trust commit messages blindly.** A commit titled "fix: update models" might contain a new feature with 800 lines of code. Always check the diff. +- **Don't miss Dependabot PRs.** They often bump 10+ packages in a single grouped PR. Check `pyproject.toml`, `package.json`, and workflow files for version changes. +- **Don't forget CI/CD changes.** Workflow file modifications (`.github/workflows/`) are easy to overlook but important for operators. +- **Don't duplicate sections.** If a feature spans backend + frontend + infra, keep it in one section with subsections — don't scatter it across the document. +- **Check the VERSION file and README badge.** These should already be updated via `sync-version.sh` before the release notes are finalized. diff --git a/.github/ACTIONS-REFERENCE.md b/.github/ACTIONS-REFERENCE.md index 78a0a51b..229ff65d 100644 --- a/.github/ACTIONS-REFERENCE.md +++ b/.github/ACTIONS-REFERENCE.md @@ -24,19 +24,23 @@ GitHub provides two mechanisms for storing configuration values: | AWS_SECRET_ACCESS_KEY | Secret | No | None | All | AWS secret access key for authentication (alternative to role-based auth) | | CDK_ALB_SUBDOMAIN | Variable | No | None | Infrastructure | Subdomain for ALB (e.g., 'api' for api.yourdomain.com) | | CDK_APP_API_CPU | Variable | No | `512` | Infrastructure, App API | CPU units for App API ECS task (256, 512, 1024, 2048, 4096) | +| CDK_APP_API_CORS_ORIGINS | Variable | No | None | App API | Additional CORS origins for the app API only (appended to global CORS origins) | | CDK_APP_API_DESIRED_COUNT | Variable | No | `1` | Infrastructure, App API | Desired number of App API tasks running | | CDK_APP_API_ENABLED | Variable | No | `true` | App API | Enable/disable App API stack deployment | | CDK_APP_API_MAX_CAPACITY | Variable | No | `10` | Infrastructure, App API | Maximum App API tasks for auto-scaling | | CDK_APP_API_MEMORY | Variable | No | `1024` | Infrastructure, App API | Memory (MB) for App API ECS task (512, 1024, 2048, 4096, 8192) | +| CDK_ASSISTANTS_CORS_ORIGINS | Variable | No | None | Infrastructure | Additional CORS origins for the assistants module only (appended to global CORS origins) | | CDK_AWS_ACCOUNT | Variable | Yes | None | All | 12-digit AWS account ID for CDK deployment | | CDK_CERTIFICATE_ARN | Variable | No | None | Infrastructure | ACM certificate ARN for HTTPS on ALB | -| CDK_CORS_ORIGINS | Variable | No | `http://localhost:4200,http://localhost:8000` | All | Top-level CORS origins (default for sections that don't override) | -| CDK_DOMAIN_NAME | Variable | No | None | Frontend, App API | Custom domain name (e.g., 'app.example.com') | -| CDK_FILE_UPLOAD_CORS_ORIGINS | Variable | No | `http://localhost:4200` | Infrastructure, App API | Comma-separated CORS origins for file upload S3 bucket | +| CDK_CORS_ORIGINS | Variable | No | None | All | Additional CORS origins appended to the auto-derived `https://{CDK_DOMAIN_NAME}`. Comma-separated. Use for localhost during local dev (e.g., `http://localhost:4200`) or extra domains. | +| CDK_DOMAIN_NAME | Variable | No | None | All | Primary domain name (e.g., 'alpha.boisestate.ai'). Auto-applied as `https://{value}` to CORS origins for every stack. This is the primary mechanism for CORS configuration. | +| CDK_FILE_UPLOAD_CORS_ORIGINS | Variable | No | None | Infrastructure | Additional CORS origins for the file upload S3 bucket only (appended to global CORS origins) | | CDK_FILE_UPLOAD_MAX_SIZE_MB | Variable | No | `10` | Infrastructure, App API | Maximum file upload size in megabytes | | CDK_FINE_TUNING_ENABLED | Variable | No | `false` | SageMaker Fine-Tuning, App API | Enable SageMaker fine-tuning stack and App API fine-tuning routes. Must be `true` before deploying the SageMaker Fine-Tuning workflow. | +| CDK_FINE_TUNING_CORS_ORIGINS | Variable | No | None | SageMaker Fine-Tuning | Additional CORS origins for the fine-tuning S3 bucket only (appended to global CORS origins) | | CDK_FINE_TUNING_DEFAULT_QUOTA_HOURS | Variable | No | `0` | App API | Default monthly GPU-hour quota for all authenticated users. `0` = whitelist-only (admin must grant each user). Positive value (e.g. `5`) = open access with that default budget. | | CDK_FRONTEND_BUCKET_NAME | Variable | No | None | Frontend | S3 bucket name for frontend assets (defaults to generated name with account ID) | +| CDK_FRONTEND_CORS_ORIGINS | Variable | No | None | Frontend | Additional CORS origins for the frontend SSM export only (appended to global CORS origins) | | CDK_FRONTEND_CERTIFICATE_ARN | Variable | No | None | Frontend | ACM certificate ARN for HTTPS on CloudFront (required for custom domain) | | CDK_FRONTEND_CLOUDFRONT_PRICE_CLASS | Variable | No | `PriceClass_100` | Frontend | CloudFront price class (PriceClass_100, PriceClass_200, PriceClass_All) | | CDK_FRONTEND_ENABLED | Variable | No | `true` | Frontend | Enable/disable Frontend stack deployment | @@ -48,20 +52,16 @@ GitHub provides two mechanisms for storing configuration values: | CDK_GATEWAY_THROTTLE_RATE_LIMIT | Variable | No | `10000` | Gateway | API Gateway rate limit for throttling (requests per second) | | CDK_HOSTED_ZONE_DOMAIN | Variable | No | None | Infrastructure, App API | Route53 hosted zone domain name (e.g., 'example.com') | | CDK_INFERENCE_API_CPU | Variable | No | `1024` | Infrastructure, Inference API | CPU units for Inference API AgentCore Runtime (256, 512, 1024, 2048, 4096) | +| CDK_INFERENCE_API_CORS_ORIGINS | Variable | No | None | Inference API | Additional CORS origins for the inference API only (appended to global CORS origins) | | CDK_INFERENCE_API_DESIRED_COUNT | Variable | No | `1` | Infrastructure, Inference API | Desired number of Inference API runtime instances | | CDK_INFERENCE_API_ENABLED | Variable | No | `true` | Inference API | Enable/disable Inference API stack deployment | | CDK_INFERENCE_API_MAX_CAPACITY | Variable | No | `5` | Infrastructure, Inference API | Maximum Inference API runtime instances for auto-scaling | | CDK_INFERENCE_API_MEMORY | Variable | No | `2048` | Infrastructure, Inference API | Memory (MB) for Inference API AgentCore Runtime (512, 1024, 2048, 4096, 8192) | | CDK_PRODUCTION | Variable | No | `true` | Frontend | Production environment flag (affects runtime config generation) | | CDK_PROJECT_PREFIX | Variable | Yes | `agentcore` | All | Prefix for all resource names (e.g., 'mycompany-agentcore') | +| CDK_RAG_CORS_ORIGINS | Variable | No | None | RAG Ingestion | Additional CORS origins for the RAG documents S3 bucket only (appended to global CORS origins) | | CDK_RETAIN_DATA_ON_DELETE | Variable | No | `false` | All | Retain data resources (DynamoDB, S3, Secrets) on stack deletion | | CDK_VPC_CIDR | Variable | No | `10.0.0.0/16` | Infrastructure, App API | CIDR block for VPC network | -| ENV_INFERENCE_API_CORS_ORIGINS | Variable | No | None | Inference API | Comma-separated CORS origins for runtime environment | +| ENV_INFERENCE_API_CORS_ORIGINS | Variable | No | None | Inference API | _(Deprecated — use CDK_INFERENCE_API_CORS_ORIGINS instead)_ | | ENV_INFERENCE_API_LOG_LEVEL | Variable | No | `INFO` | Inference API | Log level for runtime container (DEBUG, INFO, WARNING, ERROR) | -| SEED_ADMIN_JWT_ROLE | Variable | No | None | Bootstrap Data Seeding | JWT role that grants system admin access (e.g., `Admin`). Maps to the `system_admin` AppRole. | -| SEED_AUTH_BUTTON_COLOR | Variable | No | None | Bootstrap Data Seeding | Hex color for the auth provider login button (e.g., '#0078D4') | -| SEED_AUTH_CLIENT_ID | Variable | No | None | Bootstrap Data Seeding | OAuth client ID for the initial OIDC auth provider | -| SEED_AUTH_CLIENT_SECRET | Secret | No | None | Bootstrap Data Seeding | OAuth client secret for the initial OIDC auth provider | -| SEED_AUTH_DISPLAY_NAME | Variable | No | None | Bootstrap Data Seeding | Display name shown on the login page (e.g., 'Microsoft Entra ID') | -| SEED_AUTH_ISSUER_URL | Variable | No | None | Bootstrap Data Seeding | OIDC issuer URL for the auth provider (e.g., 'https://login.microsoftonline.com/TENANT/v2.0') | -| SEED_AUTH_PROVIDER_ID | Variable | No | None | Bootstrap Data Seeding | Slug identifier for the auth provider (e.g., 'entra-id') | +| SEED_ADMIN_JWT_ROLE | Variable | No | None | Bootstrap Data Seeding | _(Deprecated)_ Previously used for JWT role mapping. Admin access is now granted automatically via the Cognito first-boot flow. | diff --git a/.github/agents/devops-agent.agent.md b/.github/agents/devops-agent.agent.md deleted file mode 100644 index 3a9b011d..00000000 --- a/.github/agents/devops-agent.agent.md +++ /dev/null @@ -1,292 +0,0 @@ ---- -description: 'Agent to help with devops' -tools: ['runCommands', 'runTasks', 'edit', 'runNotebooks', 'search', 'new', 'extensions', 'usages', 'vscodeAPI', 'problems', 'changes', 'testFailure', 'openSimpleBrowser', 'fetch', 'githubRepo', 'todos', 'runSubagent', 'runTests'] ---- -# DevOps & Infrastructure Guide - -This document provides a concise overview of the CI/CD pipelines, Infrastructure as Code (IaC) architecture, and critical development rules for the AgentCore Public Stack. - -## 0. How to Jump In (Fast) - -When you’re debugging a deploy or adding a stack, start here in this order: - -1. **Workflow**: `.github/workflows/.yml` shows what runs in CI and when. -2. **Scripts**: `scripts/stack-/` contains the actual build/test/deploy logic (YAML should be a thin wrapper). -3. **CDK Stack**: `infrastructure/lib/-stack.ts` defines the AWS resources. - -Rule of thumb: if you’re looking for “what does this job do?”, it’s almost always in `scripts/`, not the workflow YAML. - -## 1. GitHub Actions Workflows - -The project uses a modular workflow architecture located in `.github/workflows/`. Each stack has its own dedicated workflow following a "Shell Scripts First" philosophy—logic resides in `scripts/`, not in YAML files. - -### Workflow Architecture -The project employs a **Modular, Job-Centric Architecture** designed for parallelism and clear failure isolation. All workflows follow these core principles: - -1. **Single Responsibility Jobs**: Each job performs exactly one major task (e.g., `build-docker`, `synth-cdk`, `test-python`). This makes debugging easier and allows for granular retries. -2. **Parallel Execution Tracks**: Independent processes run concurrently. For example, Docker images are built and pushed while the CDK code is simultaneously synthesized and diffed. -3. **Artifact-Driven Handover**: Jobs do not share state. Instead, they produce immutable artifacts (Docker image tarballs, synthesized CloudFormation templates) that are uploaded and then downloaded by downstream jobs. -4. **Script-Based Logic**: Workflows are thin wrappers around shell scripts. Every step calls a script in `scripts/stack-/`, ensuring that CI logic can be reproduced locally. - -### Workflow Invariants (Assume These Are True) - -These conventions are relied on throughout the repo and are the fastest way to reason about the pipelines: - -* **Job isolation is real**: each job starts on a fresh runner. If a downstream job needs something, it must come from an artifact (or from AWS). -* **Docker images move via artifacts**: images are exported as tar artifacts and loaded in later jobs (do not assume a prior job’s Docker cache exists). -* **CDK is “synth once”**: templates are synthesized to `cdk.out/` and deploy steps should reuse them when present. -* **YAML is the table of contents**: any non-trivial logic belongs in `scripts/`. - -### Available Workflows -* **`infrastructure.yml`**: Deploys the foundation (VPC, ALB, ECS Cluster). Runs first. -* **`app-api.yml`**: Deploys the main application API (Fargate). -* **`inference-api.yml`**: Deploys the inference runtime (Bedrock AgentCore Runtime). -* **`frontend.yml`**: Deploys the Angular application (S3 + CloudFront). -* **`gateway.yml`**: Deploys the Bedrock AgentCore Gateway and Lambda tools. - ---- - -## 2. CDK Stacks (Infrastructure) - -The infrastructure is defined in `infrastructure/lib/` and follows a strict layering model. - -| Stack Name | Class | Description | Dependencies | -| :--- | :--- | :--- | :--- | -| **Infrastructure** | `InfrastructureStack` | **Foundation Layer**. Creates VPC, ALB, ECS Cluster, and Security Groups. Exports resource IDs to SSM. | None | -| **App API** | `AppApiStack` | **Service Layer**. Fargate service for the application backend. Imports network resources via SSM. | Infrastructure | -| **Inference API** | `InferenceApiStack` | **Service Layer**. Bedrock AgentCore Runtime which hosts the inference API. | Infrastructure | -| **Gateway** | `GatewayStack` | **Integration Layer**. AWS Bedrock AgentCore Gateway and Lambda-based MCP tools. | Infrastructure | -| **Frontend** | `FrontendStack` | **Presentation Layer**. S3 Bucket for assets and CloudFront Distribution. | Infrastructure | - -### Key Concepts -* **SSM Parameter Store**: Used for all cross-stack references (e.g., `/${projectPrefix}/network/vpc-id`). -* **Context Configuration**: Project prefix, account IDs, and regions are passed via CDK Context (`cdk.json` or CLI flags), never hardcoded. - -### Deployment Order & Layering Contract - -* **Deploy order (default)**: Infrastructure → Gateway → App API → Inference API → Frontend. -* **Contract**: The Infrastructure stack is the foundation layer and exports shared IDs/attributes to SSM. All other stacks import those values from SSM. -* **No direct cross-stack coupling**: Prefer SSM parameters over CloudFormation cross-stack references to keep stacks independently deployable. - ---- - -## 3. Critical Development Rules - -Follow these rules when adding or modifying stacks to ensure stability and maintainability. - -### A. Configuration Management -* **NEVER Hardcode**: Account IDs, Regions, ARNs, or resource names. -* **Use SSM**: Store dynamic values (like Docker image tags or VPC IDs) in SSM Parameter Store. -* **Hierarchy**: Environment Variables > CDK Context > Defaults. - -#### Decision Tree: Where Should This Value Live? - -**Use `config.ts` + `cdk.context.json` when:** -- Value is needed **at CDK resource creation time** -- Examples: CORS origins (for S3 bucket CORS rules), CPU/memory (for ECS task definitions), max file size (for bucket policies) - -**Use ECS/Lambda `environment` block when:** -- Value is needed **at runtime by application code** -- Resource is in the **same stack** as the service -- Examples: DynamoDB table names, S3 bucket names, API URLs -- Application reads via `os.getenv("TABLE_NAME")` in Python - -**Use SSM Parameter Store when:** -- Value is needed **by another stack** (cross-stack reference) -- Examples: VPC ID (InfrastructureStack → AppApiStack), ALB ARN -- Consumer stack reads via `ssm.StringParameter.valueForStringParameter()` - - -### B. Scripting & Automation -* **Shell Scripts First**: GitHub Actions YAML should **ONLY** call scripts in `scripts/`. -* **Portability**: Scripts must run locally and in CI. Use `set -euo pipefail` for error handling. -* **Naming**: Scripts follow the pattern `scripts/stack-/.sh` (e.g., `scripts/stack-app-api/deploy.sh`). - -### C. Deployment Safety -* **Synth Once, Deploy Anywhere**: Synthesize CloudFormation templates in the `synth` job/step. The `deploy` step must use the generated `cdk.out/` artifacts, not re-synthesize. -* **Docker Artifacts**: Build Docker images once. Export them as `.tar` files to pass between CI jobs. Never rebuild the same image in a later stage. - -### D. Resource Referencing -* **Importing Resources**: When importing resources (VPC, Cluster, ALB) in a consumer stack, use `fromAttributes` methods (e.g., `Vpc.fromVpcAttributes`), not `fromLookup`. This avoids environment-dependent token issues. - -### E. When Adding/Modifying a Stack (Minimal Checklist) - -* **CDK**: Add/update `infrastructure/lib/.ts` and wire it in `infrastructure/bin/infrastructure.ts`. -* **SSM I/O**: Export shared values via SSM with the `/${projectPrefix}/...` convention; import via SSM in dependent stacks. -* **Scripts**: Add a `scripts/stack-/` folder and keep scripts single-purpose (install/build/synth/test/deploy as needed). -* **Workflow**: Add/update `.github/workflows/.yml` so it only calls scripts (no inline logic). -* **Context discipline**: Keep context flags consistent between `synth.sh` and `deploy.sh` for the same stack. - -### F. Adding New Configuration Properties - -When adding a new configuration value that flows from GitHub Actions through to CDK stacks, follow this 7-step pattern: - -#### Step 1: Add to TypeScript Config Interface - -**File**: `infrastructure/lib/config.ts` - -Add the property to `AppConfig` (or relevant sub-interface): - -```typescript -export interface AppConfig { - // ... existing properties - certificateArn?: string; // ACM certificate ARN for HTTPS on ALB -} -``` - -#### Step 2: Load from Environment/Context - -**File**: `infrastructure/lib/config.ts` (in `loadConfig` function) - -Add environment variable and context fallback: - -```typescript -const config: AppConfig = { - // ... existing properties - certificateArn: process.env.CDK_CERTIFICATE_ARN || scope.node.tryGetContext('certificateArn'), -}; -``` - -**Naming Convention**: Use `CDK_` prefix for CDK-specific config, `ENV_` for runtime container environment variables. - -#### Step 3: Use in CDK Stack - -**File**: `infrastructure/lib/-stack.ts` - -Access via the config object: - -```typescript -if (config.certificateArn) { - const certificate = acm.Certificate.fromCertificateArn( - this, - 'Certificate', - config.certificateArn - ); - // Use certificate... -} -``` - -#### Step 4: Add to load-env.sh - -**File**: `scripts/common/load-env.sh` - -Add three things: - -**a) Export the variable** (priority: env var > context file): -```bash -export CDK_CERTIFICATE_ARN="${CDK_CERTIFICATE_ARN:-$(get_json_value "certificateArn" "${CONTEXT_FILE}")}" -``` - -**b) Add to context parameters function** (if optional): -```bash -if [ -n "${CDK_CERTIFICATE_ARN:-}" ]; then - context_params="${context_params} --context certificateArn=\"${CDK_CERTIFICATE_ARN}\"" -fi -``` - -**c) Display in config output** (optional): -```bash -if [ -n "${CDK_CERTIFICATE_ARN:-}" ]; then - log_info " Certificate: ${CDK_CERTIFICATE_ARN:0:50}..." -fi -``` - -#### Step 5: Update Stack Scripts - -**Files**: `scripts/stack-/synth.sh` and `scripts/stack-/deploy.sh` - -Add context parameter to both scripts (must match exactly): - -```bash -cdk synth StackName \ - --context certificateArn="${CDK_CERTIFICATE_ARN}" \ - # ... other context params -``` - -```bash -cdk deploy StackName \ - --context certificateArn="${CDK_CERTIFICATE_ARN}" \ - # ... other context params -``` - -**Critical**: Context parameters must be **identical** in both `synth.sh` and `deploy.sh`. - -#### Step 6: Add to GitHub Workflow - -**File**: `.github/workflows/.yml` - -Add to the `env:` section at workflow level: - -- **Secrets** (sensitive data): Use `secrets.` -- **Variables** (non-sensitive config): Use `vars.` - -```yaml -env: - # CDK Configuration - from GitHub Variables - CDK_ALB_SUBDOMAIN: ${{ vars.CDK_ALB_SUBDOMAIN }} - - # CDK Secrets - from GitHub Secrets - CDK_CERTIFICATE_ARN: ${{ secrets.CDK_CERTIFICATE_ARN }} -``` - -**When to use Secrets vs Variables:** -- **Secrets**: API keys, passwords, certificate ARNs, AWS credentials -- **Variables**: Project names, regions, non-sensitive config - -#### Step 7: Set in GitHub Repository - -**For Variables** (Settings → Secrets and variables → Actions → Variables): -``` -CDK_ALB_SUBDOMAIN = api -``` - -**For Secrets** (Settings → Secrets and variables → Actions → Secrets): -``` -CDK_CERTIFICATE_ARN = arn:aws:acm:us-east-1:123456789012:certificate/... -``` - ---- - -### Example: Certificate ARN Flow - -Here's how `CDK_CERTIFICATE_ARN` flows through the system: - -``` -GitHub Secret (CDK_CERTIFICATE_ARN) - ↓ -.github/workflows/infrastructure.yml (env section) - ↓ -scripts/common/load-env.sh (export CDK_CERTIFICATE_ARN) - ↓ -scripts/stack-infrastructure/synth.sh (--context certificateArn) - ↓ -infrastructure/lib/config.ts (loadConfig function) - ↓ -infrastructure/lib/infrastructure-stack.ts (config.certificateArn) - ↓ -AWS CloudFormation Template (Certificate resource) -``` - -### Checklist for New Properties - -- [ ] Add to `config.ts` interface -- [ ] Load from env/context in `config.ts` `loadConfig()` -- [ ] Use in CDK stack TypeScript file -- [ ] Export in `load-env.sh` -- [ ] Add to context params in `load-env.sh` (if applicable) -- [ ] Update `synth.sh` with context flag -- [ ] Update `deploy.sh` with context flag (must match synth.sh) -- [ ] Add to workflow YAML `env:` section -- [ ] Set GitHub Secret or Variable -- [ ] Test locally with environment variable -- [ ] Test in CI/CD pipeline - ---- - -### G. Repo-Specific Gotchas (Read Before You Lose Time) - -* **Token-safe imports**: Use `Vpc.fromVpcAttributes()` (not `fromLookup()`) when importing VPC details that come from SSM tokens. -* **AgentCore CLI**: Use `aws bedrock-agentcore-control ...` for Gateway control-plane calls; gateway target lists are under `.items[]`. -* **SSM overwrite**: `aws ssm put-parameter --overwrite` cannot be used with `--tags` for an existing parameter. -* **Context parameter mismatch**: If `synth.sh` and `deploy.sh` have different context parameters, deployment may use wrong values or fail validation. -* **Empty context values**: CDK context doesn't support `--context key=""` for empty strings; omit the flag entirely for optional parameters. diff --git a/.github/docs/deploy/step-01-prerequisites.md b/.github/docs/deploy/step-01-prerequisites.md index 9c999894..82732873 100644 --- a/.github/docs/deploy/step-01-prerequisites.md +++ b/.github/docs/deploy/step-01-prerequisites.md @@ -20,22 +20,19 @@ Confirm you have access to the following before proceeding. Everything on this l - [ ] **GitHub account** with a fork of this repository - [ ] **Domain name** you control (e.g. `example.com`) with the ability to update nameservers -### Identity Provider +### Identity Provider (Optional) -You need an OIDC-compatible identity provider for user login. Any of these work: +Authentication is handled automatically via Amazon Cognito, which is deployed as part of the infrastructure stack. On first access, you'll create an admin account directly — no external identity provider is needed to get started. -- [ ] **Microsoft Entra ID** (Azure AD) -- [ ] **AWS Cognito** -- [ ] **Okta** -- [ ] **Any OIDC-compliant provider** +If you want federated login (e.g., corporate SSO), you can optionally configure an external OIDC provider later through the admin UI: -You'll need these values from your IdP: -- Client ID -- Client Secret -- Issuer URL (e.g. `https://login.microsoftonline.com/YOUR-TENANT-ID/v2.0`) +- **Microsoft Entra ID** (Azure AD) +- **Okta** +- **Google Workspace** +- **Any OIDC-compliant provider** > [!NOTE] -> Setting up the identity provider itself is outside the scope of this guide. You should have an existing IdP application configured before starting. +> No identity provider setup is required before deployment. Cognito handles initial authentication, and federated providers can be added post-deployment through the admin dashboard.
What if I don't have a domain yet? @@ -45,9 +42,9 @@ You can register a domain through [AWS Route 53](https://docs.aws.amazon.com/Rou
-What if I don't have an identity provider yet? +What if I want to add a federated identity provider later? -The quickest option is **AWS Cognito** — you can set up a user pool directly in the AWS Console. For Microsoft environments, **Entra ID** is a natural fit. The key requirement is that your IdP supports OIDC and can provide a client ID, client secret, and issuer URL. +After deployment, the first-boot flow creates your admin account using Cognito. Once logged in as admin, you can add federated identity providers (Entra ID, Okta, Google, etc.) through the admin dashboard. The system registers them in Cognito automatically — no redeployment needed.
diff --git a/.github/docs/deploy/step-03-github-config.md b/.github/docs/deploy/step-03-github-config.md index 137916be..165308eb 100644 --- a/.github/docs/deploy/step-03-github-config.md +++ b/.github/docs/deploy/step-03-github-config.md @@ -17,7 +17,7 @@ In this step you'll add all the configuration values from Step 2 (plus a few new - Admin access to your forked repository on GitHub - The values you noted in Step 2 (role ARN or access keys, domain, certificate ARNs) - Your AWS account ID (12-digit number) -- Your identity provider credentials (client ID, client secret, issuer URL) +- (Optional) Your identity provider credentials if you plan to add federated login later --- @@ -103,39 +103,11 @@ This prefix is prepended to all AWS resource names to avoid conflicts. Use somet --- -## 3c. Identity Provider Configuration +## 3c. Authentication -These values configure user login for your deployed application. Add them as a mix of **variables** and **secrets**. +Authentication is handled automatically by Amazon Cognito, which is deployed as part of the infrastructure stack. No identity provider configuration is needed before deployment. -### Variables - -| Variable Name | Example | Description | -|---------------|---------|-------------| -| `SEED_AUTH_PROVIDER_ID` | `entra-id` | Slug identifier for your IdP | -| `SEED_AUTH_DISPLAY_NAME` | `Microsoft Entra ID` | Display name shown on the login page | -| `SEED_AUTH_ISSUER_URL` | `https://login.microsoftonline.com/TENANT/v2.0` | OIDC issuer URL from your IdP | -| `SEED_AUTH_CLIENT_ID` | `your-client-id` | OAuth client ID from your IdP | - -### Secret - -| Secret Name | Description | -|-------------|-------------| -| `SEED_AUTH_CLIENT_SECRET` | OAuth client secret from your IdP | - -### Optional - -| Variable Name | Example | Description | -|---------------|---------|-------------| -| `SEED_ADMIN_JWT_ROLE` | `Admin` | JWT role claim that grants system admin access. Maps to the `system_admin` AppRole via the bootstrap seed script. Must match a role your IdP includes in tokens. | - -
-What is SEED_ADMIN_JWT_ROLE and do I need it? - -This is optional but recommended. When set, users whose JWT tokens include this role claim will be granted system admin access in the application. This lets you manage models, tools, roles, and other admin features. - -If you skip this, no users will have admin access initially. You can always set it later and re-run the Bootstrap Data Seeding workflow. - -
+After deployment, the first person to access the application will complete a first-boot setup to create the initial admin account with username, email, and password. The admin can then add federated identity providers (Entra ID, Okta, Google, etc.) through the admin dashboard.
Quick reference: what values did I note in Step 2? @@ -159,8 +131,6 @@ Before proceeding, confirm: - [ ] AWS credentials are saved as secrets (either `AWS_ROLE_ARN` or the access key pair) - [ ] All 8 required variables from section 3b are set -- [ ] All 4 identity provider variables from section 3c are set -- [ ] The `SEED_AUTH_CLIENT_SECRET` secret is saved --- diff --git a/.github/docs/deploy/step-04-deploy.md b/.github/docs/deploy/step-04-deploy.md index 5395f8a6..0b678a89 100644 --- a/.github/docs/deploy/step-04-deploy.md +++ b/.github/docs/deploy/step-04-deploy.md @@ -148,14 +148,15 @@ Deploys Lambda-based MCP tool endpoints behind API Gateway. These provide the ag 6. Seed Bootstrap Data Seeds your application with initial configuration: -- Auth provider (from your `SEED_AUTH_*` variables) - Default AI models and pricing - Application roles and permissions - Default tool configurations -- Admin role mapping (if `SEED_ADMIN_JWT_ROLE` is set) You can re-run this workflow later to update seed data. +> [!NOTE] +> Authentication is handled by Cognito's first-boot flow — no auth provider seeding is needed. The first person to access the application will create the admin account directly. +
--- diff --git a/.github/docs/deploy/step-05-verify.md b/.github/docs/deploy/step-05-verify.md index 7e4aa592..5f4ea981 100644 --- a/.github/docs/deploy/step-05-verify.md +++ b/.github/docs/deploy/step-05-verify.md @@ -19,28 +19,29 @@ All workflows have completed. Let's verify everything is working. Open your frontend URL in a browser (e.g. `https://app.example.com`). - [ ] The page loads without errors -- [ ] You see a login page with your identity provider's name (e.g. "Sign in with Microsoft Entra ID") +- [ ] You see a first-boot setup page (on fresh deployment) or a login page (if already set up) > [!NOTE] > CloudFront distributions can take a few minutes to fully propagate after the first deploy. If you get a 403 or "distribution not found" error, wait 5 minutes and try again. -### 2. Authentication Works +### 2. First-Boot Setup (Fresh Deployment) -Click the login button and authenticate with your identity provider. +On a fresh deployment, you'll see the first-boot setup page. Create your admin account. -- [ ] You're redirected to your IdP's login page -- [ ] After logging in, you're redirected back to the application +- [ ] Enter a username, email, and password +- [ ] Submit the form — you should be redirected to the login page +- [ ] Log in with your new credentials - [ ] You land on the chat interface
-Login redirects to an error page +First-boot setup fails Common causes: -- **Redirect URI mismatch:** Your IdP's app registration must include `https://app.example.com` (your frontend domain) as an allowed redirect URI -- **Client ID/secret incorrect:** Double-check `SEED_AUTH_CLIENT_ID` and `SEED_AUTH_CLIENT_SECRET` in GitHub settings -- **Issuer URL wrong:** Verify `SEED_AUTH_ISSUER_URL` matches your IdP's OIDC discovery endpoint +- **Password too weak:** Password must be at least 8 characters with uppercase, lowercase, number, and special character +- **ECS service not running:** Check that the App API service is healthy in the ECS console +- **DynamoDB permissions:** Verify the App API task role has write access to the DynamoDB tables -You can re-run the **Seed Bootstrap Data** workflow after fixing any of these values. +Check CloudWatch logs for the App API service for specific error details.
@@ -61,15 +62,15 @@ Check these in order: -### 4. Admin Access (Optional) +### 4. Admin Access -If you configured `SEED_ADMIN_JWT_ROLE` in Step 3, verify admin features: +The user who completed the first-boot setup is automatically the system admin. - [ ] Navigate to the admin section - [ ] You can see and manage models, tools, and roles > [!TIP] -> If admin features aren't visible, verify that your IdP token includes the role claim matching the value you set for `SEED_ADMIN_JWT_ROLE`. You may need to configure role/group claims in your IdP's app registration. +> To add federated identity providers (Entra ID, Okta, Google, etc.), use the admin dashboard's authentication settings. No redeployment is needed. --- diff --git a/.github/docs/deploy/troubleshooting.md b/.github/docs/deploy/troubleshooting.md index 74ad3641..36fd4327 100644 --- a/.github/docs/deploy/troubleshooting.md +++ b/.github/docs/deploy/troubleshooting.md @@ -149,29 +149,30 @@ ## Post-Deploy Issues
-Login page doesn't show the identity provider button +Login page doesn't load or shows an error -**Symptom:** The login page loads but there's no button to sign in. +**Symptom:** The login page doesn't load, or the first-boot setup page doesn't appear on a fresh deployment. -**Cause:** Bootstrap data seeding didn't run or the auth provider config is incorrect. +**Cause:** The App API may not be running, or the Cognito User Pool wasn't created properly. **Fix:** -1. Verify the **Seed Bootstrap Data** workflow (Step 7) completed successfully -2. Check that `SEED_AUTH_PROVIDER_ID`, `SEED_AUTH_DISPLAY_NAME`, `SEED_AUTH_ISSUER_URL`, `SEED_AUTH_CLIENT_ID`, and `SEED_AUTH_CLIENT_SECRET` are all set -3. Re-run the **Seed Bootstrap Data** workflow +1. Check that the App API ECS service is running and healthy +2. Verify the Infrastructure workflow completed successfully (Cognito User Pool is created there) +3. Check CloudWatch logs for the App API service for specific errors +4. If on a fresh deployment, ensure you see the first-boot setup page — if you see a login page instead, first-boot may have already been completed
Login succeeds but redirects to an error -**Symptom:** IdP login works, but the redirect back to the app fails. +**Symptom:** Login works, but the redirect back to the app fails. -**Cause:** Redirect URI mismatch in your IdP's app registration. +**Cause:** Redirect URI mismatch in the Cognito App Client configuration, or a federated identity provider misconfiguration. **Fix:** -1. In your IdP (Entra ID, Cognito, Okta, etc.), add your frontend domain as an allowed redirect URI -2. The redirect URI format is typically: `https://app.example.com` or `https://app.example.com/auth/callback` +1. Verify the Cognito App Client callback URLs include your frontend domain (e.g., `https://app.example.com/auth/callback`) +2. If using a federated provider, check that the provider's app registration includes the Cognito domain as an allowed redirect URI 3. Check your browser's developer console (Network tab) for the exact redirect URL being used
@@ -196,13 +197,13 @@ **Symptom:** You're logged in but don't see admin menu items. -**Cause:** Your JWT token doesn't include the expected admin role claim. +**Cause:** Your account doesn't have the system admin role. **Fix:** -1. Verify `SEED_ADMIN_JWT_ROLE` is set to a role that your IdP includes in tokens -2. In your IdP, check that role/group claims are configured in the token settings -3. Re-run the **Seed Bootstrap Data** workflow if you changed the value -4. Log out and log back in to get a fresh token +1. If this is a fresh deployment, the user who completed the first-boot setup should automatically have admin access +2. If using a federated identity provider, verify that the user's Cognito groups include the admin role +3. Log out and log back in to get a fresh token +4. Check the Users DynamoDB table to verify the user record has the `system_admin` role diff --git a/.github/workflows/app-api.yml b/.github/workflows/app-api.yml index b3df68ae..b62d6acf 100644 --- a/.github/workflows/app-api.yml +++ b/.github/workflows/app-api.yml @@ -255,6 +255,7 @@ jobs: name: Synthesize CDK runs-on: ubuntu-24.04-arm # Use ARM64-native runner for ARM64 Lambda builds needs: build-cdk + if: github.event_name != 'pull_request' # Select environment based on trigger # Manual: workflow_dispatch input @@ -270,6 +271,7 @@ jobs: CDK_AWS_REGION: ${{ vars.AWS_REGION }} CDK_PROJECT_PREFIX: ${{ vars.CDK_PROJECT_PREFIX }} CDK_DOMAIN_NAME: ${{ vars.CDK_DOMAIN_NAME }} + CDK_CORS_ORIGINS: ${{ vars.CDK_CORS_ORIGINS }} CDK_VPC_CIDR: ${{ vars.CDK_VPC_CIDR }} CDK_HOSTED_ZONE_DOMAIN: ${{ vars.CDK_HOSTED_ZONE_DOMAIN }} CDK_APP_API_ENABLED: ${{ vars.CDK_APP_API_ENABLED }} @@ -345,6 +347,7 @@ jobs: CDK_AWS_REGION: ${{ vars.AWS_REGION }} CDK_PROJECT_PREFIX: ${{ vars.CDK_PROJECT_PREFIX }} CDK_DOMAIN_NAME: ${{ vars.CDK_DOMAIN_NAME }} + CDK_CORS_ORIGINS: ${{ vars.CDK_CORS_ORIGINS }} CDK_AWS_ACCOUNT: ${{ vars.CDK_AWS_ACCOUNT }} AWS_ROLE_ARN: ${{ secrets.AWS_ROLE_ARN }} AWS_ACCESS_KEY_ID: ${{ secrets.AWS_ACCESS_KEY_ID }} @@ -468,6 +471,7 @@ jobs: CDK_AWS_REGION: ${{ vars.AWS_REGION }} CDK_PROJECT_PREFIX: ${{ vars.CDK_PROJECT_PREFIX }} CDK_DOMAIN_NAME: ${{ vars.CDK_DOMAIN_NAME }} + CDK_CORS_ORIGINS: ${{ vars.CDK_CORS_ORIGINS }} CDK_VPC_CIDR: ${{ vars.CDK_VPC_CIDR }} CDK_HOSTED_ZONE_DOMAIN: ${{ vars.CDK_HOSTED_ZONE_DOMAIN }} CDK_APP_API_ENABLED: ${{ vars.CDK_APP_API_ENABLED }} diff --git a/.github/workflows/bootstrap-data-seeding.yml b/.github/workflows/bootstrap-data-seeding.yml index 13a97795..16c213ec 100644 --- a/.github/workflows/bootstrap-data-seeding.yml +++ b/.github/workflows/bootstrap-data-seeding.yml @@ -52,18 +52,6 @@ jobs: AWS_ACCESS_KEY_ID: ${{ secrets.AWS_ACCESS_KEY_ID }} AWS_SECRET_ACCESS_KEY: ${{ secrets.AWS_SECRET_ACCESS_KEY }} - # Auth provider config — non-sensitive from variables - SEED_AUTH_PROVIDER_ID: ${{ vars.SEED_AUTH_PROVIDER_ID }} - SEED_AUTH_DISPLAY_NAME: ${{ vars.SEED_AUTH_DISPLAY_NAME }} - SEED_AUTH_ISSUER_URL: ${{ vars.SEED_AUTH_ISSUER_URL }} - SEED_AUTH_BUTTON_COLOR: ${{ vars.SEED_AUTH_BUTTON_COLOR }} - - # Auth provider config — client ID is a public identifier (non-sensitive) - SEED_AUTH_CLIENT_ID: ${{ vars.SEED_AUTH_CLIENT_ID }} - SEED_AUTH_CLIENT_SECRET: ${{ secrets.SEED_AUTH_CLIENT_SECRET }} - - # System admin JWT role mapping - SEED_ADMIN_JWT_ROLE: ${{ vars.SEED_ADMIN_JWT_ROLE }} steps: - name: Checkout code diff --git a/.github/workflows/frontend.yml b/.github/workflows/frontend.yml index 5632498d..3f1dfee4 100644 --- a/.github/workflows/frontend.yml +++ b/.github/workflows/frontend.yml @@ -227,6 +227,7 @@ jobs: CDK_PROJECT_PREFIX: ${{ vars.CDK_PROJECT_PREFIX }} CDK_PRODUCTION: ${{ vars.CDK_PRODUCTION }} CDK_DOMAIN_NAME: ${{ vars.CDK_DOMAIN_NAME }} + CDK_CORS_ORIGINS: ${{ vars.CDK_CORS_ORIGINS }} CDK_FRONTEND_ENABLED: ${{ vars.CDK_FRONTEND_ENABLED }} CDK_FRONTEND_CLOUDFRONT_PRICE_CLASS: ${{ vars.CDK_FRONTEND_CLOUDFRONT_PRICE_CLASS }} CDK_RETAIN_DATA_ON_DELETE: ${{ vars.CDK_RETAIN_DATA_ON_DELETE }} @@ -355,6 +356,7 @@ jobs: CDK_PROJECT_PREFIX: ${{ vars.CDK_PROJECT_PREFIX }} CDK_PRODUCTION: ${{ vars.CDK_PRODUCTION }} CDK_DOMAIN_NAME: ${{ vars.CDK_DOMAIN_NAME }} + CDK_CORS_ORIGINS: ${{ vars.CDK_CORS_ORIGINS }} CDK_FRONTEND_ENABLED: ${{ vars.CDK_FRONTEND_ENABLED }} CDK_FRONTEND_CLOUDFRONT_PRICE_CLASS: ${{ vars.CDK_FRONTEND_CLOUDFRONT_PRICE_CLASS }} CDK_RETAIN_DATA_ON_DELETE: ${{ vars.CDK_RETAIN_DATA_ON_DELETE }} diff --git a/.github/workflows/gateway.yml b/.github/workflows/gateway.yml index b5ee3d48..35a8cc4d 100644 --- a/.github/workflows/gateway.yml +++ b/.github/workflows/gateway.yml @@ -167,6 +167,8 @@ jobs: # Environment-scoped configuration CDK_AWS_REGION: ${{ vars.AWS_REGION }} CDK_PROJECT_PREFIX: ${{ vars.CDK_PROJECT_PREFIX }} + CDK_DOMAIN_NAME: ${{ vars.CDK_DOMAIN_NAME }} + CDK_CORS_ORIGINS: ${{ vars.CDK_CORS_ORIGINS }} CDK_RETAIN_DATA_ON_DELETE: ${{ vars.CDK_RETAIN_DATA_ON_DELETE }} CDK_GATEWAY_ENABLED: ${{ vars.CDK_GATEWAY_ENABLED }} CDK_GATEWAY_API_TYPE: ${{ vars.CDK_GATEWAY_API_TYPE }} @@ -228,6 +230,8 @@ jobs: # Environment-scoped configuration CDK_AWS_REGION: ${{ vars.AWS_REGION }} CDK_PROJECT_PREFIX: ${{ vars.CDK_PROJECT_PREFIX }} + CDK_DOMAIN_NAME: ${{ vars.CDK_DOMAIN_NAME }} + CDK_CORS_ORIGINS: ${{ vars.CDK_CORS_ORIGINS }} CDK_RETAIN_DATA_ON_DELETE: ${{ vars.CDK_RETAIN_DATA_ON_DELETE }} CDK_GATEWAY_ENABLED: ${{ vars.CDK_GATEWAY_ENABLED }} CDK_GATEWAY_API_TYPE: ${{ vars.CDK_GATEWAY_API_TYPE }} @@ -299,6 +303,8 @@ jobs: # Environment-scoped configuration CDK_AWS_REGION: ${{ vars.AWS_REGION }} CDK_PROJECT_PREFIX: ${{ vars.CDK_PROJECT_PREFIX }} + CDK_DOMAIN_NAME: ${{ vars.CDK_DOMAIN_NAME }} + CDK_CORS_ORIGINS: ${{ vars.CDK_CORS_ORIGINS }} CDK_RETAIN_DATA_ON_DELETE: ${{ vars.CDK_RETAIN_DATA_ON_DELETE }} CDK_GATEWAY_ENABLED: ${{ vars.CDK_GATEWAY_ENABLED }} CDK_GATEWAY_API_TYPE: ${{ vars.CDK_GATEWAY_API_TYPE }} diff --git a/.github/workflows/inference-api.yml b/.github/workflows/inference-api.yml index 97e3e9d1..dfd6b9aa 100644 --- a/.github/workflows/inference-api.yml +++ b/.github/workflows/inference-api.yml @@ -285,6 +285,8 @@ jobs: # Environment-scoped configuration CDK_AWS_REGION: ${{ vars.AWS_REGION }} CDK_PROJECT_PREFIX: ${{ vars.CDK_PROJECT_PREFIX }} + CDK_DOMAIN_NAME: ${{ vars.CDK_DOMAIN_NAME }} + CDK_CORS_ORIGINS: ${{ vars.CDK_CORS_ORIGINS }} CDK_RETAIN_DATA_ON_DELETE: ${{ vars.CDK_RETAIN_DATA_ON_DELETE }} CDK_INFERENCE_API_ENABLED: ${{ vars.CDK_INFERENCE_API_ENABLED }} CDK_INFERENCE_API_CPU: ${{ vars.CDK_INFERENCE_API_CPU }} @@ -292,7 +294,7 @@ jobs: CDK_INFERENCE_API_DESIRED_COUNT: ${{ vars.CDK_INFERENCE_API_DESIRED_COUNT }} CDK_INFERENCE_API_MAX_CAPACITY: ${{ vars.CDK_INFERENCE_API_MAX_CAPACITY }} ENV_INFERENCE_API_LOG_LEVEL: ${{ vars.ENV_INFERENCE_API_LOG_LEVEL }} - ENV_INFERENCE_API_CORS_ORIGINS: ${{ vars.ENV_INFERENCE_API_CORS_ORIGINS }} + CDK_INFERENCE_API_CORS_ORIGINS: ${{ vars.CDK_INFERENCE_API_CORS_ORIGINS }} CDK_AWS_ACCOUNT: ${{ vars.CDK_AWS_ACCOUNT }} CDK_APP_VERSION: ${{ needs.build-docker.outputs.app-version }} AWS_ROLE_ARN: ${{ secrets.AWS_ROLE_ARN }} @@ -352,6 +354,8 @@ jobs: # Environment-scoped configuration CDK_AWS_REGION: ${{ vars.AWS_REGION }} CDK_PROJECT_PREFIX: ${{ vars.CDK_PROJECT_PREFIX }} + CDK_DOMAIN_NAME: ${{ vars.CDK_DOMAIN_NAME }} + CDK_CORS_ORIGINS: ${{ vars.CDK_CORS_ORIGINS }} CDK_AWS_ACCOUNT: ${{ vars.CDK_AWS_ACCOUNT }} AWS_ROLE_ARN: ${{ secrets.AWS_ROLE_ARN }} AWS_ACCESS_KEY_ID: ${{ secrets.AWS_ACCESS_KEY_ID }} @@ -477,6 +481,8 @@ jobs: # Environment-scoped configuration CDK_AWS_REGION: ${{ vars.AWS_REGION }} CDK_PROJECT_PREFIX: ${{ vars.CDK_PROJECT_PREFIX }} + CDK_DOMAIN_NAME: ${{ vars.CDK_DOMAIN_NAME }} + CDK_CORS_ORIGINS: ${{ vars.CDK_CORS_ORIGINS }} CDK_RETAIN_DATA_ON_DELETE: ${{ vars.CDK_RETAIN_DATA_ON_DELETE }} CDK_INFERENCE_API_ENABLED: ${{ vars.CDK_INFERENCE_API_ENABLED }} CDK_INFERENCE_API_CPU: ${{ vars.CDK_INFERENCE_API_CPU }} @@ -484,7 +490,7 @@ jobs: CDK_INFERENCE_API_DESIRED_COUNT: ${{ vars.CDK_INFERENCE_API_DESIRED_COUNT }} CDK_INFERENCE_API_MAX_CAPACITY: ${{ vars.CDK_INFERENCE_API_MAX_CAPACITY }} ENV_INFERENCE_API_LOG_LEVEL: ${{ vars.ENV_INFERENCE_API_LOG_LEVEL }} - ENV_INFERENCE_API_CORS_ORIGINS: ${{ vars.ENV_INFERENCE_API_CORS_ORIGINS }} + CDK_INFERENCE_API_CORS_ORIGINS: ${{ vars.CDK_INFERENCE_API_CORS_ORIGINS }} CDK_AWS_ACCOUNT: ${{ vars.CDK_AWS_ACCOUNT }} AWS_ROLE_ARN: ${{ secrets.AWS_ROLE_ARN }} AWS_ACCESS_KEY_ID: ${{ secrets.AWS_ACCESS_KEY_ID }} diff --git a/.github/workflows/infrastructure.yml b/.github/workflows/infrastructure.yml index 6191ee16..bb10e65e 100644 --- a/.github/workflows/infrastructure.yml +++ b/.github/workflows/infrastructure.yml @@ -155,6 +155,7 @@ jobs: CDK_AWS_REGION: ${{ vars.AWS_REGION }} CDK_PROJECT_PREFIX: ${{ vars.CDK_PROJECT_PREFIX }} CDK_DOMAIN_NAME: ${{ vars.CDK_DOMAIN_NAME }} + CDK_CORS_ORIGINS: ${{ vars.CDK_CORS_ORIGINS }} CDK_VPC_CIDR: ${{ vars.CDK_VPC_CIDR }} CDK_HOSTED_ZONE_DOMAIN: ${{ vars.CDK_HOSTED_ZONE_DOMAIN }} CDK_ALB_SUBDOMAIN: ${{ vars.CDK_ALB_SUBDOMAIN }} @@ -162,6 +163,7 @@ jobs: CDK_RETAIN_DATA_ON_DELETE: ${{ vars.CDK_RETAIN_DATA_ON_DELETE }} CDK_FILE_UPLOAD_CORS_ORIGINS: ${{ vars.CDK_FILE_UPLOAD_CORS_ORIGINS }} CDK_FILE_UPLOAD_MAX_SIZE_MB: ${{ vars.CDK_FILE_UPLOAD_MAX_SIZE_MB }} + CDK_COGNITO_DOMAIN_PREFIX: ${{ vars.CDK_COGNITO_DOMAIN_PREFIX }} CDK_AWS_ACCOUNT: ${{ vars.CDK_AWS_ACCOUNT }} AWS_ROLE_ARN: ${{ secrets.AWS_ROLE_ARN }} AWS_ACCESS_KEY_ID: ${{ secrets.AWS_ACCESS_KEY_ID }} @@ -228,6 +230,7 @@ jobs: CDK_AWS_REGION: ${{ vars.AWS_REGION }} CDK_PROJECT_PREFIX: ${{ vars.CDK_PROJECT_PREFIX }} CDK_DOMAIN_NAME: ${{ vars.CDK_DOMAIN_NAME }} + CDK_CORS_ORIGINS: ${{ vars.CDK_CORS_ORIGINS }} CDK_VPC_CIDR: ${{ vars.CDK_VPC_CIDR }} CDK_HOSTED_ZONE_DOMAIN: ${{ vars.CDK_HOSTED_ZONE_DOMAIN }} CDK_ALB_SUBDOMAIN: ${{ vars.CDK_ALB_SUBDOMAIN }} @@ -235,6 +238,7 @@ jobs: CDK_RETAIN_DATA_ON_DELETE: ${{ vars.CDK_RETAIN_DATA_ON_DELETE }} CDK_FILE_UPLOAD_CORS_ORIGINS: ${{ vars.CDK_FILE_UPLOAD_CORS_ORIGINS }} CDK_FILE_UPLOAD_MAX_SIZE_MB: ${{ vars.CDK_FILE_UPLOAD_MAX_SIZE_MB }} + CDK_COGNITO_DOMAIN_PREFIX: ${{ vars.CDK_COGNITO_DOMAIN_PREFIX }} CDK_AWS_ACCOUNT: ${{ vars.CDK_AWS_ACCOUNT }} AWS_ROLE_ARN: ${{ secrets.AWS_ROLE_ARN }} AWS_ACCESS_KEY_ID: ${{ secrets.AWS_ACCESS_KEY_ID }} @@ -305,6 +309,7 @@ jobs: CDK_AWS_REGION: ${{ vars.AWS_REGION }} CDK_PROJECT_PREFIX: ${{ vars.CDK_PROJECT_PREFIX }} CDK_DOMAIN_NAME: ${{ vars.CDK_DOMAIN_NAME }} + CDK_CORS_ORIGINS: ${{ vars.CDK_CORS_ORIGINS }} CDK_VPC_CIDR: ${{ vars.CDK_VPC_CIDR }} CDK_HOSTED_ZONE_DOMAIN: ${{ vars.CDK_HOSTED_ZONE_DOMAIN }} CDK_ALB_SUBDOMAIN: ${{ vars.CDK_ALB_SUBDOMAIN }} @@ -320,6 +325,7 @@ jobs: CDK_INFERENCE_API_MAX_CAPACITY: ${{ vars.CDK_INFERENCE_API_MAX_CAPACITY }} CDK_INFERENCE_API_CPU: ${{ vars.CDK_INFERENCE_API_CPU }} CDK_INFERENCE_API_MEMORY: ${{ vars.CDK_INFERENCE_API_MEMORY }} + CDK_COGNITO_DOMAIN_PREFIX: ${{ vars.CDK_COGNITO_DOMAIN_PREFIX }} CDK_AWS_ACCOUNT: ${{ vars.CDK_AWS_ACCOUNT }} AWS_ROLE_ARN: ${{ secrets.AWS_ROLE_ARN }} AWS_ACCESS_KEY_ID: ${{ secrets.AWS_ACCESS_KEY_ID }} diff --git a/.github/workflows/nightly-deploy-pipeline.yml b/.github/workflows/nightly-deploy-pipeline.yml index ade4a818..8e169568 100644 --- a/.github/workflows/nightly-deploy-pipeline.yml +++ b/.github/workflows/nightly-deploy-pipeline.yml @@ -103,10 +103,12 @@ jobs: CDK_PROJECT_PREFIX: ${{ inputs.project-prefix }} CDK_VPC_CIDR: ${{ vars.CDK_VPC_CIDR }} CDK_DOMAIN_NAME: "" + CDK_CORS_ORIGINS: ${{ vars.CDK_CORS_ORIGINS }} CDK_HOSTED_ZONE_DOMAIN: ${{ vars.CDK_HOSTED_ZONE_DOMAIN }} CDK_ALB_SUBDOMAIN: ${{ inputs.alb-subdomain }} CDK_CERTIFICATE_ARN: ${{ vars.CDK_CERTIFICATE_ARN }} CDK_RETAIN_DATA_ON_DELETE: false + CDK_FILE_UPLOAD_CORS_ORIGINS: ${{ vars.CDK_FILE_UPLOAD_CORS_ORIGINS }} CDK_AWS_ACCOUNT: ${{ vars.CDK_AWS_ACCOUNT }} AWS_ROLE_ARN: ${{ secrets.AWS_ROLE_ARN }} AWS_ACCESS_KEY_ID: ${{ secrets.AWS_ACCESS_KEY_ID }} @@ -417,6 +419,7 @@ jobs: CDK_PRODUCTION: false CDK_FRONTEND_ENABLED: true CDK_RETAIN_DATA_ON_DELETE: false + CDK_CORS_ORIGINS: ${{ vars.CDK_CORS_ORIGINS }} CDK_AWS_ACCOUNT: ${{ vars.CDK_AWS_ACCOUNT }} CDK_VPC_CIDR: ${{ vars.CDK_VPC_CIDR }} CDK_DOMAIN_NAME: "" diff --git a/.github/workflows/nightly.yml b/.github/workflows/nightly.yml index 4bd0eb29..c723e413 100644 --- a/.github/workflows/nightly.yml +++ b/.github/workflows/nightly.yml @@ -535,7 +535,7 @@ jobs: run: docker build -f backend/Dockerfile.rag-ingestion -t rag-ingestion:scan . - name: Trivy scan app-api - uses: aquasecurity/trivy-action@18f2510ee396bbf400402947e7f3b01b8e110e21 # v0.28.0 + uses: aquasecurity/trivy-action@57a97c7e7821a5776cebc9bb87c984fa69cba8f1 # v0.35.0 with: image-ref: 'app-api:scan' format: 'table' @@ -544,7 +544,7 @@ jobs: output: trivy-app-api.txt - name: Trivy scan inference-api - uses: aquasecurity/trivy-action@18f2510ee396bbf400402947e7f3b01b8e110e21 # v0.28.0 + uses: aquasecurity/trivy-action@57a97c7e7821a5776cebc9bb87c984fa69cba8f1 # v0.35.0 with: image-ref: 'inference-api:scan' format: 'table' @@ -553,7 +553,7 @@ jobs: output: trivy-inference-api.txt - name: Trivy scan rag-ingestion - uses: aquasecurity/trivy-action@18f2510ee396bbf400402947e7f3b01b8e110e21 # v0.28.0 + uses: aquasecurity/trivy-action@57a97c7e7821a5776cebc9bb87c984fa69cba8f1 # v0.35.0 with: image-ref: 'rag-ingestion:scan' format: 'table' diff --git a/.kiro/specs/agent-core-tests/.config.kiro b/.kiro/specs/agent-core-tests/.config.kiro deleted file mode 100644 index 2d7de462..00000000 --- a/.kiro/specs/agent-core-tests/.config.kiro +++ /dev/null @@ -1 +0,0 @@ -{"specId": "83305357-3aa6-4fff-b924-5b087888786d", "workflowType": "requirements-first", "specType": "feature"} \ No newline at end of file diff --git a/.kiro/specs/agent-core-tests/design.md b/.kiro/specs/agent-core-tests/design.md deleted file mode 100644 index 98ea56d8..00000000 --- a/.kiro/specs/agent-core-tests/design.md +++ /dev/null @@ -1,318 +0,0 @@ -# Design Document: Agent Core Tests - -## Overview - -This design specifies a comprehensive test suite for the Agent Core module (`backend/src/agents/main_agent/`), covering 25 requirements across 7 submodules: core, tools, multimodal, streaming, session, integrations, and utils. The test suite uses pytest with pytest-asyncio for async tests and Hypothesis for property-based testing. - -The test files mirror the source module structure under `backend/tests/agents/main_agent/`, with a dedicated `property/` subdirectory for Hypothesis-based property tests. All external dependencies (Strands Agents, boto3, AWS services, MCP clients) are mocked to ensure tests are fast, deterministic, and runnable without cloud credentials. - -## Architecture - -### Test File Organization - -``` -backend/tests/agents/main_agent/ -├── conftest.py # Shared fixtures for all main_agent tests -├── core/ -│ ├── test_model_config.py # Req 1: ModelConfig, Req 2: RetryConfig -│ ├── test_system_prompt_builder.py # Req 3: SystemPromptBuilder -│ └── test_agent_factory.py # Req 4: AgentFactory -├── tools/ -│ ├── test_tool_registry.py # Req 5: ToolRegistry -│ ├── test_tool_filter.py # Req 6: ToolFilter -│ └── test_tool_catalog.py # Req 7: ToolCatalogService -├── multimodal/ -│ ├── test_image_handler.py # Req 8: ImageHandler -│ ├── test_document_handler.py # Req 9: DocumentHandler -│ ├── test_file_sanitizer.py # Req 10: FileSanitizer -│ └── test_prompt_builder.py # Req 11: PromptBuilder -├── streaming/ -│ ├── test_event_formatter.py # Req 12: StreamEventFormatter -│ ├── test_tool_result_processor.py # Req 13: ToolResultProcessor -│ └── test_stream_processor.py # Req 23: Stream processor event handlers -├── session/ -│ ├── test_preview_session_manager.py # Req 14: PreviewSessionManager -│ ├── test_session_factory.py # Req 15: SessionFactory -│ ├── test_compaction_models.py # Req 16: CompactionState/Config -│ ├── test_memory_config.py # Req 17: MemoryStorageConfig -│ └── test_stop_hook.py # Req 18: StopHook -├── integrations/ -│ ├── test_oauth_auth.py # Req 19: OAuthBearerAuth, CompositeAuth -│ ├── test_gateway_auth.py # Req 20: SigV4HTTPXAuth -│ ├── test_gateway_mcp_client.py # Req 24: FilteredMCPClient -│ └── test_external_mcp_client.py # Req 25: External MCP utilities -├── utils/ -│ ├── test_timezone.py # Req 21: get_current_date_pacific -│ └── test_global_state.py # Req 22: Deprecated global state -└── property/ - ├── conftest.py # Shared Hypothesis strategies - └── test_pbt_agent_core.py # All property-based tests (8 properties) -``` - -### Mocking Strategy - -All tests isolate the unit under test by mocking external dependencies: - -| Dependency | Mock Approach | -|---|---| -| `strands.Agent`, `BedrockModel`, `OpenAIModel`, `GeminiModel` | `unittest.mock.patch` on constructors | -| `strands.models.CacheConfig` | `MagicMock` | -| `botocore.config.Config` | `MagicMock` | -| `boto3.Session` | `unittest.mock.patch` returning mock credentials/region | -| `bedrock_agentcore.memory.*` | `unittest.mock.patch` on imports; toggle `AGENTCORE_MEMORY_AVAILABLE` | -| `os.environ` | `monkeypatch.setenv` / `monkeypatch.delenv` via pytest fixtures | -| `httpx.Request` / `httpx.Response` | Direct construction with test data | -| `MCPClient`, `streamablehttp_client` | `unittest.mock.patch` | -| `strands.types.session.SessionMessage` | Direct construction or `MagicMock` | -| File I/O (ToolResultProcessor) | `unittest.mock.patch` on `open`, `os.makedirs` | - -### Fixture Design - -Shared fixtures in `conftest.py`: - -- `tool_registry` — pre-populated `ToolRegistry` with 3-5 mock tools -- `tool_filter` — `ToolFilter` wrapping the `tool_registry` fixture -- `model_config` — default `ModelConfig` instance -- `retry_config` — default `RetryConfig` instance -- `preview_session` — `PreviewSessionManager` with a test session ID -- `mock_agent` — `MagicMock` with `.messages` attribute for session hook tests -- `sample_files` — list of mock `FileContent` objects (image, document, unsupported) - -Hypothesis strategies in `property/conftest.py`: - -- `st_model_config` — generates valid `ModelConfig` instances with random providers, temperatures, model IDs -- `st_retry_config` — generates `RetryConfig` with constrained delay values (`initial <= max`) -- `st_compaction_state` — generates `CompactionState` with random checkpoint, summary, token counts -- `st_filename` — generates arbitrary strings for sanitizer testing -- `st_tool_ids` — generates lists of tool IDs mixing local, gateway, external, and unknown -- `st_sse_event_dict` — generates valid event dictionaries with string keys and JSON-serializable values - -## Components and Interfaces - -### Unit Under Test → Test File Mapping - -| Component | Source File | Test File | Key Methods Tested | -|---|---|---|---| -| `ModelConfig` | `core/model_config.py` | `core/test_model_config.py` | `get_provider`, `to_bedrock_config`, `to_openai_config`, `to_gemini_config`, `to_dict`, `from_params` | -| `RetryConfig` | `core/model_config.py` | `core/test_model_config.py` | `__init__`, `from_env` | -| `SystemPromptBuilder` | `core/system_prompt_builder.py` | `core/test_system_prompt_builder.py` | `build`, `from_user_prompt` | -| `AgentFactory` | `core/agent_factory.py` | `core/test_agent_factory.py` | `create_agent` (Bedrock/OpenAI/Gemini paths) | -| `ToolRegistry` | `tools/tool_registry.py` | `tools/test_tool_registry.py` | `register_tool`, `get_tool`, `has_tool`, `register_module_tools`, `get_all_tool_ids`, `get_tool_count` | -| `ToolFilter` | `tools/tool_filter.py` | `tools/test_tool_filter.py` | `filter_tools`, `filter_tools_extended`, `set_external_mcp_tools`, `get_statistics` | -| `ToolCatalogService` | `tools/tool_catalog.py` | `tools/test_tool_catalog.py` | `get_all_tools`, `get_tool`, `get_tools_by_category`, `add_gateway_tool`, `ToolMetadata.to_dict` | -| `ImageHandler` | `multimodal/image_handler.py` | `multimodal/test_image_handler.py` | `is_image`, `get_image_format`, `create_content_block` | -| `DocumentHandler` | `multimodal/document_handler.py` | `multimodal/test_document_handler.py` | `is_document`, `get_document_format`, `create_content_block` | -| `FileSanitizer` | `multimodal/file_sanitizer.py` | `multimodal/test_file_sanitizer.py` | `sanitize_filename` | -| `PromptBuilder` | `multimodal/prompt_builder.py` | `multimodal/test_prompt_builder.py` | `build_prompt`, `get_content_type_summary` | -| `StreamEventFormatter` | `streaming/event_formatter.py` | `streaming/test_event_formatter.py` | `format_sse_event`, `create_*_event`, `extract_final_result_data` | -| `ToolResultProcessor` | `streaming/tool_result_processor.py` | `streaming/test_tool_result_processor.py` | `process_tool_result`, `_extract_basic_content`, `_process_json_content` | -| Stream processor functions | `streaming/stream_processor.py` | `streaming/test_stream_processor.py` | `_handle_lifecycle_events`, `_handle_content_block_events`, `_handle_tool_events`, `_handle_reasoning_events`, `_handle_citation_events`, `_handle_metadata_events`, `_serialize_object` | -| `PreviewSessionManager` | `session/preview_session_manager.py` | `session/test_preview_session_manager.py` | `create_message`, `read_session`, `clear_session`, `message_count`, `_initialize_agent` | -| `SessionFactory` | `session/session_factory.py` | `session/test_session_factory.py` | `create_session_manager`, `is_cloud_mode` | -| `CompactionState` | `session/compaction_models.py` | `session/test_compaction_models.py` | `to_dict`, `from_dict` | -| `CompactionConfig` | `session/compaction_models.py` | `session/test_compaction_models.py` | `from_env` | -| `MemoryStorageConfig` | `session/memory_config.py` | `session/test_memory_config.py` | `load_memory_config`, `is_cloud_mode` | -| `StopHook` | `session/hooks/stop.py` | `session/test_stop_hook.py` | `check_cancelled` | -| `OAuthBearerAuth` | `integrations/oauth_auth.py` | `integrations/test_oauth_auth.py` | `auth_flow` | -| `CompositeAuth` | `integrations/oauth_auth.py` | `integrations/test_oauth_auth.py` | `auth_flow` | -| `SigV4HTTPXAuth` | `integrations/gateway_auth.py` | `integrations/test_gateway_auth.py` | `auth_flow`, `get_gateway_region_from_url` | -| `FilteredMCPClient` | `integrations/gateway_mcp_client.py` | `integrations/test_gateway_mcp_client.py` | `__init__`, `get_gateway_client_if_enabled` | -| External MCP utils | `integrations/external_mcp_client.py` | `integrations/test_external_mcp_client.py` | `extract_region_from_url`, `detect_aws_service_from_url` | -| `get_current_date_pacific` | `utils/timezone.py` | `utils/test_timezone.py` | `get_current_date_pacific` | -| Global state | `utils/global_state.py` | `utils/test_global_state.py` | `set_global_stream_processor`, `get_global_stream_processor` | - -## Data Models - -### Key Dataclasses Under Test - -```python -# ModelConfig (core/model_config.py) -@dataclass -class ModelConfig: - model_id: str # Provider-specific model identifier - temperature: float # 0.0 - 1.0 - caching_enabled: bool # Bedrock prompt caching - provider: ModelProvider # BEDROCK | OPENAI | GEMINI - max_tokens: Optional[int] - retry_config: Optional[RetryConfig] - -# RetryConfig (core/model_config.py) -@dataclass -class RetryConfig: - boto_max_attempts: int # Default: 3 - boto_retry_mode: str # "legacy" | "standard" | "adaptive" - connect_timeout: int # Default: 5 - read_timeout: int # Default: 120 - sdk_max_attempts: int # Default: 4 - sdk_initial_delay: float # Default: 2.0 - sdk_max_delay: float # Default: 16.0 - -# CompactionState (session/compaction_models.py) -@dataclass -class CompactionState: - checkpoint: int # Message index to load from - summary: Optional[str] # Summary for skipped messages - last_input_tokens: int # Input tokens from last turn - updated_at: Optional[str] # ISO timestamp - -# CompactionConfig (session/compaction_models.py) -@dataclass -class CompactionConfig: - enabled: bool # Default: False - token_threshold: int # Default: 100_000 - protected_turns: int # Default: 2 - max_tool_content_length: int # Default: 500 - -# ToolMetadata (tools/tool_catalog.py) -@dataclass -class ToolMetadata: - tool_id: str - name: str - description: str - category: ToolCategory - is_gateway_tool: bool - requires_oauth_provider: Optional[str] - icon: Optional[str] - -# MemoryStorageConfig (session/memory_config.py) -@dataclass -class MemoryStorageConfig: - memory_id: str - region: str -``` - -### SSE Event Format - -``` -data: {"type": "", ...payload}\n\n -``` - -All SSE events produced by `StreamEventFormatter` follow this wire format. The JSON payload always contains a `"type"` key. The `format_sse_event` method wraps any dict into this format. - -### ProcessedEvent Format - -```python -{"type": str, "data": dict} -``` - -All events produced by stream processor handler functions (`_handle_*`) follow this structure, enforced by the `_create_event` helper. - -## Correctness Properties - -*A property is a characteristic or behavior that should hold true across all valid executions of a system — essentially, a formal statement about what the system should do. Properties serve as the bridge between human-readable specifications and machine-verifiable correctness guarantees.* - -### Property 1: ModelConfig round-trip - -*For any* valid `ModelConfig` instance (with any provider, temperature, caching_enabled, model_id, and max_tokens), converting to a dictionary via `to_dict()` and then reconstructing via `from_params()` using those dictionary values should produce a `ModelConfig` whose `to_dict()` output is identical to the original's `to_dict()` output. - -**Validates: Requirements 1.13** - -### Property 2: RetryConfig delay invariant - -*For any* `RetryConfig` instance constructed with valid parameters, `sdk_initial_delay` should be less than or equal to `sdk_max_delay`. - -**Validates: Requirements 2.4** - -### Property 3: ToolRegistry count invariant - -*For any* sequence of `register_tool(tool_id, tool_obj)` calls on a fresh `ToolRegistry`, `get_tool_count()` should equal the number of distinct `tool_id` values in the sequence. - -**Validates: Requirements 5.9** - -### Property 4: ToolFilter partition invariant - -*For any* list of `enabled_tool_ids` and any `ToolFilter` (with a known registry and known external MCP tool set), the sum of `local_tools + gateway_tools + external_mcp_tools + unknown_tools` from `get_statistics()` should equal `total_requested`. - -**Validates: Requirements 6.7** - -### Property 5: FileSanitizer output invariant and idempotence - -*For any* input string, `sanitize_filename(x)` should (a) match the regex `^[a-zA-Z0-9\s\-\(\)\[\]_]*$` and (b) satisfy `sanitize_filename(sanitize_filename(x)) == sanitize_filename(x)`. - -**Validates: Requirements 10.4, 10.5** - -### Property 6: SSE format invariant and JSON round-trip - -*For any* dictionary with string keys and JSON-serializable values, `format_sse_event(d)` should (a) start with `"data: "` and end with `"\n\n"`, and (b) the JSON payload extracted from between the prefix and suffix should parse back to the original dictionary. - -**Validates: Requirements 12.9, 12.10** - -### Property 7: PreviewSessionManager count invariant - -*For any* sequence of `create_message` and `clear_session` operations on a `PreviewSessionManager`, `message_count` should equal the number of `create_message` calls since the last `clear_session` (or since initialization if no clear has occurred). - -**Validates: Requirements 14.8** - -### Property 8: CompactionState round-trip - -*For any* valid `CompactionState` instance (with any checkpoint, summary, last_input_tokens, and updated_at), `CompactionState.from_dict(state.to_dict())` should produce a `CompactionState` whose `to_dict()` output is identical to the original's `to_dict()` output. - -**Validates: Requirements 16.5** - -### Property 9: ProcessedEvent structural invariant - -*For any* raw event dictionary processed by any of the stream processor handler functions (`_handle_lifecycle_events`, `_handle_content_block_events`, `_handle_tool_events`, `_handle_reasoning_events`, `_handle_citation_events`, `_handle_metadata_events`), every returned `ProcessedEvent` should contain exactly the keys `"type"` (a string) and `"data"` (a dictionary). - -**Validates: Requirements 23.9** - -## Error Handling - -### Test-Level Error Handling - -Tests should verify error conditions without letting exceptions escape: - -| Error Condition | Expected Behavior | Test Approach | -|---|---|---| -| Missing API keys (OpenAI, Gemini) | `ValueError` raised | `pytest.raises(ValueError)` | -| Missing `AGENTCORE_MEMORY_ID` | `RuntimeError` raised | `pytest.raises(RuntimeError)` | -| Missing AgentCore Memory package | `RuntimeError` raised | Mock `AGENTCORE_MEMORY_AVAILABLE = False` | -| Non-serializable SSE event data | Error event returned (not exception) | Assert output contains `type: "error"` | -| Invalid provider string in `from_params` | Defaults to BEDROCK | Assert `get_provider() == BEDROCK` | -| Missing `cancelled` attribute on session manager | No exception raised | Assert `StopHook.check_cancelled` completes without error | -| No region from URL or boto3 | `ValueError` raised | `pytest.raises(ValueError)` | -| Neither token nor token_provider | `ValueError` raised | `pytest.raises(ValueError)` | - -### Mocking Failures - -When mocks are misconfigured or external dependencies change signatures, tests should fail with clear assertion errors rather than import errors. The `conftest.py` fixtures should use `autospec=True` where possible to catch API drift. - -## Testing Strategy - -### Dual Testing Approach - -The test suite uses two complementary testing methods: - -1. **Unit tests (pytest)**: Verify specific examples, edge cases, and error conditions for each acceptance criterion. These are deterministic and fast. - -2. **Property-based tests (Hypothesis)**: Verify universal properties across randomly generated inputs. These catch edge cases that example-based tests miss. - -Both are necessary — unit tests catch concrete bugs and verify specific behaviors, while property tests verify general correctness across the input space. - -### Property-Based Testing Configuration - -- **Library**: [Hypothesis](https://hypothesis.readthedocs.io/) (Python's standard PBT library) -- **Minimum iterations**: 100 per property (`@settings(max_examples=100)`) -- **Test file**: `backend/tests/agents/main_agent/property/test_pbt_agent_core.py` -- **Strategy file**: `backend/tests/agents/main_agent/property/conftest.py` -- **Each property test MUST reference its design property via docstring tag** -- **Tag format**: `Feature: agent-core-tests, Property {N}: {title}` -- **Each correctness property is implemented by a single `@given` test function** - -### Test Execution - -```bash -# Run all agent core unit tests -docker compose exec dev python -m pytest tests/agents/main_agent/ -v - -# Run only property-based tests -docker compose exec dev python -m pytest tests/agents/main_agent/property/ -v - -# Run with coverage -docker compose exec dev python -m pytest tests/agents/main_agent/ -v --cov=agents.main_agent -``` - -### Unit Test Balance - -- Unit tests focus on: specific examples from acceptance criteria, error conditions, edge cases (empty inputs, None values, missing env vars) -- Property tests focus on: invariants, round-trips, idempotence, partition properties -- Avoid duplicating property test coverage in unit tests — if a property covers "all inputs", don't write 10 unit tests for specific inputs of the same behavior diff --git a/.kiro/specs/agent-core-tests/requirements.md b/.kiro/specs/agent-core-tests/requirements.md deleted file mode 100644 index 58d7b4c5..00000000 --- a/.kiro/specs/agent-core-tests/requirements.md +++ /dev/null @@ -1,360 +0,0 @@ -# Requirements Document - -## Introduction - -Comprehensive unit and property-based test coverage for the Agent Core module (`backend/src/agents/main_agent/`). This module is the heart of the conversational AI system — it orchestrates agent creation, session management, tool filtering, multimodal content handling, streaming event processing, and external integrations. Currently at zero test coverage across all submodules (core, session, streaming, tools, multimodal, integrations, utils), this spec defines the requirements for a thorough test suite using pytest, pytest-asyncio, and Hypothesis. - -## Glossary - -- **Test_Suite**: The collection of pytest test files under `backend/tests/agents/main_agent/` -- **ModelConfig**: Dataclass that holds LLM provider configuration (model ID, temperature, caching, retry settings) -- **RetryConfig**: Dataclass controlling two-layer retry behavior (botocore HTTP-level and Strands SDK agent-level) -- **AgentFactory**: Static factory that creates Strands Agent instances for Bedrock, OpenAI, or Gemini providers -- **SystemPromptBuilder**: Builder class that constructs system prompts with optional date injection -- **ToolRegistry**: Registry that discovers and stores tool objects by ID -- **ToolFilter**: Filters tools into local, gateway, and external MCP categories based on user-enabled tool lists -- **ToolCatalogService**: Service for querying tool metadata (name, description, category, icon) -- **GatewayIntegration**: Manages Gateway MCP client lifecycle for AgentCore Gateway tools -- **StreamCoordinator**: Orchestrates streaming agent responses, metadata storage, and cost calculation -- **StreamEventFormatter**: Formats processed events into SSE-compatible `data: {...}\n\n` strings -- **ToolResultProcessor**: Extracts text and images from tool execution results -- **ImageHandler**: Detects image formats and creates Bedrock-compatible image ContentBlocks -- **DocumentHandler**: Detects document formats and creates Bedrock-compatible document ContentBlocks -- **FileSanitizer**: Sanitizes filenames to meet AWS Bedrock character requirements -- **PromptBuilder**: Assembles multimodal prompts from text, images, and documents -- **SessionFactory**: Factory that creates the appropriate session manager (cloud or preview) -- **PreviewSessionManager**: In-memory session manager for assistant preview/testing (no persistence) -- **TurnBasedSessionManager**: Cloud session manager with AgentCore Memory, compaction, and summarization -- **CompactionState**: Dataclass tracking compaction checkpoint, summary, and token counts -- **CompactionConfig**: Dataclass for compaction behavior configuration (threshold, protected turns) -- **StopHook**: Strands hook that cancels tool execution when a session is stopped by the user -- **OAuthBearerAuth**: HTTPX Auth class that injects OAuth Bearer tokens into requests -- **CompositeAuth**: Combines multiple HTTPX Auth handlers (e.g., SigV4 + OAuth) -- **SigV4HTTPXAuth**: HTTPX Auth class that signs requests with AWS SigV4 for Gateway authentication -- **FilteredMCPClient**: MCPClient wrapper that filters gateway tools based on enabled tool IDs -- **MemoryStorageConfig**: Configuration dataclass for AgentCore Memory (memory ID, region) - -## Requirements - -### Requirement 1: Model Configuration Tests - -**User Story:** As a developer, I want ModelConfig to correctly manage multi-provider LLM configuration, so that agents are created with the right model parameters for Bedrock, OpenAI, and Gemini. - -#### Acceptance Criteria - -1. THE Test_Suite SHALL verify that ModelConfig initializes with correct default values (model_id, temperature, caching_enabled, provider) -2. WHEN a model_id starting with "gpt-" or "o1-" is provided, THE Test_Suite SHALL verify that ModelConfig.get_provider returns ModelProvider.OPENAI -3. WHEN a model_id starting with "gemini-" is provided, THE Test_Suite SHALL verify that ModelConfig.get_provider returns ModelProvider.GEMINI -4. WHEN a model_id containing "anthropic" or "claude" is provided, THE Test_Suite SHALL verify that ModelConfig.get_provider returns ModelProvider.BEDROCK -5. WHEN provider is explicitly set to a non-Bedrock value, THE Test_Suite SHALL verify that get_provider returns the explicit provider regardless of model_id -6. THE Test_Suite SHALL verify that to_bedrock_config produces a dictionary with model_id, temperature, and CacheConfig when caching is enabled -7. THE Test_Suite SHALL verify that to_bedrock_config includes boto_client_config with retry settings when RetryConfig is present -8. THE Test_Suite SHALL verify that to_openai_config produces a dictionary with model_id and params containing temperature -9. WHEN max_tokens is set, THE Test_Suite SHALL verify that to_openai_config includes max_tokens in params and to_gemini_config includes max_output_tokens in params -10. THE Test_Suite SHALL verify that to_dict produces a dictionary with provider resolved via get_provider -11. THE Test_Suite SHALL verify that ModelConfig.from_params creates a config with defaults applied for omitted parameters -12. WHEN an invalid provider string is passed to from_params, THE Test_Suite SHALL verify that the provider defaults to BEDROCK -13. FOR ALL valid ModelConfig instances, THE Test_Suite SHALL verify that from_params(to_dict values) produces an equivalent configuration (round-trip property) - -### Requirement 2: Retry Configuration Tests - -**User Story:** As a developer, I want RetryConfig to correctly load from environment variables and provide sensible defaults, so that retry behavior is configurable without code changes. - -#### Acceptance Criteria - -1. THE Test_Suite SHALL verify that RetryConfig initializes with correct default values (boto_max_attempts=3, sdk_max_attempts=4, sdk_initial_delay=2.0, sdk_max_delay=16.0) -2. WHEN environment variables RETRY_BOTO_MAX_ATTEMPTS, RETRY_SDK_MAX_ATTEMPTS, RETRY_SDK_INITIAL_DELAY, and RETRY_SDK_MAX_DELAY are set, THE Test_Suite SHALL verify that RetryConfig.from_env reads those values -3. WHEN no environment variables are set, THE Test_Suite SHALL verify that RetryConfig.from_env returns default values -4. FOR ALL RetryConfig instances, THE Test_Suite SHALL verify that sdk_initial_delay is less than or equal to sdk_max_delay (invariant property) - -### Requirement 3: System Prompt Builder Tests - -**User Story:** As a developer, I want SystemPromptBuilder to correctly construct system prompts with optional date injection, so that agents receive properly formatted instructions. - -#### Acceptance Criteria - -1. WHEN include_date is True, THE Test_Suite SHALL verify that SystemPromptBuilder.build appends a "Current date:" line to the base prompt -2. WHEN include_date is False, THE Test_Suite SHALL verify that SystemPromptBuilder.build returns the base prompt unchanged -3. WHEN a custom base_prompt is provided, THE Test_Suite SHALL verify that SystemPromptBuilder uses the custom prompt instead of DEFAULT_SYSTEM_PROMPT -4. WHEN from_user_prompt is called, THE Test_Suite SHALL verify that the builder is configured with the user prompt as the base prompt -5. THE Test_Suite SHALL verify that DEFAULT_SYSTEM_PROMPT contains expected key phrases ("boisestate.ai", "CORE PRINCIPLES", "RESPONSE GUIDELINES") - -### Requirement 4: Agent Factory Tests - -**User Story:** As a developer, I want AgentFactory to create correctly configured Strands Agent instances for each provider, so that the agent is wired with the right model, tools, and session manager. - -#### Acceptance Criteria - -1. WHEN provider is BEDROCK, THE Test_Suite SHALL verify that AgentFactory.create_agent creates an Agent with a BedrockModel -2. WHEN provider is OPENAI and OPENAI_API_KEY is set, THE Test_Suite SHALL verify that AgentFactory.create_agent creates an Agent with an OpenAIModel -3. WHEN provider is GEMINI and GOOGLE_GEMINI_API_KEY is set, THE Test_Suite SHALL verify that AgentFactory.create_agent creates an Agent with a GeminiModel -4. IF OPENAI_API_KEY is not set and provider is OPENAI, THEN THE Test_Suite SHALL verify that AgentFactory raises ValueError -5. IF GOOGLE_GEMINI_API_KEY is not set and provider is GEMINI, THEN THE Test_Suite SHALL verify that AgentFactory raises ValueError -6. WHEN retry_config is provided for a Bedrock model, THE Test_Suite SHALL verify that a ModelRetryStrategy is passed to the Agent -7. WHEN retry_config is not provided or provider is not Bedrock, THE Test_Suite SHALL verify that retry_strategy is None -8. THE Test_Suite SHALL verify that AgentFactory passes SequentialToolExecutor to the Agent constructor - -### Requirement 5: Tool Registry Tests - -**User Story:** As a developer, I want ToolRegistry to correctly register, retrieve, and manage tools, so that the agent has access to the right set of tools. - -#### Acceptance Criteria - -1. THE Test_Suite SHALL verify that a new ToolRegistry starts with zero tools -2. WHEN register_tool is called, THE Test_Suite SHALL verify that the tool is retrievable via get_tool and has_tool returns True -3. WHEN get_tool is called with an unregistered tool_id, THE Test_Suite SHALL verify that it returns None -4. WHEN has_tool is called with an unregistered tool_id, THE Test_Suite SHALL verify that it returns False -5. WHEN register_module_tools is called with a module that has __all__, THE Test_Suite SHALL verify that all exported tools are registered -6. WHEN register_module_tools is called with a module without __all__, THE Test_Suite SHALL verify that no tools are registered -7. THE Test_Suite SHALL verify that get_all_tool_ids returns all registered tool IDs -8. THE Test_Suite SHALL verify that get_tool_count returns the correct count after registrations -9. FOR ALL sequences of register_tool calls, THE Test_Suite SHALL verify that get_tool_count equals the number of unique tool_ids registered (idempotence/count invariant) - -### Requirement 6: Tool Filter Tests - -**User Story:** As a developer, I want ToolFilter to correctly categorize tools into local, gateway, and external MCP buckets, so that each tool type is handled by the appropriate integration. - -#### Acceptance Criteria - -1. WHEN enabled_tool_ids is None or empty, THE Test_Suite SHALL verify that filter_tools returns empty lists for both local tools and gateway tool IDs -2. WHEN enabled_tool_ids contains registered local tool IDs, THE Test_Suite SHALL verify that filter_tools returns the corresponding tool objects -3. WHEN enabled_tool_ids contains IDs starting with "gateway_", THE Test_Suite SHALL verify that filter_tools returns those IDs in the gateway_tool_ids list -4. WHEN enabled_tool_ids contains unrecognized tool IDs, THE Test_Suite SHALL verify that filter_tools skips those IDs -5. WHEN set_external_mcp_tools is called and filter_tools_extended is used, THE Test_Suite SHALL verify that external MCP tool IDs appear in the external_mcp_tool_ids list -6. THE Test_Suite SHALL verify that get_statistics returns correct counts for each tool category -7. FOR ALL lists of enabled_tool_ids, THE Test_Suite SHALL verify that the sum of local_tools, gateway_tools, external_mcp_tools, and unknown_tools in get_statistics equals total_requested (partition invariant) - -### Requirement 7: Tool Catalog Service Tests - -**User Story:** As a developer, I want ToolCatalogService to provide correct tool metadata for UI display and authorization, so that the frontend can render tool information accurately. - -#### Acceptance Criteria - -1. THE Test_Suite SHALL verify that get_all_tools returns all tools in the catalog -2. WHEN get_tool is called with a valid tool_id, THE Test_Suite SHALL verify that it returns the correct ToolMetadata -3. WHEN get_tool is called with an invalid tool_id, THE Test_Suite SHALL verify that it returns None -4. THE Test_Suite SHALL verify that get_tools_by_category returns only tools matching the specified category -5. WHEN add_gateway_tool is called without "gateway_" prefix, THE Test_Suite SHALL verify that the prefix is automatically added -6. THE Test_Suite SHALL verify that ToolMetadata.to_dict produces a dictionary with camelCase keys (toolId, isGatewayTool, requiresOauthProvider) - -### Requirement 8: Multimodal Image Handler Tests - -**User Story:** As a developer, I want ImageHandler to correctly detect image formats and create Bedrock-compatible ContentBlocks, so that image attachments are processed correctly. - -#### Acceptance Criteria - -1. WHEN content_type starts with "image/", THE Test_Suite SHALL verify that is_image returns True -2. WHEN filename ends with .png, .jpg, .jpeg, .gif, or .webp, THE Test_Suite SHALL verify that is_image returns True -3. WHEN content_type is not image and filename has no image extension, THE Test_Suite SHALL verify that is_image returns False -4. THE Test_Suite SHALL verify that get_image_format returns "png" for image/png content type and .png extension -5. THE Test_Suite SHALL verify that get_image_format returns "jpeg" for image/jpeg, image/jpg, .jpg, and .jpeg -6. THE Test_Suite SHALL verify that get_image_format defaults to "png" for unrecognized formats -7. THE Test_Suite SHALL verify that create_content_block returns a dictionary with "image" key containing "format" and "source.bytes" - -### Requirement 9: Multimodal Document Handler Tests - -**User Story:** As a developer, I want DocumentHandler to correctly detect document formats and create ContentBlocks, so that document attachments are processed correctly. - -#### Acceptance Criteria - -1. THE Test_Suite SHALL verify that is_document returns True for all supported extensions (.pdf, .csv, .doc, .docx, .xls, .xlsx, .html, .txt, .md) -2. THE Test_Suite SHALL verify that is_document returns False for unsupported extensions (.exe, .zip, .py) -3. THE Test_Suite SHALL verify that get_document_format returns the correct format string for each supported extension -4. THE Test_Suite SHALL verify that get_document_format defaults to "txt" for unrecognized extensions -5. THE Test_Suite SHALL verify that create_content_block returns a dictionary with "document" key containing "format", "name", and "source.bytes" - -### Requirement 10: File Sanitizer Tests - -**User Story:** As a developer, I want FileSanitizer to produce Bedrock-safe filenames, so that file uploads do not cause API errors. - -#### Acceptance Criteria - -1. THE Test_Suite SHALL verify that sanitize_filename replaces special characters with underscores while preserving alphanumeric characters, hyphens, parentheses, and square brackets -2. THE Test_Suite SHALL verify that sanitize_filename collapses consecutive whitespace into a single space -3. THE Test_Suite SHALL verify that sanitize_filename trims leading and trailing whitespace -4. FOR ALL input strings, THE Test_Suite SHALL verify that sanitize_filename output matches the regex pattern `^[a-zA-Z0-9\s\-\(\)\[\]_]*$` (output invariant property) -5. FOR ALL input strings, THE Test_Suite SHALL verify that sanitize_filename is idempotent: sanitize(sanitize(x)) equals sanitize(x) - -### Requirement 11: Multimodal Prompt Builder Tests - -**User Story:** As a developer, I want PromptBuilder to correctly assemble multimodal prompts from text, images, and documents, so that the agent receives properly structured input. - -#### Acceptance Criteria - -1. WHEN no files are provided, THE Test_Suite SHALL verify that build_prompt returns the message as a plain string -2. WHEN files are provided, THE Test_Suite SHALL verify that build_prompt returns a list of ContentBlocks with text first -3. WHEN image files are provided, THE Test_Suite SHALL verify that the ContentBlock list includes image blocks with correct format -4. WHEN document files are provided, THE Test_Suite SHALL verify that the ContentBlock list includes document blocks with sanitized names -5. WHEN an unsupported file type is provided, THE Test_Suite SHALL verify that build_prompt skips the unsupported file and includes only supported content -6. THE Test_Suite SHALL verify that get_content_type_summary returns "text only" for string prompts -7. THE Test_Suite SHALL verify that get_content_type_summary returns correct counts for multimodal prompts (e.g., "text + 2 images + 1 document") -8. WHEN files include a filename, THE Test_Suite SHALL verify that the text block includes an "[Attached files: ...]" marker - -### Requirement 12: SSE Event Formatter Tests - -**User Story:** As a developer, I want StreamEventFormatter to produce correctly formatted SSE events, so that the frontend can parse streaming responses reliably. - -#### Acceptance Criteria - -1. THE Test_Suite SHALL verify that format_sse_event produces output in the format `data: {json}\n\n` -2. IF event_data contains non-serializable objects, THEN THE Test_Suite SHALL verify that format_sse_event returns an error event instead of raising an exception -3. THE Test_Suite SHALL verify that create_init_event produces an event with type "init" -4. THE Test_Suite SHALL verify that create_response_event produces an event with type "response" and the provided text -5. THE Test_Suite SHALL verify that create_tool_use_event produces an event with type "tool_use" containing toolUseId, name, and input -6. THE Test_Suite SHALL verify that create_complete_event produces an event with type "complete" and optional images and usage data -7. THE Test_Suite SHALL verify that create_error_event produces an event with type "error" and the error message -8. THE Test_Suite SHALL verify that extract_final_result_data extracts text parts and image data from a final result object -9. FOR ALL valid event dictionaries, THE Test_Suite SHALL verify that format_sse_event output starts with "data: " and ends with "\n\n" (format invariant) -10. FOR ALL valid event dictionaries, THE Test_Suite SHALL verify that the JSON payload in format_sse_event output can be parsed back to the original dictionary (round-trip property) - -### Requirement 13: Tool Result Processor Tests - -**User Story:** As a developer, I want ToolResultProcessor to correctly extract text and images from tool execution results, so that tool outputs are displayed properly in the chat. - -#### Acceptance Criteria - -1. WHEN a tool result contains text content, THE Test_Suite SHALL verify that process_tool_result extracts the text -2. WHEN a tool result contains image content with base64 data, THE Test_Suite SHALL verify that process_tool_result extracts the images -3. WHEN a tool result contains JSON content with embedded images, THE Test_Suite SHALL verify that _process_json_content extracts the images and cleans the text -4. WHEN a tool result has no content, THE Test_Suite SHALL verify that process_tool_result returns empty text and empty image list - -### Requirement 14: Preview Session Manager Tests - -**User Story:** As a developer, I want PreviewSessionManager to maintain in-memory conversation context without persistence, so that assistant preview sessions work correctly. - -#### Acceptance Criteria - -1. THE Test_Suite SHALL verify that PreviewSessionManager initializes with zero messages -2. WHEN create_message is called, THE Test_Suite SHALL verify that the message is stored in memory and message_count increases -3. WHEN read_session is called, THE Test_Suite SHALL verify that it returns a copy of stored messages (not a reference) -4. WHEN clear_session is called, THE Test_Suite SHALL verify that all messages are removed and message_count returns to zero -5. THE Test_Suite SHALL verify that is_preview_session returns True for session IDs starting with "preview-" and False otherwise -6. WHEN _initialize_agent is called with existing messages, THE Test_Suite SHALL verify that the agent's messages list is populated -7. WHEN _initialize_agent is called with no messages, THE Test_Suite SHALL verify that the agent's messages list is empty -8. FOR ALL sequences of create_message and clear_session operations, THE Test_Suite SHALL verify that message_count equals the number of messages added since the last clear (count invariant) - -### Requirement 15: Session Factory Tests - -**User Story:** As a developer, I want SessionFactory to create the correct session manager type based on session ID and environment, so that preview and cloud sessions are handled appropriately. - -#### Acceptance Criteria - -1. WHEN session_id starts with "preview-", THE Test_Suite SHALL verify that SessionFactory.create_session_manager returns a PreviewSessionManager -2. WHEN session_id does not start with "preview-" and AgentCore Memory is available, THE Test_Suite SHALL verify that SessionFactory.create_session_manager returns a TurnBasedSessionManager -3. IF AgentCore Memory package is not available and session is not a preview, THEN THE Test_Suite SHALL verify that SessionFactory.create_session_manager raises RuntimeError -4. THE Test_Suite SHALL verify that is_cloud_mode returns True when AgentCore Memory is available and configured, and False otherwise - -### Requirement 16: Compaction Models Tests - -**User Story:** As a developer, I want CompactionState and CompactionConfig to correctly serialize, deserialize, and load from environment, so that compaction behavior is configurable and state is persisted correctly. - -#### Acceptance Criteria - -1. THE Test_Suite SHALL verify that CompactionState initializes with default values (checkpoint=0, summary=None, last_input_tokens=0) -2. THE Test_Suite SHALL verify that CompactionState.to_dict produces a dictionary with camelCase keys -3. WHEN CompactionState.from_dict is called with a valid dictionary, THE Test_Suite SHALL verify that it reconstructs the correct state -4. WHEN CompactionState.from_dict is called with None or empty dict, THE Test_Suite SHALL verify that it returns default state -5. FOR ALL CompactionState instances, THE Test_Suite SHALL verify that from_dict(to_dict(state)) produces an equivalent state (round-trip property) -6. THE Test_Suite SHALL verify that CompactionConfig.from_env reads AGENTCORE_MEMORY_COMPACTION_ENABLED, AGENTCORE_MEMORY_COMPACTION_TOKEN_THRESHOLD, AGENTCORE_MEMORY_COMPACTION_PROTECTED_TURNS, and AGENTCORE_MEMORY_COMPACTION_MAX_TOOL_CONTENT_LENGTH from environment -7. WHEN no environment variables are set, THE Test_Suite SHALL verify that CompactionConfig.from_env returns default values - -### Requirement 17: Memory Configuration Tests - -**User Story:** As a developer, I want load_memory_config to correctly load and validate memory configuration from environment, so that AgentCore Memory is properly initialized. - -#### Acceptance Criteria - -1. WHEN AGENTCORE_MEMORY_ID is set, THE Test_Suite SHALL verify that load_memory_config returns a MemoryStorageConfig with the correct memory_id and region -2. IF AGENTCORE_MEMORY_ID is not set, THEN THE Test_Suite SHALL verify that load_memory_config raises RuntimeError -3. WHEN AWS_REGION is set, THE Test_Suite SHALL verify that load_memory_config uses the specified region -4. WHEN AWS_REGION is not set, THE Test_Suite SHALL verify that load_memory_config defaults to "us-west-2" -5. THE Test_Suite SHALL verify that MemoryStorageConfig.is_cloud_mode always returns True - -### Requirement 18: Stop Hook Tests - -**User Story:** As a developer, I want StopHook to cancel tool execution when a session is stopped, so that users can interrupt long-running agent operations. - -#### Acceptance Criteria - -1. WHEN session_manager.cancelled is True, THE Test_Suite SHALL verify that StopHook.check_cancelled sets event.cancel_tool to a cancellation message -2. WHEN session_manager.cancelled is False, THE Test_Suite SHALL verify that StopHook.check_cancelled does not modify the event -3. WHEN session_manager does not have a cancelled attribute, THE Test_Suite SHALL verify that StopHook.check_cancelled does not raise an exception - -### Requirement 19: OAuth Bearer Auth Tests - -**User Story:** As a developer, I want OAuthBearerAuth to correctly inject Bearer tokens into HTTP requests, so that external MCP servers receive proper authentication. - -#### Acceptance Criteria - -1. WHEN a static token is provided, THE Test_Suite SHALL verify that auth_flow adds "Authorization: Bearer {token}" to the request headers -2. WHEN a token_provider callback is provided, THE Test_Suite SHALL verify that auth_flow calls the provider and uses the returned token -3. WHEN the token_provider returns None, THE Test_Suite SHALL verify that auth_flow does not add an Authorization header -4. IF neither token nor token_provider is provided, THEN THE Test_Suite SHALL verify that OAuthBearerAuth raises ValueError -5. THE Test_Suite SHALL verify that CompositeAuth applies all auth handlers in order to the request - -### Requirement 20: SigV4 Gateway Auth Tests - -**User Story:** As a developer, I want SigV4HTTPXAuth to correctly sign requests for AgentCore Gateway, so that gateway MCP tools authenticate successfully. - -#### Acceptance Criteria - -1. THE Test_Suite SHALL verify that SigV4HTTPXAuth.auth_flow adds AWS signature headers to the request -2. THE Test_Suite SHALL verify that SigV4HTTPXAuth.auth_flow removes the "connection" header before signing -3. THE Test_Suite SHALL verify that get_gateway_region_from_url extracts the correct region from a standard Gateway URL pattern -4. WHEN the URL does not match the expected pattern, THE Test_Suite SHALL verify that get_gateway_region_from_url falls back to the boto3 session region -5. IF no region can be determined from URL or boto3 session, THEN THE Test_Suite SHALL verify that get_gateway_region_from_url raises ValueError - -### Requirement 21: Timezone Utility Tests - -**User Story:** As a developer, I want get_current_date_pacific to return correctly formatted dates in Pacific timezone, so that system prompts include accurate date information. - -#### Acceptance Criteria - -1. THE Test_Suite SHALL verify that get_current_date_pacific returns a string matching the format "YYYY-MM-DD (DayName) HH:00 TZ" -2. THE Test_Suite SHALL verify that the timezone abbreviation is either PST or PDT -3. IF timezone libraries are unavailable, THEN THE Test_Suite SHALL verify that get_current_date_pacific falls back to UTC - -### Requirement 22: Global State Deprecation Tests - -**User Story:** As a developer, I want the deprecated global state functions to be safe no-ops, so that backward-compatible code does not break. - -#### Acceptance Criteria - -1. THE Test_Suite SHALL verify that set_global_stream_processor accepts any argument without raising an exception -2. THE Test_Suite SHALL verify that get_global_stream_processor returns None - -### Requirement 23: Stream Processor Event Handling Tests - -**User Story:** As a developer, I want the stream processor to correctly transform raw Strands Agent events into standardized processed events, so that the frontend receives a consistent event format. - -#### Acceptance Criteria - -1. WHEN a lifecycle event (message_start, message_stop) is received, THE Test_Suite SHALL verify that _handle_lifecycle_events produces the correct processed events -2. WHEN a content_block_start event with type "text" is received, THE Test_Suite SHALL verify that _handle_content_block_events produces a content_block_start event with the correct contentBlockIndex -3. WHEN a content_block_delta event with text data is received, THE Test_Suite SHALL verify that _handle_content_block_events produces a content_block_delta event with the text -4. WHEN a tool_use event is received, THE Test_Suite SHALL verify that _handle_tool_events produces events with toolUseId, name, and input -5. WHEN a reasoning event (thinking text) is received, THE Test_Suite SHALL verify that _handle_reasoning_events produces a reasoning event with the text -6. WHEN a citation event is received, THE Test_Suite SHALL verify that _handle_citation_events produces citation_start or citation_end events with source metadata -7. WHEN a metadata event with usage data is received, THE Test_Suite SHALL verify that _handle_metadata_events produces a metadata event with token counts -8. THE Test_Suite SHALL verify that _serialize_object correctly handles primitives, datetime, UUID, Decimal, dicts, lists, and objects with __dict__ -9. FOR ALL ProcessedEvent outputs, THE Test_Suite SHALL verify that the event contains "type" and "data" keys (structural invariant) - -### Requirement 24: Gateway MCP Client Tests - -**User Story:** As a developer, I want FilteredMCPClient to correctly filter gateway tools based on enabled tool IDs, so that only user-selected gateway tools are available to the agent. - -#### Acceptance Criteria - -1. THE Test_Suite SHALL verify that FilteredMCPClient stores the enabled_tool_ids and prefix -2. THE Test_Suite SHALL verify that get_gateway_client_if_enabled returns None when AGENTCORE_GATEWAY_MCP_ENABLED is "false" -3. WHEN no gateway tool IDs are provided, THE Test_Suite SHALL verify that create_filtered_gateway_client returns None - -### Requirement 25: External MCP Client Utility Tests - -**User Story:** As a developer, I want the external MCP client utilities to correctly parse URLs and detect AWS services, so that external tool connections are configured properly. - -#### Acceptance Criteria - -1. THE Test_Suite SHALL verify that extract_region_from_url correctly extracts AWS region from standard AgentCore URLs -2. WHEN the URL does not contain a recognizable region pattern, THE Test_Suite SHALL verify that extract_region_from_url returns None -3. THE Test_Suite SHALL verify that detect_aws_service_from_url returns the correct service name for known URL patterns (e.g., "bedrock-agentcore" for gateway URLs) diff --git a/.kiro/specs/agent-core-tests/tasks.md b/.kiro/specs/agent-core-tests/tasks.md deleted file mode 100644 index 3b9012e6..00000000 --- a/.kiro/specs/agent-core-tests/tasks.md +++ /dev/null @@ -1,216 +0,0 @@ -# Implementation Plan: Agent Core Tests - -## Overview - -Build a comprehensive pytest test suite for `backend/src/agents/main_agent/` covering 25 requirements across 7 submodules. Tests are organized to mirror source structure, with shared fixtures first, simple dataclass/utility tests next, and complex integration-heavy tests last. All external dependencies are mocked. Property-based tests use Hypothesis. - -All commands run inside Docker: `docker compose exec dev ` - -## Tasks - -- [x] 1. Create shared test fixtures and directory structure - - [x] 1.1 Create `backend/tests/agents/main_agent/conftest.py` with shared fixtures - - Create directory structure: `core/`, `tools/`, `multimodal/`, `streaming/`, `session/`, `integrations/`, `utils/`, `property/` - - Add `__init__.py` files for each subdirectory - - Implement fixtures: `tool_registry`, `tool_filter`, `model_config`, `retry_config`, `preview_session`, `mock_agent`, `sample_files` - - _Requirements: All (shared infrastructure)_ - - - [x] 1.2 Create `backend/tests/agents/main_agent/property/conftest.py` with Hypothesis strategies - - Implement strategies: `st_model_config`, `st_retry_config`, `st_compaction_state`, `st_filename`, `st_tool_ids`, `st_sse_event_dict` - - _Requirements: 1.13, 2.4, 5.9, 6.7, 10.4, 10.5, 12.9, 12.10, 14.8, 16.5, 23.9_ - -- [x] 2. Checkpoint - Ensure fixtures load correctly - - Ensure all tests pass, ask the user if questions arise. - -- [x] 3. Core submodule tests — dataclasses and configuration - - [x] 3.1 Create `backend/tests/agents/main_agent/core/test_model_config.py` - - Test ModelConfig defaults, `get_provider` for Bedrock/OpenAI/Gemini model IDs, explicit provider override - - Test `to_bedrock_config` with/without caching and retry, `to_openai_config`, `to_gemini_config` with max_tokens - - Test `to_dict`, `from_params` with defaults and invalid provider - - _Requirements: 1.1–1.12_ - - - [x] 3.2 Create RetryConfig tests in `test_model_config.py` - - Test default values, `from_env` with and without environment variables - - _Requirements: 2.1–2.3_ - - - [x] 3.3 Create `backend/tests/agents/main_agent/core/test_system_prompt_builder.py` - - Test `build` with include_date True/False, custom base_prompt, `from_user_prompt` - - Test DEFAULT_SYSTEM_PROMPT contains expected key phrases - - _Requirements: 3.1–3.5_ - - - [x] 3.4 Create `backend/tests/agents/main_agent/core/test_agent_factory.py` - - Test `create_agent` for Bedrock, OpenAI (with/without API key), Gemini (with/without API key) - - Test retry_strategy passed for Bedrock, None for others - - Test SequentialToolExecutor is passed - - Mock `strands.Agent`, `BedrockModel`, `OpenAIModel`, `GeminiModel` - - _Requirements: 4.1–4.8_ - -- [x] 4. Tools submodule tests - - [x] 4.1 Create `backend/tests/agents/main_agent/tools/test_tool_registry.py` - - Test empty registry, register/get/has tool, unregistered tool returns None/False - - Test `register_module_tools` with and without `__all__`, `get_all_tool_ids`, `get_tool_count` - - _Requirements: 5.1–5.8_ - - - [x] 4.2 Create `backend/tests/agents/main_agent/tools/test_tool_filter.py` - - Test empty/None enabled_tool_ids, local tool filtering, gateway tool filtering, unrecognized IDs - - Test `set_external_mcp_tools` + `filter_tools_extended`, `get_statistics` counts - - _Requirements: 6.1–6.6_ - - - [x] 4.3 Create `backend/tests/agents/main_agent/tools/test_tool_catalog.py` - - Test `get_all_tools`, `get_tool` valid/invalid, `get_tools_by_category` - - Test `add_gateway_tool` auto-prefix, `ToolMetadata.to_dict` camelCase keys - - _Requirements: 7.1–7.6_ - -- [x] 5. Multimodal submodule tests - - [x] 5.1 Create `backend/tests/agents/main_agent/multimodal/test_image_handler.py` - - Test `is_image` by content_type, by extension, negative case - - Test `get_image_format` for png/jpeg/default, `create_content_block` structure - - _Requirements: 8.1–8.7_ - - - [x] 5.2 Create `backend/tests/agents/main_agent/multimodal/test_document_handler.py` - - Test `is_document` for all supported/unsupported extensions - - Test `get_document_format` mapping and default, `create_content_block` structure - - _Requirements: 9.1–9.5_ - - - [x] 5.3 Create `backend/tests/agents/main_agent/multimodal/test_file_sanitizer.py` - - Test special character replacement, whitespace collapsing, trimming - - _Requirements: 10.1–10.3_ - - - [x] 5.4 Create `backend/tests/agents/main_agent/multimodal/test_prompt_builder.py` - - Test `build_prompt` with no files (plain string), with images, with documents, with unsupported files - - Test `get_content_type_summary` for text-only and multimodal, attached files marker - - _Requirements: 11.1–11.8_ - -- [x] 6. Checkpoint - Ensure all dataclass and handler tests pass - - Ensure all tests pass, ask the user if questions arise. - -- [x] 7. Streaming submodule tests - - [x] 7.1 Create `backend/tests/agents/main_agent/streaming/test_event_formatter.py` - - Test `format_sse_event` format, non-serializable error handling - - Test `create_init_event`, `create_response_event`, `create_tool_use_event`, `create_complete_event`, `create_error_event` - - Test `extract_final_result_data` - - _Requirements: 12.1–12.8_ - - - [x] 7.2 Create `backend/tests/agents/main_agent/streaming/test_tool_result_processor.py` - - Test text extraction, image extraction, JSON content with embedded images, empty content - - _Requirements: 13.1–13.4_ - - - [x] 7.3 Create `backend/tests/agents/main_agent/streaming/test_stream_processor.py` - - Test `_handle_lifecycle_events`, `_handle_content_block_events`, `_handle_tool_events` - - Test `_handle_reasoning_events`, `_handle_citation_events`, `_handle_metadata_events` - - Test `_serialize_object` with primitives, datetime, UUID, Decimal, dicts, lists, __dict__ objects - - _Requirements: 23.1–23.8_ - -- [x] 8. Session submodule tests - - [x] 8.1 Create `backend/tests/agents/main_agent/session/test_compaction_models.py` - - Test CompactionState defaults, `to_dict` camelCase, `from_dict` valid/None/empty - - Test CompactionConfig `from_env` with and without env vars - - _Requirements: 16.1–16.4, 16.6–16.7_ - - - [x] 8.2 Create `backend/tests/agents/main_agent/session/test_memory_config.py` - - Test `load_memory_config` with/without AGENTCORE_MEMORY_ID, region handling, `is_cloud_mode` - - _Requirements: 17.1–17.5_ - - - [x] 8.3 Create `backend/tests/agents/main_agent/session/test_stop_hook.py` - - Test `check_cancelled` when cancelled=True, cancelled=False, no cancelled attribute - - _Requirements: 18.1–18.3_ - - - [x] 8.4 Create `backend/tests/agents/main_agent/session/test_preview_session_manager.py` - - Test init with zero messages, `create_message`, `read_session` returns copy - - Test `clear_session`, `is_preview_session`, `_initialize_agent` with/without messages - - _Requirements: 14.1–14.7_ - - - [x] 8.5 Create `backend/tests/agents/main_agent/session/test_session_factory.py` - - Test preview session creation, cloud session creation with memory available - - Test RuntimeError when memory unavailable, `is_cloud_mode` - - Mock `bedrock_agentcore.memory` availability - - _Requirements: 15.1–15.4_ - -- [x] 9. Integrations submodule tests - - [x] 9.1 Create `backend/tests/agents/main_agent/integrations/test_oauth_auth.py` - - Test `OAuthBearerAuth` with static token, token_provider callback, None token, missing both - - Test `CompositeAuth` applies all handlers in order - - Mock `httpx.Request` - - _Requirements: 19.1–19.5_ - - - [x] 9.2 Create `backend/tests/agents/main_agent/integrations/test_gateway_auth.py` - - Test `SigV4HTTPXAuth.auth_flow` adds signature headers, removes connection header - - Test `get_gateway_region_from_url` extraction, fallback, ValueError - - Mock `boto3.Session`, `botocore.auth.SigV4Auth` - - _Requirements: 20.1–20.5_ - - - [x] 9.3 Create `backend/tests/agents/main_agent/integrations/test_gateway_mcp_client.py` - - Test `FilteredMCPClient` stores enabled_tool_ids and prefix - - Test `get_gateway_client_if_enabled` returns None when disabled, None when no gateway IDs - - _Requirements: 24.1–24.3_ - - - [x] 9.4 Create `backend/tests/agents/main_agent/integrations/test_external_mcp_client.py` - - Test `extract_region_from_url` for standard URLs and non-matching URLs - - Test `detect_aws_service_from_url` for known patterns - - _Requirements: 25.1–25.3_ - -- [x] 10. Utils submodule tests - - [x] 10.1 Create `backend/tests/agents/main_agent/utils/test_timezone.py` - - Test format "YYYY-MM-DD (DayName) HH:00 TZ", timezone is PST or PDT - - Test UTC fallback when timezone libraries unavailable - - _Requirements: 21.1–21.3_ - - - [x] 10.2 Create `backend/tests/agents/main_agent/utils/test_global_state.py` - - Test `set_global_stream_processor` accepts any arg, `get_global_stream_processor` returns None - - _Requirements: 22.1–22.2_ - -- [x] 11. Checkpoint - Ensure all unit tests pass - - Ensure all tests pass, ask the user if questions arise. - -- [x] 12. Property-based tests - - [x] 12.1 Create `backend/tests/agents/main_agent/property/test_pbt_agent_core.py` - - [x] 12.1.1 Write property test for ModelConfig round-trip - - **Property 1: ModelConfig round-trip** - - **Validates: Requirements 1.13** - - - [x] 12.1.2 Write property test for RetryConfig delay invariant - - **Property 2: RetryConfig delay invariant** - - **Validates: Requirements 2.4** - - - [x] 12.1.3 Write property test for ToolRegistry count invariant - - **Property 3: ToolRegistry count invariant** - - **Validates: Requirements 5.9** - - - [x] 12.1.4 Write property test for ToolFilter partition invariant - - **Property 4: ToolFilter partition invariant** - - **Validates: Requirements 6.7** - - - [x] 12.1.5 Write property test for FileSanitizer output invariant and idempotence - - **Property 5: FileSanitizer output invariant and idempotence** - - **Validates: Requirements 10.4, 10.5** - - - [x] 12.1.6 Write property test for SSE format invariant and JSON round-trip - - **Property 6: SSE format invariant and JSON round-trip** - - **Validates: Requirements 12.9, 12.10** - - - [x] 12.1.7 Write property test for PreviewSessionManager count invariant - - **Property 7: PreviewSessionManager count invariant** - - **Validates: Requirements 14.8** - - - [x] 12.1.8 Write property test for CompactionState round-trip - - **Property 8: CompactionState round-trip** - - **Validates: Requirements 16.5** - - - [x] 12.1.9 Write property test for ProcessedEvent structural invariant - - **Property 9: ProcessedEvent structural invariant** - - **Validates: Requirements 23.9** - -- [x] 13. Final checkpoint - Ensure all tests pass - - Ensure all tests pass, ask the user if questions arise. - - Run full suite: `docker compose exec dev python -m pytest tests/agents/main_agent/ -v` - - Verify coverage: `docker compose exec dev python -m pytest tests/agents/main_agent/ -v --cov=agents.main_agent` - -## Notes - -- Tasks marked with `*` are optional and can be skipped for faster MVP -- All commands must run inside Docker: `docker compose exec dev ` -- Workspace path inside container: `/workspace/bsu-org/agentcore-public-stack/` -- Each task references specific requirements for traceability -- Property tests validate universal correctness properties from the design document -- Unit tests validate specific examples and edge cases from acceptance criteria -- Checkpoints ensure incremental validation at natural breakpoints diff --git a/.kiro/specs/api-route-tests/.config.kiro b/.kiro/specs/api-route-tests/.config.kiro deleted file mode 100644 index 2d7de462..00000000 --- a/.kiro/specs/api-route-tests/.config.kiro +++ /dev/null @@ -1 +0,0 @@ -{"specId": "83305357-3aa6-4fff-b924-5b087888786d", "workflowType": "requirements-first", "specType": "feature"} \ No newline at end of file diff --git a/.kiro/specs/api-route-tests/design.md b/.kiro/specs/api-route-tests/design.md deleted file mode 100644 index b543b4c9..00000000 --- a/.kiro/specs/api-route-tests/design.md +++ /dev/null @@ -1,332 +0,0 @@ -# Design Document: API Route Tests - -## Overview - -This design covers comprehensive API route testing for the AgentCore Public Stack backend. The backend has two FastAPI applications — App API (port 8000, 15+ route modules) and Inference API (port 8001, 2 route modules) — with zero route-level test coverage today. - -The testing approach uses FastAPI's `TestClient` with `app.dependency_overrides` to mock authentication (`get_current_user`), RBAC guards (`require_roles`, `require_admin`), and service-layer dependencies (DynamoDB, S3, Bedrock). This keeps tests fast, deterministic, and isolated from AWS infrastructure. - -Key design decisions: -- **Per-module minimal FastAPI apps**: Each test module creates a `FastAPI()` instance mounting only the router under test, matching the existing pattern in `tests/auth/test_auth_routes.py`. -- **Shared fixtures in a route-test conftest**: A new `backend/tests/routes/conftest.py` provides reusable authenticated/unauthenticated clients, mock user factories, and service mock helpers. -- **Hypothesis for request validation**: Property-based tests generate random invalid payloads to verify routes reject malformed input consistently. -- **Route introspection for auth sweep**: Requirement 17 uses `app.routes` to programmatically discover all protected routes and verify they return 401 without auth. - -## Architecture - -```mermaid -graph TD - subgraph Test Infrastructure - CF[routes/conftest.py
Shared fixtures] - end - - subgraph Per-Module Route Tests - H[test_health.py] - S[test_sessions.py] - F[test_files.py] - C[test_chat.py] - A[test_auth.py] - AD[test_admin.py] - T[test_tools.py] - M[test_memory.py] - CO[test_costs.py] - U[test_users.py] - MO[test_models.py] - AS[test_assistants.py] - D[test_documents.py] - I[test_inference.py] - end - - subgraph Property Tests - PV[test_pbt_request_validation.py] - PA[test_pbt_auth_sweep.py] - end - - CF --> H & S & F & C & A & AD & T & M & CO & U & MO & AS & D & I - CF --> PV & PA - - subgraph Mocked Dependencies - AUTH[get_current_user
→ mock User] - RBAC[require_admin
→ mock admin User] - SVC[Service deps
→ AsyncMock] - end - - CF -.-> AUTH & RBAC & SVC -``` - -### Test File Layout - -``` -backend/tests/routes/ -├── __init__.py -├── conftest.py # Shared fixtures (Req 1) -├── test_health.py # Req 2 -├── test_sessions.py # Req 3 -├── test_files.py # Req 4 -├── test_chat.py # Req 5 -├── test_auth.py # Req 6 -├── test_admin.py # Req 7 -├── test_tools.py # Req 8 -├── test_memory.py # Req 9 -├── test_costs.py # Req 10 -├── test_users.py # Req 11 -├── test_models.py # Req 12 -├── test_assistants.py # Req 13 -├── test_documents.py # Req 14 -├── test_inference.py # Req 15 -├── test_pbt_request_validation.py # Req 16 -└── test_pbt_auth_sweep.py # Req 17 -``` - -### Testing Pattern - -Every per-module test file follows this pattern: - -1. Create a minimal `FastAPI()` app with only the router under test -2. Apply `dependency_overrides` for auth and service dependencies -3. Use `TestClient(app)` (synchronous) for request/response assertions -4. Group tests by endpoint in classes (e.g., `TestListSessions`, `TestDeleteSession`) - -This matches the established pattern in `tests/auth/test_auth_routes.py`. - -## Components and Interfaces - -### 1. Shared Test Fixtures (`routes/conftest.py`) - -Provides reusable pytest fixtures consumed by all route test modules. - -```python -# Key fixtures: - -def make_user() -> Callable[..., User]: - """Factory: create User with configurable email, user_id, name, roles.""" - -def mock_auth_user(app: FastAPI, user: User) -> None: - """Override get_current_user to return the given User.""" - -def mock_no_auth(app: FastAPI) -> None: - """Override get_current_user to raise HTTP 401.""" - -def authenticated_client(app: FastAPI, user: User) -> TestClient: - """TestClient with auth overridden to return user.""" - -def unauthenticated_client(app: FastAPI) -> TestClient: - """TestClient with no auth override (real dependency raises 401).""" - -def admin_client(app: FastAPI) -> TestClient: - """TestClient with auth overridden to return admin-role user.""" - -def mock_service(app: FastAPI, dependency: Callable, mock: Any) -> None: - """Override any FastAPI Depends() with a mock.""" -``` - -The `make_user` factory mirrors the existing `tests/auth/conftest.py` pattern but lives in the shared routes conftest so all route tests can use it. - -### 2. Per-Module Test Files - -Each test file: -- Imports the specific router from `apis.app_api..routes` -- Creates a local `@pytest.fixture def app()` mounting that router -- Uses `dependency_overrides` to mock `get_current_user` and any service dependencies -- Tests happy path (200), auth rejection (401), RBAC rejection (403), validation errors (400/422), and not-found (404) as applicable - -### 3. Auth Sweep Test (`test_pbt_auth_sweep.py`) - -Uses FastAPI's `app.routes` introspection to: -1. Import the full App API `app` from `apis.app_api.main` -2. Iterate all `APIRoute` objects -3. Skip known public routes (`/health`, `/auth/providers`, `/auth/login`, etc.) -4. For each protected route, send a request with no `Authorization` header -5. Assert HTTP 401 - -This is implemented as a parametrized test, not a Hypothesis property test, since the route list is finite and deterministic. - -### 4. Property-Based Request Validation (`test_pbt_request_validation.py`) - -Uses Hypothesis strategies to generate: -- Random invalid session IDs (UUIDs, empty strings, special characters) -- Random PresignRequest payloads with invalid MIME types -- Random payloads missing required fields - -Each strategy targets a specific route and asserts the appropriate 4xx status code. - -## Data Models - -### Test User Model - -The tests reuse the existing `User` dataclass from `apis.shared.auth.models`: - -```python -@dataclass -class User: - email: str - user_id: str - name: str - roles: List[str] - picture: Optional[str] = None - raw_token: Optional[str] = None -``` - -### Mock User Presets - -| Preset | email | user_id | roles | Purpose | -|--------|-------|---------|-------|---------| -| `default_user` | `test@example.com` | `user-001` | `["User"]` | Standard authenticated user | -| `admin_user` | `admin@example.com` | `admin-001` | `["Admin"]` | Admin route access | -| `no_role_user` | `norole@example.com` | `norole-001` | `[]` | RBAC rejection testing | - -### Dependency Override Map - -| Real Dependency | Override For | Mock Behavior | -|----------------|-------------|---------------| -| `get_current_user` | Auth tests | Returns mock `User` or raises `HTTPException(401)` | -| `get_current_user_id` | Document tests | Returns `user_id` string | -| `get_current_user_trusted` | Inference API tests | Returns mock `User` | -| `require_admin` | Admin tests | Returns admin `User` or raises `HTTPException(403)` | -| `require_roles(...)` | RBAC tests | Returns `User` with matching roles | -| `get_file_upload_service` | File tests | Returns `AsyncMock` of `FileUploadService` | -| `get_model_access_service` | Model tests | Returns `AsyncMock` of `ModelAccessService` | -| `get_user_repository` | User tests | Returns `AsyncMock` of `UserRepository` | -| `CostAggregator` | Cost tests | Patched via `unittest.mock.patch` | -| `SessionService` | Session tests | Patched via `unittest.mock.patch` | - - -## Correctness Properties - -*A property is a characteristic or behavior that should hold true across all valid executions of a system — essentially, a formal statement about what the system should do. Properties serve as the bridge between human-readable specifications and machine-verifiable correctness guarantees.* - -The following properties were derived from the acceptance criteria prework analysis. Each property is universally quantified and suitable for property-based testing with Hypothesis. - -### Property 1: Pagination limit invariant - -*For any* valid limit value N (1 ≤ N ≤ 1000) and any mock session list of arbitrary length, when GET /sessions is called with `limit=N`, the number of sessions returned SHALL be at most N. - -**Validates: Requirements 3.3** - -### Property 2: Invalid MIME type rejection - -*For any* randomly generated MIME type string that is not in the ALLOWED_MIME_TYPES set, when sent as part of a PresignRequest to POST /files/presign, the App_API SHALL return HTTP 400. - -**Validates: Requirements 4.2, 16.2** - -### Property 3: Oversized file rejection - -*For any* file size greater than MAX_FILE_SIZE (4MB), when sent as part of a PresignRequest to POST /files/presign with a valid MIME type, the App_API SHALL return HTTP 400. - -**Validates: Requirements 4.3** - -### Property 4: Non-admin role rejection - -*For any* User whose roles list does not contain "Admin", "SuperAdmin", or "DotNetDevelopers", when that user sends a request to an admin-protected endpoint, the App_API SHALL return HTTP 403. This includes the edge case where the roles list is empty. - -**Validates: Requirements 7.2, 7.3** - -### Property 5: Invalid session ID rejection - -*For any* randomly generated string used as a session_id in GET /sessions/{session_id}/metadata, when the underlying session lookup returns no result, the App_API SHALL return HTTP 404 or HTTP 422. - -**Validates: Requirements 16.1** - -### Property 6: Missing required fields rejection - -*For any* randomly generated JSON object that is missing one or more required fields expected by a route's request model, when sent to that route, the App_API SHALL return HTTP 422. - -**Validates: Requirements 16.3** - -### Property 7: Auth enforcement across all protected routes - -*For any* protected route in the App_API (discovered via `app.routes` introspection, excluding known public endpoints), when a request is sent without an Authorization header OR with an invalid/expired token, the App_API SHALL return HTTP 401. - -**Validates: Requirements 17.1, 17.2** - -## Error Handling - -### Test-Level Error Handling - -Tests themselves don't need error handling — they assert on expected outcomes. However, the test infrastructure must handle: - -1. **Dependency override cleanup**: Each test that modifies `app.dependency_overrides` must restore the original state. Using per-test `app` fixtures (created fresh each test) avoids this issue entirely. - -2. **Mock service exceptions**: When testing error paths (e.g., DynamoDB timeout), service mocks should raise the appropriate exception type so the route's `try/except` block produces the expected HTTP error response. - -3. **Hypothesis health checks**: Hypothesis may flag tests that are too slow or filter too many examples. Configure `@settings(suppress_health_check=[HealthCheck.too_slow])` where needed, and keep strategies focused to minimize filtering. - -### Expected Error Response Patterns - -The routes follow consistent error patterns that tests should verify: - -| Scenario | Expected Status | Expected Detail Pattern | -|----------|----------------|------------------------| -| No auth token | 401 | "Authentication required" | -| Invalid/expired token | 401 | "Authentication failed" | -| Missing RBAC role | 403 | "Access denied. Required roles: ..." | -| Empty roles list | 403 | "User has no assigned roles" | -| Validation error (Pydantic) | 422 | FastAPI auto-generated validation detail | -| Invalid MIME type | 400 | "Unsupported file type: ..." | -| File too large | 400 | "File exceeds ...MB limit" | -| Quota exceeded | 403 | QuotaExceededModel JSON | -| Resource not found | 404 | "... not found ..." | -| Server error | 500 | "Failed to ..." | - -## Testing Strategy - -### Dual Testing Approach - -This feature uses both unit tests (specific examples) and property-based tests (universal properties) as complementary strategies: - -- **Unit tests** (per-module test files): Verify specific examples, edge cases, and error conditions for each route. These cover the majority of acceptance criteria (Requirements 2–15) with concrete request/response assertions. -- **Property-based tests** (Hypothesis): Verify universal properties across randomly generated inputs. These cover Requirements 3.3, 4.2, 4.3, 7.2, 16.1–16.3, and 17.1–17.2 with 100+ iterations per property. - -Together they provide comprehensive coverage — unit tests catch concrete bugs in specific scenarios, property tests verify general correctness across the input space. - -### Property-Based Testing Configuration - -- **Library**: [Hypothesis](https://hypothesis.readthedocs.io/) (already in `pyproject.toml` dev dependencies as `hypothesis>=6.0.0`) -- **Minimum iterations**: 100 per property test via `@settings(max_examples=100)` -- **Each correctness property is implemented by a single `@given` test function** -- **Tag format**: Each test includes a docstring comment referencing the design property: - ```python - @given(...) - @settings(max_examples=100) - def test_invalid_mime_type_rejection(mime_type): - """Feature: api-route-tests, Property 2: Invalid MIME type rejection""" - ``` - -### Test Organization - -| Test File | Requirements | Type | Key Assertions | -|-----------|-------------|------|----------------| -| `test_health.py` | 2.1–2.3 | Unit | 200, response fields | -| `test_sessions.py` | 3.1–3.8 | Unit | 200, 401, pagination | -| `test_files.py` | 4.1–4.10 | Unit | 200, 204, 400, 403, 404 | -| `test_chat.py` | 5.1–5.4 | Unit | 200, 401, content-type | -| `test_auth.py` | 6.1–6.4 | Unit | 200, 400/401 | -| `test_admin.py` | 7.1–7.7 | Unit | 200, 401, 403 | -| `test_tools.py` | 8.1–8.2 | Unit | 200, 401 | -| `test_memory.py` | 9.1–9.2 | Unit | 200, 401 | -| `test_costs.py` | 10.1–10.2 | Unit | 200, 401 | -| `test_users.py` | 11.1–11.2 | Unit | 200, 401 | -| `test_models.py` | 12.1–12.2 | Unit | 200, 401 | -| `test_assistants.py` | 13.1–13.2 | Unit | 200, 401 | -| `test_documents.py` | 14.1–14.2 | Unit | 200, 401 | -| `test_inference.py` | 15.1–15.3 | Unit | 200, 422, streaming | -| `test_pbt_request_validation.py` | 16.1–16.3, 3.3, 4.2, 4.3 | Property | Properties 1–3, 5–6 | -| `test_pbt_auth_sweep.py` | 17.1–17.3, 7.2–7.3 | Property + Unit | Properties 4, 7 | - -### Running Tests - -All test commands must run inside the Docker container: - -```bash -# Run all route tests -docker compose exec dev bash -c "cd /workspace/bsu-org/agentcore-public-stack/backend && python -m pytest tests/routes/ -v" - -# Run a specific module -docker compose exec dev bash -c "cd /workspace/bsu-org/agentcore-public-stack/backend && python -m pytest tests/routes/test_sessions.py -v" - -# Run only property-based tests -docker compose exec dev bash -c "cd /workspace/bsu-org/agentcore-public-stack/backend && python -m pytest tests/routes/test_pbt_*.py -v" - -# Run with coverage -docker compose exec dev bash -c "cd /workspace/bsu-org/agentcore-public-stack/backend && python -m pytest tests/routes/ -v --cov=src/apis" -``` diff --git a/.kiro/specs/api-route-tests/requirements.md b/.kiro/specs/api-route-tests/requirements.md deleted file mode 100644 index 30bc8465..00000000 --- a/.kiro/specs/api-route-tests/requirements.md +++ /dev/null @@ -1,207 +0,0 @@ -# Requirements Document - -## Introduction - -The AgentCore Public Stack backend has 15+ API route modules across two FastAPI applications (App API on port 8000, Inference API on port 8001) with zero route-level test coverage. This feature adds comprehensive API route tests using FastAPI TestClient, pytest-asyncio, and Hypothesis. The goal is to validate HTTP status codes, authentication enforcement, RBAC authorization, request validation, error handling, and response schemas for every route module. Tests will mock external dependencies (DynamoDB, S3, Bedrock, MCP) so they run fast and deterministically. - -## Glossary - -- **App_API**: The primary FastAPI application serving user-facing endpoints on port 8000 (sessions, files, chat, admin, etc.) -- **Inference_API**: The secondary FastAPI application serving AgentCore Runtime endpoints on port 8001 (ping, invocations, converse) -- **TestClient**: The `httpx.AsyncClient` or `fastapi.testclient.TestClient` used to send HTTP requests to a FastAPI app in tests without starting a real server -- **Route_Module**: A Python module containing FastAPI router definitions for a specific domain (e.g., `sessions/routes.py`, `files/routes.py`) -- **Auth_Dependency**: The `get_current_user` FastAPI dependency that extracts and validates JWT tokens, returning a `User` object -- **RBAC_Guard**: The `require_roles` or `require_all_roles` FastAPI dependency that checks user roles before granting access to a route -- **Dependency_Override**: FastAPI's `app.dependency_overrides` mechanism for replacing real dependencies with mocks during testing -- **Test_Fixture**: A pytest fixture providing reusable test setup such as mock users, authenticated clients, or service mocks -- **Hypothesis**: A property-based testing library that generates random inputs to find edge cases -- **Route_Test**: A test that sends an HTTP request to a route endpoint and asserts on the response status code, body, and headers - - -## Requirements - -### Requirement 1: Shared Test Infrastructure - -**User Story:** As a developer, I want reusable test fixtures and helpers for API route testing, so that I can write route tests consistently without duplicating mock setup across every module. - -#### Acceptance Criteria - -1. THE Test_Infrastructure SHALL provide a pytest fixture that creates an authenticated TestClient with Auth_Dependency overridden to return a configurable mock User -2. THE Test_Infrastructure SHALL provide a pytest fixture that creates an unauthenticated TestClient with no Auth_Dependency override -3. THE Test_Infrastructure SHALL provide factory fixtures for creating mock User objects with configurable user_id, email, and roles -4. THE Test_Infrastructure SHALL provide a pytest fixture that creates a TestClient with RBAC_Guard overridden to simulate users with specific roles -5. WHEN a test requires a mocked external service (DynamoDB, S3, Bedrock), THE Test_Infrastructure SHALL provide Dependency_Override fixtures that replace service dependencies with async mocks -6. THE Test_Infrastructure SHALL reside in a shared conftest.py accessible to all route test modules - -### Requirement 2: Health Endpoint Tests - -**User Story:** As a developer, I want tests for the health check endpoint, so that I can verify the service readiness probe works correctly. - -#### Acceptance Criteria - -1. WHEN a GET request is sent to /health, THE App_API SHALL return HTTP 200 with a JSON body containing "status", "service", and "version" fields -2. THE health response "status" field SHALL contain the value "healthy" -3. WHEN a GET request is sent to /ping, THE Inference_API SHALL return HTTP 200 - -### Requirement 3: Session Route Tests - -**User Story:** As a developer, I want tests for all session management routes, so that I can verify session CRUD operations, pagination, and access control. - -#### Acceptance Criteria - -1. WHEN an authenticated user sends GET /sessions, THE App_API SHALL return HTTP 200 with a paginated list of sessions belonging to that user -2. WHEN an unauthenticated request is sent to GET /sessions, THE App_API SHALL return HTTP 401 -3. WHEN an authenticated user sends GET /sessions with a valid limit parameter, THE App_API SHALL return at most that many sessions -4. WHEN an authenticated user sends GET /sessions/{session_id} for a session they own, THE App_API SHALL return HTTP 200 with session metadata -5. WHEN an authenticated user sends PUT /sessions/{session_id} with valid update data, THE App_API SHALL return HTTP 200 with updated metadata -6. WHEN an authenticated user sends DELETE /sessions/{session_id} for a session they own, THE App_API SHALL return HTTP 200 -7. WHEN an authenticated user sends POST /sessions/bulk-delete with a list of session IDs, THE App_API SHALL return HTTP 200 with deletion results -8. WHEN an authenticated user sends GET /sessions/{session_id}/messages, THE App_API SHALL return HTTP 200 with the message history for that session - -### Requirement 4: File Route Tests - -**User Story:** As a developer, I want tests for file upload, listing, deletion, and quota routes, so that I can verify the file management lifecycle and quota enforcement. - -#### Acceptance Criteria - -1. WHEN an authenticated user sends POST /files/presign with a valid PresignRequest, THE App_API SHALL return HTTP 200 with a presigned URL and upload ID -2. WHEN an authenticated user sends POST /files/presign with an unsupported MIME type, THE App_API SHALL return HTTP 400 -3. WHEN an authenticated user sends POST /files/presign with a file exceeding the size limit, THE App_API SHALL return HTTP 400 -4. WHEN an authenticated user sends POST /files/presign and the user quota is exceeded, THE App_API SHALL return HTTP 403 -5. WHEN an authenticated user sends POST /files/{upload_id}/complete for a valid upload, THE App_API SHALL return HTTP 200 -6. WHEN an authenticated user sends POST /files/{upload_id}/complete for a nonexistent upload, THE App_API SHALL return HTTP 404 -7. WHEN an authenticated user sends GET /files, THE App_API SHALL return HTTP 200 with a paginated file list -8. WHEN an authenticated user sends DELETE /files/{upload_id} for a file they own, THE App_API SHALL return HTTP 204 -9. WHEN an authenticated user sends DELETE /files/{upload_id} for a nonexistent file, THE App_API SHALL return HTTP 404 -10. WHEN an authenticated user sends GET /files/quota, THE App_API SHALL return HTTP 200 with quota usage data - -### Requirement 5: Chat Route Tests - -**User Story:** As a developer, I want tests for chat and title generation routes, so that I can verify chat request handling and streaming response initiation. - -#### Acceptance Criteria - -1. WHEN an authenticated user sends POST /chat/title with a valid GenerateTitleRequest, THE App_API SHALL return HTTP 200 with a generated title -2. WHEN an unauthenticated request is sent to POST /chat/title, THE App_API SHALL return HTTP 401 -3. WHEN an authenticated user sends POST /chat/stream with a valid ChatRequest, THE App_API SHALL return a streaming response with content-type text/event-stream -4. WHEN an authenticated user sends POST /chat/multimodal with a valid ChatRequest, THE App_API SHALL return a streaming response - -### Requirement 6: Authentication Route Tests - -**User Story:** As a developer, I want tests for authentication routes, so that I can verify login flows, provider listing, and token handling. - -#### Acceptance Criteria - -1. WHEN a GET request is sent to the auth providers endpoint, THE App_API SHALL return HTTP 200 with a list of configured authentication providers -2. WHEN no authentication providers are configured, THE App_API SHALL return HTTP 200 with an empty list -3. WHEN a valid authentication callback is received, THE App_API SHALL process the callback and return appropriate tokens -4. IF an invalid or expired callback state is received, THEN THE App_API SHALL return HTTP 400 or HTTP 401 - -### Requirement 7: Admin Route Tests with RBAC - -**User Story:** As a developer, I want tests for admin routes, so that I can verify that RBAC guards correctly restrict access and that admin operations work for authorized users. - -#### Acceptance Criteria - -1. WHEN a user with Admin role sends a request to an admin endpoint, THE App_API SHALL return HTTP 200 with the requested data -2. WHEN a user without Admin role sends a request to an admin endpoint, THE App_API SHALL return HTTP 403 -3. WHEN a user with no roles sends a request to an admin endpoint, THE App_API SHALL return HTTP 403 -4. WHEN an unauthenticated request is sent to an admin endpoint, THE App_API SHALL return HTTP 401 -5. WHEN an admin user sends GET to the managed models endpoint, THE App_API SHALL return HTTP 200 with a list of models -6. WHEN an admin user sends POST to create a managed model with valid data, THE App_API SHALL return HTTP 200 with the created model -7. WHEN an admin user sends DELETE to remove a managed model, THE App_API SHALL return HTTP 200 - -### Requirement 8: Tools Route Tests - -**User Story:** As a developer, I want tests for tool discovery and management routes, so that I can verify tool listing and permission handling. - -#### Acceptance Criteria - -1. WHEN an authenticated user sends GET /tools, THE App_API SHALL return HTTP 200 with a list of available tools -2. WHEN an unauthenticated request is sent to GET /tools, THE App_API SHALL return HTTP 401 - -### Requirement 9: Memory Route Tests - -**User Story:** As a developer, I want tests for memory management routes, so that I can verify memory retrieval and management operations. - -#### Acceptance Criteria - -1. WHEN an authenticated user sends a request to a memory endpoint, THE App_API SHALL return HTTP 200 with memory data -2. WHEN an unauthenticated request is sent to a memory endpoint, THE App_API SHALL return HTTP 401 - -### Requirement 10: Costs Route Tests - -**User Story:** As a developer, I want tests for cost tracking routes, so that I can verify cost data retrieval for users. - -#### Acceptance Criteria - -1. WHEN an authenticated user sends a request to the costs endpoint, THE App_API SHALL return HTTP 200 with cost data for that user -2. WHEN an unauthenticated request is sent to the costs endpoint, THE App_API SHALL return HTTP 401 - -### Requirement 11: Users Route Tests - -**User Story:** As a developer, I want tests for user profile routes, so that I can verify user data retrieval and updates. - -#### Acceptance Criteria - -1. WHEN an authenticated user sends a request to the users endpoint, THE App_API SHALL return HTTP 200 with user profile data -2. WHEN an unauthenticated request is sent to the users endpoint, THE App_API SHALL return HTTP 401 - -### Requirement 12: Models Route Tests - -**User Story:** As a developer, I want tests for the models listing route, so that I can verify model discovery works correctly. - -#### Acceptance Criteria - -1. WHEN an authenticated user sends GET /models, THE App_API SHALL return HTTP 200 with available model data -2. WHEN an unauthenticated request is sent to GET /models, THE App_API SHALL return HTTP 401 - -### Requirement 13: Assistants Route Tests - -**User Story:** As a developer, I want tests for assistant configuration routes, so that I can verify assistant CRUD operations. - -#### Acceptance Criteria - -1. WHEN an authenticated user sends a request to the assistants endpoint, THE App_API SHALL return HTTP 200 with assistant data -2. WHEN an unauthenticated request is sent to the assistants endpoint, THE App_API SHALL return HTTP 401 - -### Requirement 14: Documents Route Tests - -**User Story:** As a developer, I want tests for document management routes, so that I can verify document operations. - -#### Acceptance Criteria - -1. WHEN an authenticated user sends a request to the documents endpoint, THE App_API SHALL return HTTP 200 with document data -2. WHEN an unauthenticated request is sent to the documents endpoint, THE App_API SHALL return HTTP 401 - -### Requirement 15: Inference API Route Tests - -**User Story:** As a developer, I want tests for the Inference API endpoints, so that I can verify the AgentCore Runtime contract (ping and invocations). - -#### Acceptance Criteria - -1. WHEN a GET request is sent to /ping, THE Inference_API SHALL return HTTP 200 -2. WHEN a POST request is sent to /invocations with a valid payload, THE Inference_API SHALL return a streaming response -3. WHEN a POST request is sent to /invocations with an invalid payload, THE Inference_API SHALL return HTTP 422 - -### Requirement 16: Request Validation with Property-Based Testing - -**User Story:** As a developer, I want property-based tests for request validation, so that I can verify routes reject malformed inputs across a wide range of generated payloads. - -#### Acceptance Criteria - -1. FOR ALL randomly generated invalid session IDs, WHEN sent to GET /sessions/{session_id}, THE App_API SHALL return HTTP 404 or HTTP 422 -2. FOR ALL randomly generated PresignRequest payloads with invalid MIME types, WHEN sent to POST /files/presign, THE App_API SHALL return HTTP 400 -3. FOR ALL randomly generated payloads missing required fields, WHEN sent to a route expecting a request body, THE App_API SHALL return HTTP 422 - -### Requirement 17: Authentication Enforcement Across All Routes - -**User Story:** As a developer, I want a systematic test that verifies every protected route rejects unauthenticated requests, so that I can be confident no route accidentally exposes data without auth. - -#### Acceptance Criteria - -1. FOR ALL protected routes in App_API, WHEN an unauthenticated request is sent, THE App_API SHALL return HTTP 401 -2. FOR ALL protected routes in App_API, WHEN a request with an expired or invalid token is sent, THE App_API SHALL return HTTP 401 -3. THE health endpoint SHALL remain accessible without authentication - - diff --git a/.kiro/specs/api-route-tests/tasks.md b/.kiro/specs/api-route-tests/tasks.md deleted file mode 100644 index c9b2fa4e..00000000 --- a/.kiro/specs/api-route-tests/tasks.md +++ /dev/null @@ -1,187 +0,0 @@ -# Implementation Plan: API Route Tests - -## Overview - -Add comprehensive route-level tests for all App API and Inference API endpoints. Tests use FastAPI TestClient with dependency overrides for auth, RBAC, and service mocks. Property-based tests (Hypothesis) cover request validation and auth enforcement. Each test module creates a minimal FastAPI app mounting only the router under test, following the established pattern in `tests/auth/test_auth_routes.py`. - -## Tasks - -- [x] 1. Set up shared test infrastructure - - [x] 1.1 Create `backend/tests/routes/__init__.py` and `backend/tests/routes/conftest.py` with shared fixtures - - Implement `make_user` factory fixture (configurable email, user_id, name, roles) - - Implement `mock_auth_user(app, user)` helper to override `get_current_user` - - Implement `mock_no_auth(app)` helper to override `get_current_user` with 401 - - Implement `authenticated_client(app, user)` fixture returning TestClient with auth - - Implement `unauthenticated_client(app)` fixture returning TestClient without auth override - - Implement `admin_client(app)` fixture returning TestClient with admin-role user - - Implement `mock_service(app, dependency, mock)` helper for overriding any Depends() - - _Requirements: 1.1, 1.2, 1.3, 1.4, 1.5, 1.6_ - -- [x] 2. Implement health and auth route tests - - [x] 2.1 Create `backend/tests/routes/test_health.py` - - Test GET /health returns 200 with "status", "service", "version" fields - - Test health response "status" field equals "healthy" - - Test Inference API GET /ping returns 200 - - _Requirements: 2.1, 2.2, 2.3_ - - - [x] 2.2 Create `backend/tests/routes/test_auth.py` - - Test GET auth providers returns 200 with provider list - - Test GET auth providers returns 200 with empty list when none configured - - Test valid auth callback returns tokens - - Test invalid/expired callback returns 400 or 401 - - _Requirements: 6.1, 6.2, 6.3, 6.4_ - -- [x] 3. Checkpoint - Ensure infrastructure and basic tests pass - - Ensure all tests pass, ask the user if questions arise. - -- [x] 4. Implement session and file route tests - - [x] 4.1 Create `backend/tests/routes/test_sessions.py` - - Test GET /sessions returns 200 with paginated session list for authenticated user - - Test GET /sessions returns 401 for unauthenticated request - - Test GET /sessions with valid limit parameter returns at most N sessions - - Test GET /sessions/{session_id} returns 200 with session metadata - - Test PUT /sessions/{session_id} returns 200 with updated metadata - - Test DELETE /sessions/{session_id} returns 200 - - Test POST /sessions/bulk-delete returns 200 with deletion results - - Test GET /sessions/{session_id}/messages returns 200 with message history - - _Requirements: 3.1, 3.2, 3.3, 3.4, 3.5, 3.6, 3.7, 3.8_ - - - [x] 4.2 Create `backend/tests/routes/test_files.py` - - Test POST /files/presign with valid request returns 200 with presigned URL - - Test POST /files/presign with unsupported MIME type returns 400 - - Test POST /files/presign with oversized file returns 400 - - Test POST /files/presign with exceeded quota returns 403 - - Test POST /files/{upload_id}/complete for valid upload returns 200 - - Test POST /files/{upload_id}/complete for nonexistent upload returns 404 - - Test GET /files returns 200 with paginated file list - - Test DELETE /files/{upload_id} for owned file returns 204 - - Test DELETE /files/{upload_id} for nonexistent file returns 404 - - Test GET /files/quota returns 200 with quota usage data - - _Requirements: 4.1, 4.2, 4.3, 4.4, 4.5, 4.6, 4.7, 4.8, 4.9, 4.10_ - -- [x] 5. Implement chat and admin route tests - - [x] 5.1 Create `backend/tests/routes/test_chat.py` - - Test POST /chat/title with valid request returns 200 with generated title - - Test POST /chat/title returns 401 for unauthenticated request - - Test POST /chat/stream returns streaming response with text/event-stream content-type - - Test POST /chat/multimodal returns streaming response - - _Requirements: 5.1, 5.2, 5.3, 5.4_ - - - [x] 5.2 Create `backend/tests/routes/test_admin.py` - - Test admin endpoint returns 200 for user with Admin role - - Test admin endpoint returns 403 for user without Admin role - - Test admin endpoint returns 403 for user with no roles - - Test admin endpoint returns 401 for unauthenticated request - - Test GET managed models returns 200 with model list for admin - - Test POST create managed model returns 200 for admin - - Test DELETE managed model returns 200 for admin - - _Requirements: 7.1, 7.2, 7.3, 7.4, 7.5, 7.6, 7.7_ - -- [x] 6. Checkpoint - Ensure session, file, chat, and admin tests pass - - Ensure all tests pass, ask the user if questions arise. - -- [x] 7. Implement remaining module route tests - - [x] 7.1 Create `backend/tests/routes/test_tools.py` - - Test GET /tools returns 200 with tool list for authenticated user - - Test GET /tools returns 401 for unauthenticated request - - _Requirements: 8.1, 8.2_ - - - [x] 7.2 Create `backend/tests/routes/test_memory.py` - - Test memory endpoint returns 200 with memory data for authenticated user - - Test memory endpoint returns 401 for unauthenticated request - - _Requirements: 9.1, 9.2_ - - - [x] 7.3 Create `backend/tests/routes/test_costs.py` - - Test costs endpoint returns 200 with cost data for authenticated user - - Test costs endpoint returns 401 for unauthenticated request - - _Requirements: 10.1, 10.2_ - - - [x] 7.4 Create `backend/tests/routes/test_users.py` - - Test users endpoint returns 200 with user profile for authenticated user - - Test users endpoint returns 401 for unauthenticated request - - _Requirements: 11.1, 11.2_ - - - [x] 7.5 Create `backend/tests/routes/test_models.py` - - Test GET /models returns 200 with model data for authenticated user - - Test GET /models returns 401 for unauthenticated request - - _Requirements: 12.1, 12.2_ - - - [x] 7.6 Create `backend/tests/routes/test_assistants.py` - - Test assistants endpoint returns 200 with assistant data for authenticated user - - Test assistants endpoint returns 401 for unauthenticated request - - _Requirements: 13.1, 13.2_ - - - [x] 7.7 Create `backend/tests/routes/test_documents.py` - - Test documents endpoint returns 200 with document data for authenticated user - - Test documents endpoint returns 401 for unauthenticated request - - _Requirements: 14.1, 14.2_ - - - [x] 7.8 Create `backend/tests/routes/test_inference.py` - - Test GET /ping returns 200 - - Test POST /invocations with valid payload returns streaming response - - Test POST /invocations with invalid payload returns 422 - - _Requirements: 15.1, 15.2, 15.3_ - -- [x] 8. Checkpoint - Ensure all per-module route tests pass - - Ensure all tests pass, ask the user if questions arise. - -- [x] 9. Implement property-based request validation tests - - [x] 9.1 Create `backend/tests/routes/test_pbt_request_validation.py` with Hypothesis strategies - - Set up Hypothesis configuration with `@settings(max_examples=100)` - - _Requirements: 16.1, 16.2, 16.3_ - - - [x] 9.2 Write property test for pagination limit invariant - - **Property 1: Pagination limit invariant** - - For any valid limit N (1 ≤ N ≤ 1000) and mock session list, GET /sessions with limit=N returns at most N sessions - - **Validates: Requirements 3.3** - - - [x] 9.3 Write property test for invalid MIME type rejection - - **Property 2: Invalid MIME type rejection** - - For any MIME type string not in ALLOWED_MIME_TYPES, POST /files/presign returns HTTP 400 - - **Validates: Requirements 4.2, 16.2** - - - [x] 9.4 Write property test for oversized file rejection - - **Property 3: Oversized file rejection** - - For any file size > MAX_FILE_SIZE, POST /files/presign returns HTTP 400 - - **Validates: Requirements 4.3** - - - [x] 9.5 Write property test for invalid session ID rejection - - **Property 5: Invalid session ID rejection** - - For any random string as session_id where lookup returns no result, GET /sessions/{session_id}/metadata returns 404 or 422 - - **Validates: Requirements 16.1** - - - [x] 9.6 Write property test for missing required fields rejection - - **Property 6: Missing required fields rejection** - - For any JSON object missing required fields, the route returns HTTP 422 - - **Validates: Requirements 16.3** - -- [x] 10. Implement auth sweep and RBAC property tests - - [x] 10.1 Create `backend/tests/routes/test_pbt_auth_sweep.py` with route introspection - - Import full App API app from `apis.app_api.main` - - Discover all APIRoute objects via `app.routes` - - Define known public routes to exclude (/health, /auth/providers, /auth/login, etc.) - - _Requirements: 17.1, 17.2, 17.3_ - - - [x] 10.2 Write property test for non-admin role rejection - - **Property 4: Non-admin role rejection** - - For any User whose roles do not contain "Admin", "SuperAdmin", or "DotNetDevelopers", admin endpoints return HTTP 403 - - **Validates: Requirements 7.2, 7.3** - - - [x] 10.3 Write parametrized test for auth enforcement across all protected routes - - **Property 7: Auth enforcement across all protected routes** - - For each protected route discovered via introspection, unauthenticated request returns HTTP 401 - - Verify health endpoint remains accessible without auth - - **Validates: Requirements 17.1, 17.2, 17.3** - -- [x] 11. Final checkpoint - Ensure all tests pass - - Run full route test suite: `docker compose exec dev bash -c "cd /workspace/bsu-org/agentcore-public-stack/backend && python -m pytest tests/routes/ -v"` - - Ensure all tests pass, ask the user if questions arise. - -## Notes - -- Tasks marked with `*` are optional and can be skipped for faster MVP -- Each task references specific requirements for traceability -- Checkpoints ensure incremental validation -- Property tests validate universal correctness properties from the design document -- Unit tests validate specific examples and edge cases -- All test commands must run inside Docker: `docker compose exec dev ` diff --git a/.kiro/specs/auth-rbac-tests/.config.kiro b/.kiro/specs/auth-rbac-tests/.config.kiro deleted file mode 100644 index 2d7de462..00000000 --- a/.kiro/specs/auth-rbac-tests/.config.kiro +++ /dev/null @@ -1 +0,0 @@ -{"specId": "83305357-3aa6-4fff-b924-5b087888786d", "workflowType": "requirements-first", "specType": "feature"} \ No newline at end of file diff --git a/.kiro/specs/auth-rbac-tests/design.md b/.kiro/specs/auth-rbac-tests/design.md deleted file mode 100644 index 9dc23654..00000000 --- a/.kiro/specs/auth-rbac-tests/design.md +++ /dev/null @@ -1,478 +0,0 @@ -# Design Document: Auth & RBAC Test Suite - -## Overview - -This design covers comprehensive test coverage for the Auth & RBAC modules in the AgentCore Public Stack. The modules under test are the highest-risk untested surface in the system — zero tests currently exist for JWT validation, role guards, or access control. - -The test suite spans two platforms: -- **Backend (Python):** pytest + pytest-asyncio for unit/integration tests, Hypothesis for property-based tests -- **Frontend (Angular/TypeScript):** Vitest for unit tests, fast-check for property-based tests - -The scope includes 15 requirements covering: JWT validation, legacy code removal, FastAPI auth dependencies, RBAC role checkers, AppRole permission resolution, AppRole admin CRUD, cache TTL/invalidation, OIDC state management, PKCE generation, OIDC auth service flows, auth route integration tests, and frontend auth service/guard/interceptor tests. - -A key prerequisite across all requirements is a docstring/comment audit of each module before writing tests, ensuring documentation accurately reflects current behavior. - -## Architecture - -The auth and RBAC system is layered across backend and frontend: - -```mermaid -graph TD - subgraph Frontend["Frontend (Angular)"] - AI[authInterceptor] -->|attaches Bearer token| AS[AuthService] - EI[errorInterceptor] -->|delegates errors| ES[ErrorService] - AG[authGuard] -->|checks auth| AS - ADG[adminGuard] -->|checks roles| US[UserService] - ADG -->|checks auth| AS - end - - subgraph Backend_Routes["Backend Routes (FastAPI)"] - AR[Auth Routes
/auth/*] -->|delegates| OAS[GenericOIDCAuthService] - AR -->|uses| SS[StateStore] - end - - subgraph Backend_Auth["Backend Auth Layer"] - DEP[Auth Dependencies
get_current_user
get_current_user_trusted] -->|validates via| GJV[GenericOIDCJWTValidator] - GJV -->|fetches keys| JWKS[JWKS Endpoint] - GJV -->|matches| PR[AuthProviderRepository] - OAS -->|PKCE, state| SS - end - - subgraph Backend_RBAC["Backend RBAC Layer"] - RC[RBAC Checkers
require_roles
require_all_roles] -->|depends on| DEP - ARS[AppRoleService] -->|resolves permissions| REPO[AppRoleRepository] - ARS -->|caches| ARC[AppRoleCache] - ARAS[AppRoleAdminService] -->|CRUD| REPO - ARAS -->|invalidates| ARC - end - - Frontend -->|HTTP + Bearer| Backend_Routes - Backend_Routes -->|auth dependency| Backend_Auth - Backend_Auth -->|role checks| Backend_RBAC -``` - -### Test Architecture - -Tests are organized by module, with each requirement mapping to one or more test files: - -``` -backend/tests/ -├── conftest.py # Shared fixtures (User factory, mock providers) -├── auth/ -│ ├── conftest.py # Auth-specific fixtures -│ ├── test_generic_jwt_validator.py # Req 1: JWT validation -│ ├── test_dependencies.py # Req 3: FastAPI auth deps -│ ├── test_rbac.py # Req 4: Role checkers -│ ├── test_state_store.py # Req 8: OIDC state store -│ ├── test_pkce.py # Req 9: PKCE generation -│ ├── test_oidc_auth_service.py # Req 10: OIDC auth flows -│ └── test_auth_routes.py # Req 11: Auth route integration -├── rbac/ -│ ├── conftest.py # RBAC-specific fixtures -│ ├── test_app_role_service.py # Req 5: Permission resolution -│ ├── test_app_role_admin_service.py # Req 6: Admin CRUD -│ └── test_app_role_cache.py # Req 7: Cache TTL -└── property/ - └── test_pbt_permissions.py # Req 15: Property-based tests - -frontend/ai.client/src/app/auth/ -├── auth.service.spec.ts # Req 12: AuthService tests -├── auth.guard.spec.ts # Req 13: authGuard tests -├── admin.guard.spec.ts # Req 13: adminGuard tests -├── auth.interceptor.spec.ts # Req 14: authInterceptor tests -├── error.interceptor.spec.ts # Req 14: errorInterceptor tests -└── auth-pbt.spec.ts # Req 15: Frontend PBT -``` - -## Components and Interfaces - -### Backend Components Under Test - -| Component | Source File | Test Approach | -|-----------|-----------|---------------| -| `GenericOIDCJWTValidator` | `shared/auth/generic_jwt_validator.py` | Unit tests with mocked JWKS/providers | -| `EntraIDJWTValidator` (legacy) | `shared/auth/jwt_validator.py` | Deletion verification (Req 2) | -| `get_current_user` / `get_current_user_trusted` | `shared/auth/dependencies.py` | Unit tests with mocked validator | -| `require_roles` / `require_all_roles` / `has_any_role` / `has_all_roles` | `shared/auth/rbac.py` | Unit tests + PBT | -| `AppRoleService` | `shared/rbac/service.py` | Unit tests with mocked repo/cache + PBT | -| `AppRoleAdminService` | `shared/rbac/admin_service.py` | Unit tests with mocked repo/cache | -| `AppRoleCache` | `shared/rbac/cache.py` | Unit tests with time manipulation | -| `InMemoryStateStore` | `shared/auth/state_store.py` | Unit tests + PBT | -| `generate_pkce_pair` | `app_api/auth/service.py` | Unit tests + PBT | -| `GenericOIDCAuthService` | `app_api/auth/service.py` | Unit tests with mocked HTTP | -| Auth Routes | `app_api/auth/routes.py` | Integration tests via FastAPI TestClient | - -### Frontend Components Under Test - -| Component | Source File | Test Approach | -|-----------|-----------|---------------| -| `AuthService` | `auth/auth.service.ts` | Vitest with mocked localStorage/HTTP | -| `authGuard` | `auth/auth.guard.ts` | Vitest with mocked AuthService/Router | -| `adminGuard` | `auth/admin.guard.ts` | Vitest with mocked AuthService/UserService/Router | -| `authInterceptor` | `auth/auth.interceptor.ts` | Vitest with mocked HttpHandler | -| `errorInterceptor` | `auth/error.interceptor.ts` | Vitest with mocked ErrorService | - -### Key Interfaces for Mocking - -**Backend mocks:** -- `AuthProviderRepository` — returns configured `AuthProvider` objects -- `AppRoleRepository` — returns `AppRole` objects, simulates DynamoDB -- `PyJWKClient` — returns signing keys for JWT verification -- `httpx.AsyncClient` — mocks token endpoint responses for OIDC flows -- `AppRoleCache` — in-memory cache (can use real instance or mock) - -**Frontend mocks:** -- `localStorage` / `sessionStorage` — token storage -- `HttpClient` (via `HttpTestingController` or manual mock) — API calls -- `Router` — navigation assertions -- `AuthService` / `UserService` — for guard tests -- `ErrorService` — for error interceptor tests - -## Data Models - -### Backend Models - -**`User`** (dataclass in `shared/auth/models.py`): -```python -@dataclass -class User: - email: str - user_id: str - name: str - roles: List[str] - picture: Optional[str] = None - raw_token: Optional[str] = None -``` - -**`AppRole`** (dataclass in `shared/rbac/models.py`): -```python -@dataclass -class AppRole: - role_id: str - display_name: str - description: str - jwt_role_mappings: List[str] - inherits_from: List[str] - effective_permissions: EffectivePermissions - granted_tools: List[str] - granted_models: List[str] - priority: int = 0 - is_system_role: bool = False - enabled: bool = True -``` - -**`EffectivePermissions`** (dataclass): -```python -@dataclass -class EffectivePermissions: - tools: List[str] - models: List[str] - quota_tier: Optional[str] = None -``` - -**`UserEffectivePermissions`** (dataclass): -```python -@dataclass -class UserEffectivePermissions: - user_id: str - app_roles: List[str] - tools: List[str] - models: List[str] - quota_tier: Optional[str] - resolved_at: str -``` - -**`OIDCStateData`** (dataclass in `shared/auth/state_store.py`): -```python -@dataclass -class OIDCStateData: - redirect_uri: Optional[str] = None - code_verifier: Optional[str] = None - nonce: Optional[str] = None - provider_id: Optional[str] = None -``` - -### Frontend Models - -**`User`** (interface in `auth/user.model.ts`): -```typescript -interface User { - email: string; - user_id: string; - firstName: string; - lastName: string; - fullName: string; - roles: string[]; - picture?: string; -} -``` - -### Test Data Generators (for PBT) - -**Hypothesis strategies (backend):** -- `st_user()` — generates `User` with random email, user_id, name, roles -- `st_app_role()` — generates `AppRole` with random tools, models, priority, enabled flag -- `st_oidc_state_data()` — generates `OIDCStateData` with random fields -- `st_role_list()` — generates `List[str]` of role names - -**fast-check arbitraries (frontend):** -- `arbRoleList()` — generates arrays of role name strings -- `arbToolList()` — generates arrays of tool ID strings - - -## Correctness Properties - -*A property is a characteristic or behavior that should hold true across all valid executions of a system — essentially, a formal statement about what the system should do. Properties serve as the bridge between human-readable specifications and machine-verifiable correctness guarantees.* - -### Property 1: Permission merge produces union of tools and models - -*For any* list of `AppRole` objects with arbitrary `effective_permissions.tools` and `effective_permissions.models` lists, calling `_merge_permissions()` shall produce a `tools` set that is a superset of every individual role's effective tools, and a `models` set that is a superset of every individual role's effective models. This includes wildcard (`"*"`) propagation — if any role contains `"*"` in its tools or models, the merged result must also contain `"*"`. - -**Validates: Requirements 5.2, 5.3, 5.7, 5.14, 15.2, 15.3** - -### Property 2: Permission merge is idempotent - -*For any* list of `AppRole` objects, merging permissions and then merging again with the same roles shall produce an identical `UserEffectivePermissions` result (same tools, models, and quota_tier). - -**Validates: Requirements 5.15, 15.4** - -### Property 3: Quota tier comes from highest-priority role - -*For any* list of `AppRole` objects with varying `priority` values and non-null `quota_tier` in their effective permissions, the `quota_tier` in the merged `UserEffectivePermissions` shall equal the `quota_tier` of the role with the highest `priority` value. - -**Validates: Requirements 5.4, 15.5** - -### Property 4: Wildcard grants universal tool access - -*For any* `User` whose resolved permissions contain `"*"` in the tools list, and *for any* `tool_id` string, `can_access_tool(user, tool_id)` shall return `True`. - -**Validates: Requirements 5.8** - -### Property 5: PKCE round-trip correctness - -*For any* PKCE pair generated by `generate_pkce_pair()`, the `code_verifier` shall be between 43 and 128 characters in length, and recomputing `BASE64URL(SHA256(code_verifier))` with padding stripped shall equal the returned `code_challenge`. - -**Validates: Requirements 9.2, 9.3, 9.4, 15.6** - -### Property 6: PKCE verifier uniqueness - -*For any* set of PKCE pairs generated by repeated calls to `generate_pkce_pair()`, all `code_verifier` values shall be distinct. - -**Validates: Requirements 9.5** - -### Property 7: State store round-trip - -*For any* state token string and `OIDCStateData` object, storing via `store_state()` and then retrieving via `get_and_delete_state()` shall return `(True, data)` where `data` has equivalent `redirect_uri`, `code_verifier`, `nonce`, and `provider_id` to the original. - -**Validates: Requirements 8.2, 8.7, 15.7** - -### Property 8: State store one-time-use - -*For any* state token stored in the `InMemoryStateStore`, after the first successful `get_and_delete_state()` call, a second call with the same state shall return `(False, None)`. - -**Validates: Requirements 8.3** - -### Property 9: has_any_role is set intersection - -*For any* `User` object with an arbitrary roles list and *for any* set of query roles, `has_any_role(user, *roles)` shall return `True` if and only if the intersection of `user.roles` and `roles` is non-empty. - -**Validates: Requirements 15.8** - -### Property 10: has_all_roles is subset check - -*For any* `User` object with an arbitrary roles list and *for any* set of query roles, `has_all_roles(user, *roles)` shall return `True` if and only if `roles` is a subset of `user.roles`. - -**Validates: Requirements 15.9** - -### Property 11: Dot-notation claim extraction traverses nested dicts - -*For any* nested dictionary and *for any* dot-notation path where each segment is a valid key at its level, `_extract_claim(payload, path)` shall return the value at the leaf of the path. - -**Validates: Requirements 1.21** - -## Error Handling - -### Backend Error Handling Strategy - -Tests must verify the following error patterns: - -| Error Condition | Expected Status | Expected Detail Pattern | -|----------------|----------------|------------------------| -| Invalid JWT signature | 401 | "Invalid token signature" | -| Expired JWT | 401 | "Token expired" | -| Issuer mismatch | 401 | — | -| Audience mismatch | 401 | "Invalid token audience" | -| Missing required scope | 401 | "Token missing required scope" | -| Invalid user_id pattern | 401 | "Invalid user." | -| Missing user_id claim | 401 | "Invalid user." | -| No credentials provided | 401 | WWW-Authenticate header present | -| Malformed token (trusted) | 401 | "Malformed token." | -| Auth service not configured | 500 | "Authentication service not configured" | -| Missing role (OR logic) | 403 | "Access denied. Required roles:" | -| Missing role (AND logic) | 403 | "Access denied. Missing required roles:" | -| Empty roles list | 403 | "User has no assigned roles." | -| Invalid OIDC state | 400 | "Invalid or expired state" | -| Nonce mismatch | 400 | "ID token nonce validation failed." | -| Expired refresh token | 401 | "Invalid or expired refresh token" | -| Non-existent parent role | ValueError | — | -| Duplicate role creation | ValueError | — | -| Delete system role | ValueError | "Cannot delete system role" | -| Update protected system role fields | ValueError | lists protected fields | - -### Frontend Error Handling Strategy - -| Error Condition | Expected Behavior | -|----------------|-------------------| -| No token, route guarded | Redirect to `/auth/login` with `returnUrl` | -| Expired token, refresh fails | Redirect to `/auth/login`, clear tokens | -| 401 response | Retry once with refreshed token | -| 401 retry fails | Clear tokens, propagate original error | -| HTTP error on non-streaming endpoint | `errorService.handleHttpError()` called | -| HTTP error on streaming endpoint | Error propagated without interception | -| HTTP error on silent endpoint | Error propagated without display | -| `ensureAuthenticated()` with no token | Throws `Error("not authenticated")` | - -### Mock Error Injection - -Backend tests use `unittest.mock.patch` and `AsyncMock` to inject errors: -- Mock `PyJWKClient.get_signing_key_from_jwt()` to raise `jwt.exceptions.InvalidSignatureError` -- Mock `httpx.AsyncClient.post()` to return error responses -- Mock `AppRoleRepository` methods to raise exceptions - -Frontend tests use Vitest mocks: -- Mock `AuthService.refreshAccessToken()` to reject -- Mock `HttpHandler` `next()` to return error observables -- Mock `localStorage` to return null/expired values - -## Testing Strategy - -### Dual Testing Approach - -This test suite uses both unit tests and property-based tests as complementary strategies: - -- **Unit tests** verify specific examples, edge cases, error conditions, and integration points. They cover the majority of acceptance criteria (concrete scenarios like "expired token → 401"). -- **Property-based tests** verify universal invariants across randomly generated inputs. They cover the 11 correctness properties defined above (union merging, idempotence, round-trips, set operations). - -Together they provide comprehensive coverage: unit tests catch concrete bugs at specific boundaries, property tests verify general correctness across the input space. - -### Backend Testing Stack - -- **Framework:** pytest + pytest-asyncio -- **PBT Library:** Hypothesis (do NOT implement PBT from scratch) -- **Mocking:** `unittest.mock.patch`, `AsyncMock`, `MagicMock` -- **HTTP Testing:** FastAPI `TestClient` for route integration tests -- **JWT Generation:** `PyJWT` to create test tokens signed with test RSA keys - -### Frontend Testing Stack - -- **Framework:** Vitest -- **PBT Library:** fast-check (do NOT implement PBT from scratch) -- **Angular Testing:** `TestBed` for DI, manual mocks for services -- **HTTP Mocking:** Manual mock of `HttpHandler` `next()` function - -### Property-Based Test Configuration - -- Each property test MUST run a minimum of **100 iterations** (Hypothesis: `@settings(max_examples=100)`, fast-check: `fc.assert(..., { numRuns: 100 })`) -- Each property test MUST be tagged with a comment referencing the design property: - - Backend format: `# Feature: auth-rbac-tests, Property {N}: {title}` - - Frontend format: `// Feature: auth-rbac-tests, Property {N}: {title}` -- Each correctness property MUST be implemented by a SINGLE property-based test - -### Hypothesis Strategies (Backend PBT) - -```python -from hypothesis import strategies as st - -# Role name strategy -st_role_name = st.text( - alphabet=st.characters(whitelist_categories=("L", "N"), whitelist_characters="_-"), - min_size=1, max_size=30 -) - -# Tool/model ID strategy -st_tool_id = st.text( - alphabet=st.characters(whitelist_categories=("L", "N"), whitelist_characters="_-:."), - min_size=1, max_size=50 -) - -# AppRole strategy -@st.composite -def st_app_role(draw): - return AppRole( - role_id=draw(st.text(min_size=3, max_size=20, alphabet=string.ascii_lowercase)), - display_name=draw(st.text(min_size=1, max_size=50)), - description="", - effective_permissions=EffectivePermissions( - tools=draw(st.lists(st_tool_id, max_size=10)), - models=draw(st.lists(st_tool_id, max_size=10)), - quota_tier=draw(st.one_of(st.none(), st.sampled_from(["free", "basic", "pro", "enterprise"]))), - ), - priority=draw(st.integers(min_value=0, max_value=999)), - enabled=True, - ) - -# User strategy -@st.composite -def st_user(draw): - return User( - email=draw(st.emails()), - user_id=draw(st.uuids().map(str)), - name=draw(st.text(min_size=1, max_size=50)), - roles=draw(st.lists(st_role_name, max_size=10)), - ) - -# OIDCStateData strategy -@st.composite -def st_oidc_state_data(draw): - return OIDCStateData( - redirect_uri=draw(st.one_of(st.none(), st.text(min_size=1, max_size=100))), - code_verifier=draw(st.one_of(st.none(), st.text(min_size=43, max_size=128))), - nonce=draw(st.one_of(st.none(), st.text(min_size=1, max_size=64))), - provider_id=draw(st.one_of(st.none(), st.text(min_size=1, max_size=30))), - ) -``` - -### fast-check Arbitraries (Frontend PBT) - -```typescript -import * as fc from 'fast-check'; - -const arbRoleName = fc.stringOf( - fc.constantFrom(...'abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789_-'.split('')), - { minLength: 1, maxLength: 30 } -); - -const arbRoleList = fc.array(arbRoleName, { maxLength: 10 }); -``` - -### Test File Mapping - -| Requirement | Test File | Type | -|------------|-----------|------| -| Req 1: JWT Validator | `backend/tests/auth/test_generic_jwt_validator.py` | Unit | -| Req 2: Legacy Removal | Verified by file deletion + grep | Manual | -| Req 3: Auth Dependencies | `backend/tests/auth/test_dependencies.py` | Unit | -| Req 4: RBAC Checkers | `backend/tests/auth/test_rbac.py` | Unit | -| Req 5: AppRoleService | `backend/tests/rbac/test_app_role_service.py` | Unit | -| Req 6: AppRoleAdminService | `backend/tests/rbac/test_app_role_admin_service.py` | Unit | -| Req 7: AppRoleCache | `backend/tests/rbac/test_app_role_cache.py` | Unit | -| Req 8: State Store | `backend/tests/auth/test_state_store.py` | Unit | -| Req 9: PKCE | `backend/tests/auth/test_pkce.py` | Unit | -| Req 10: OIDC Auth Service | `backend/tests/auth/test_oidc_auth_service.py` | Unit | -| Req 11: Auth Routes | `backend/tests/auth/test_auth_routes.py` | Integration | -| Req 12: FE AuthService | `frontend/ai.client/src/app/auth/auth.service.spec.ts` | Unit | -| Req 13: FE Guards | `frontend/ai.client/src/app/auth/auth.guard.spec.ts`, `admin.guard.spec.ts` | Unit | -| Req 14: FE Interceptors | `frontend/ai.client/src/app/auth/auth.interceptor.spec.ts`, `error.interceptor.spec.ts` | Unit | -| Req 15: PBT | `backend/tests/property/test_pbt_permissions.py`, `frontend/ai.client/src/app/auth/auth-pbt.spec.ts` | PBT | - -### Running Tests - -All commands must execute inside the Docker container: - -```bash -# Backend tests -docker compose exec dev bash -c "cd /workspace/bsu-org/agentcore-public-stack/backend && python -m pytest tests/auth/ tests/rbac/ tests/property/ -v" - -# Frontend tests -docker compose exec dev bash -c "cd /workspace/bsu-org/agentcore-public-stack/frontend/ai.client && npx vitest --run src/app/auth/" -``` diff --git a/.kiro/specs/auth-rbac-tests/requirements.md b/.kiro/specs/auth-rbac-tests/requirements.md deleted file mode 100644 index 22666b2c..00000000 --- a/.kiro/specs/auth-rbac-tests/requirements.md +++ /dev/null @@ -1,288 +0,0 @@ -# Requirements Document - -## Introduction - -The Auth & RBAC modules are the highest-risk untested surface in the AgentCore Public Stack. The Testing Posture Report rates this area as 🔴 Critical: zero tests on JWT validation, role guards, access control. This spec defines comprehensive test coverage for both backend (Python/pytest) and frontend (Angular/Vitest) auth and RBAC systems, including property-based testing where applicable. - -## Glossary - -- **JWT_Validator**: The `GenericOIDCJWTValidator` class that validates JWT tokens against dynamically configured OIDC providers, performing signature verification, issuer matching, audience checks, scope verification, and claim extraction. -- **Auth_Dependency**: The FastAPI dependency functions `get_current_user()`, `get_current_user_trusted()`, and `get_current_user_id()` that extract authenticated users from HTTP requests. -- **RBAC_Checker**: The role-checking utilities in `rbac.py` including `require_roles()`, `require_all_roles()`, `has_any_role()`, and `has_all_roles()`. -- **AppRole_Service**: The `AppRoleService` class that resolves user permissions by mapping JWT roles to AppRoles and merging tools, models, and quota tiers. -- **AppRole_Admin_Service**: The `AppRoleAdminService` class that handles CRUD operations on AppRoles with inheritance resolution, cache invalidation, and system role protection. -- **AppRole_Cache**: The `AppRoleCache` class providing in-memory TTL-based caching for roles, user permissions, and JWT-to-AppRole mappings. -- **State_Store**: The `StateStore` abstraction (`InMemoryStateStore`, `DynamoDBStateStore`) for OIDC state management with TTL expiration and one-time-use semantics. -- **Auth_Service_FE**: The Angular `AuthService` class managing token storage, OIDC login/logout flows, token refresh, and authentication state signals. -- **Auth_Guard**: The Angular `authGuard` CanActivateFn that protects routes requiring authentication. -- **Admin_Guard**: The Angular `adminGuard` CanActivateFn that protects admin routes requiring specific roles (Admin, SuperAdmin, DotNetDevelopers). -- **Auth_Interceptor**: The Angular `authInterceptor` HttpInterceptorFn that adds Bearer tokens to requests and handles 401 retry with token refresh. -- **Error_Interceptor**: The Angular `errorInterceptor` HttpInterceptorFn that catches HTTP errors from non-streaming requests and delegates to ErrorService. -- **PKCE**: Proof Key for Code Exchange (S256 method) used in the OIDC authorization code flow. -- **Auth_Routes**: The FastAPI router endpoints for `/auth/providers`, `/auth/login`, `/auth/token`, `/auth/refresh`, `/auth/logout`, and `/auth/runtime-endpoint`. -- **OIDC_Auth_Service**: The `GenericOIDCAuthService` class handling PKCE generation, state management, authorization URL building, token exchange, and token refresh. -- **Test_Suite**: The collection of pytest (backend) and Vitest (frontend) test files created by this feature. - -## Requirements - -### Requirement 1: GenericOIDCJWTValidator Token Validation Tests - -**User Story:** As a developer, I want comprehensive tests for the GenericOIDCJWTValidator, so that I can verify JWT signature verification, issuer matching, audience checks, scope enforcement, and claim extraction work correctly across multiple OIDC providers. - -#### Acceptance Criteria - -1. BEFORE writing tests, THE developer SHALL review all inline comments and docstrings in the `GenericOIDCJWTValidator` source file, verifying they accurately describe the current behavior, and update or remove any that are stale, misleading, or incorrect. -2. WHEN a token with a valid RS256 signature is provided, THE JWT_Validator SHALL decode the token and return a User object with correct email, user_id, name, and roles. -2. WHEN a token with an invalid signature is provided, THE JWT_Validator SHALL raise an HTTPException with status 401 and detail containing "Invalid token signature". -3. WHEN a token with an expired `exp` claim is provided, THE JWT_Validator SHALL raise an HTTPException with status 401 and detail containing "Token expired". -4. WHEN a token issuer matches the provider's `issuer_url` exactly, THE JWT_Validator SHALL accept the token as valid. -5. WHEN a token has an Entra ID v1 issuer (`https://sts.windows.net/{tenant}/`) and the provider has a v2 issuer (`https://login.microsoftonline.com/{tenant}/v2.0`), THE JWT_Validator SHALL accept the token via cross-version matching. -6. WHEN a token has an Entra ID v2 issuer and the provider has a v1 issuer, THE JWT_Validator SHALL accept the token via cross-version matching. -7. WHEN a token issuer does not match the provider issuer and no cross-version match exists, THE JWT_Validator SHALL raise an HTTPException with status 401. -8. WHEN the provider has `allowed_audiences` configured and the token audience is not in the list, THE JWT_Validator SHALL raise an HTTPException with status 401 and detail containing "Invalid token audience". -9. WHEN the provider has `allowed_audiences` configured and the token audience is a list containing at least one allowed audience, THE JWT_Validator SHALL accept the token. -10. WHEN the provider has `required_scopes` configured and the token `scp` claim is missing a required scope, THE JWT_Validator SHALL raise an HTTPException with status 401 and detail containing "Token missing required scope". -11. WHEN the provider has a `user_id_pattern` configured and the extracted user_id does not match the regex pattern, THE JWT_Validator SHALL raise an HTTPException with status 401 and detail "Invalid user.". -12. WHEN the provider has a `user_id_claim` pointing to a missing claim, THE JWT_Validator SHALL raise an HTTPException with status 401 and detail "Invalid user.". -13. WHEN the provider has `first_name_claim` and `last_name_claim` configured and the `name_claim` is absent, THE JWT_Validator SHALL construct the name from first and last name claims. -14. WHEN the token `roles` claim is a string instead of a list, THE JWT_Validator SHALL normalize the roles to a single-element list. -15. WHEN the `email` claim is absent but `preferred_username` is present, THE JWT_Validator SHALL use `preferred_username` as the email. -16. THE JWT_Validator SHALL cache PyJWKClient instances per JWKS URI so that repeated validations for the same provider reuse the client. -17. WHEN `resolve_provider_from_token()` is called with a valid token, THE JWT_Validator SHALL match the token issuer to an enabled provider and return the AuthProvider. -18. WHEN `resolve_provider_from_token()` is called with a token whose issuer matches no enabled provider, THE JWT_Validator SHALL return None. -19. WHEN `invalidate_cache()` is called, THE JWT_Validator SHALL clear both the issuer-to-provider cache and the JWKS client cache. -20. WHEN the `_extract_claim()` method receives a dot-notation claim path, THE JWT_Validator SHALL traverse nested dictionaries to extract the value. -21. WHEN the `_extract_claim()` method receives a URI-style claim path (e.g., `http://schemas.example.com/claims/id`), THE JWT_Validator SHALL perform a direct dictionary lookup. - -### Requirement 2: Remove Legacy EntraIDJWTValidator - -**User Story:** As a developer, I want the legacy `EntraIDJWTValidator` removed from the codebase, so that we eliminate dead code and reduce the auth surface area before production — the `GenericOIDCJWTValidator` already handles all OIDC providers including Entra ID. - -#### Acceptance Criteria - -1. BEFORE removal, THE developer SHALL review all inline comments and docstrings in `jwt_validator.py` and any files that import it, verifying comments accurately reflect the current state, and document all call sites in the PR description confirming none are actively used. -2. THE file `backend/src/apis/shared/auth/jwt_validator.py` SHALL be deleted entirely. -2. ALL import references to `EntraIDJWTValidator` or `get_validator` from `jwt_validator` SHALL be removed from the codebase. -3. THE `GenericOIDCJWTValidator` SHALL remain the sole JWT validation path, with no regression in functionality. -4. IF any module currently falls back to `EntraIDJWTValidator` when the generic validator is unavailable, THAT fallback SHALL be removed. -5. THE `__init__.py` or any re-exports referencing `jwt_validator` SHALL be updated to exclude the deleted module. -6. AFTER removal, all existing tests SHALL continue to pass without modification (confirming no runtime dependency on the legacy validator). - -### Requirement 3: FastAPI Auth Dependency Tests - -**User Story:** As a developer, I want tests for the FastAPI authentication dependencies, so that I can verify that `get_current_user()` correctly validates tokens via the generic validator, `get_current_user_trusted()` extracts claims without signature verification, and both handle edge cases properly. - -#### Acceptance Criteria - -1. BEFORE writing tests, THE developer SHALL review all inline comments and docstrings in the auth dependency functions (`get_current_user`, `get_current_user_trusted`, `get_current_user_id`), verifying they accurately describe the current behavior, and update or remove any that are stale, misleading, or incorrect. -2. WHEN `get_current_user()` receives valid Bearer credentials, THE Auth_Dependency SHALL resolve the provider from the token, validate the token, and return a User object with `raw_token` set. -2. WHEN `get_current_user()` receives no credentials (None), THE Auth_Dependency SHALL raise an HTTPException with status 401 and a `WWW-Authenticate: Bearer` header. -3. WHEN `get_current_user()` receives a token that fails validation, THE Auth_Dependency SHALL raise an HTTPException with status 401. -4. WHEN `get_current_user()` is called and no generic validator is available, THE Auth_Dependency SHALL raise an HTTPException with status 500 and detail containing "Authentication service not configured". -5. WHEN `get_current_user_trusted()` receives valid Bearer credentials, THE Auth_Dependency SHALL decode the JWT without signature verification and return a User object using provider-specific claim mappings. -6. WHEN `get_current_user_trusted()` receives a malformed token, THE Auth_Dependency SHALL raise an HTTPException with status 401 and detail "Malformed token.". -7. WHEN `get_current_user_trusted()` is called with no generic validator available, THE Auth_Dependency SHALL fall back to standard OIDC claims (`sub`, `email`, `name`, `roles`). -8. WHEN `get_current_user_trusted()` extracts a token with a missing `user_id` claim, THE Auth_Dependency SHALL raise an HTTPException with status 401 and detail "Invalid user.". -9. WHEN `get_current_user_id()` is called, THE Auth_Dependency SHALL return only the `user_id` string from the authenticated User. - -### Requirement 4: RBAC Role Checker Tests - -**User Story:** As a developer, I want tests for the RBAC role-checking utilities, so that I can verify OR-logic, AND-logic, predefined role checkers, and edge cases like empty role lists. - -#### Acceptance Criteria - -1. BEFORE writing tests, THE developer SHALL review all inline comments and docstrings in `rbac.py` for `require_roles()`, `require_all_roles()`, `has_any_role()`, `has_all_roles()`, and any predefined role checkers, verifying they accurately describe the current behavior, and update or remove any that are stale, misleading, or incorrect. -2. WHEN `require_roles("Admin", "SuperAdmin")` is used and the user has the "Admin" role, THE RBAC_Checker SHALL return the User object (access granted). -2. WHEN `require_roles("Admin", "SuperAdmin")` is used and the user has neither role, THE RBAC_Checker SHALL raise an HTTPException with status 403. -3. WHEN `require_all_roles("Admin", "Security")` is used and the user has both roles, THE RBAC_Checker SHALL return the User object (access granted). -4. WHEN `require_all_roles("Admin", "Security")` is used and the user is missing the "Security" role, THE RBAC_Checker SHALL raise an HTTPException with status 403 and detail listing the missing roles. -5. WHEN `require_roles()` or `require_all_roles()` is used and the user has an empty roles list, THE RBAC_Checker SHALL raise an HTTPException with status 403 and detail "User has no assigned roles.". -6. WHEN `has_any_role(user, "Admin", "Faculty")` is called and the user has "Faculty", THE RBAC_Checker SHALL return True. -7. WHEN `has_any_role(user, "Admin")` is called and the user has no matching role, THE RBAC_Checker SHALL return False. -8. WHEN `has_all_roles(user, "Admin", "Security")` is called and the user has both, THE RBAC_Checker SHALL return True. -9. WHEN `has_all_roles(user, "Admin", "Security")` is called and the user is missing one, THE RBAC_Checker SHALL return False. -10. WHEN `has_any_role()` or `has_all_roles()` is called with a user whose roles list is empty, THE RBAC_Checker SHALL return False. -11. THE RBAC_Checker predefined `require_admin` SHALL accept users with "Admin", "SuperAdmin", or "DotNetDevelopers" roles. - -### Requirement 5: AppRoleService Permission Resolution Tests - -**User Story:** As a developer, I want tests for the AppRoleService permission resolution, so that I can verify JWT-to-AppRole mapping, permission merging (union for tools/models, highest priority for quota), wildcard handling, caching, and default role fallback. - -#### Acceptance Criteria - -1. BEFORE writing tests, THE developer SHALL review all inline comments and docstrings in the `AppRoleService` source file, verifying they accurately describe the permission resolution pipeline, merge logic, caching behavior, wildcard handling, and default role fallback, and update or remove any that are stale, misleading, or incorrect. -2. WHEN a user has JWT roles that map to multiple AppRoles, THE AppRole_Service SHALL merge tools as a union of all roles' effective tools. -2. WHEN a user has JWT roles that map to multiple AppRoles, THE AppRole_Service SHALL merge models as a union of all roles' effective models. -3. WHEN a user has JWT roles that map to multiple AppRoles with different quota tiers, THE AppRole_Service SHALL select the quota tier from the highest-priority role. -4. WHEN a user has JWT roles that match no AppRoles, THE AppRole_Service SHALL fall back to the "default" role if it exists and is enabled. -5. WHEN a user has JWT roles that match no AppRoles and no default role exists, THE AppRole_Service SHALL return empty permissions. -6. WHEN any matching AppRole has a wildcard ("*") in its tools, THE AppRole_Service SHALL include "*" in the merged tools list. -7. WHEN `can_access_tool()` is called and the user's permissions contain "*" in tools, THE AppRole_Service SHALL return True for any tool_id. -8. WHEN `can_access_tool()` is called and the tool_id is in the user's tools list, THE AppRole_Service SHALL return True. -9. WHEN `can_access_tool()` is called and the tool_id is not in the user's tools list and no wildcard exists, THE AppRole_Service SHALL return False. -10. WHEN `resolve_user_permissions()` is called twice for the same user, THE AppRole_Service SHALL return the cached result on the second call without querying the repository. -11. WHEN the cache is empty and `resolve_user_permissions()` is called, THE AppRole_Service SHALL query the repository for JWT mappings and cache the results. -12. THE AppRole_Service SHALL only include enabled AppRoles when merging permissions. -13. FOR ALL sets of AppRoles with tools lists, merging permissions SHALL produce a tools list that is a superset of each individual role's tools (union property). -14. FOR ALL sets of AppRoles, merging permissions and then merging again with the same roles SHALL produce an identical result (idempotence property). - -### Requirement 6: AppRoleAdminService CRUD and Inheritance Tests - -**User Story:** As a developer, I want tests for the AppRoleAdminService, so that I can verify role creation, update, deletion, inheritance resolution, system role protection, and cache invalidation. - -#### Acceptance Criteria - -1. BEFORE writing tests, THE developer SHALL review all inline comments and docstrings in the `AppRoleAdminService` source file, verifying they accurately describe the CRUD lifecycle, inheritance resolution, system role protection rules, and cache invalidation triggers, and update or remove any that are stale, misleading, or incorrect. -2. WHEN `create_role()` is called with valid data, THE AppRole_Admin_Service SHALL create the role in the repository with computed effective permissions and return the created AppRole. -2. WHEN `create_role()` is called with an `inherits_from` list referencing a non-existent role, THE AppRole_Admin_Service SHALL raise a ValueError. -3. WHEN `create_role()` is called and the role already exists, THE AppRole_Admin_Service SHALL raise a ValueError. -4. WHEN `update_role()` is called on the "system_admin" role with fields other than `display_name` or `description`, THE AppRole_Admin_Service SHALL raise a ValueError listing the protected fields. -5. WHEN `delete_role()` is called on a system role, THE AppRole_Admin_Service SHALL raise a ValueError with detail "Cannot delete system role". -6. WHEN `delete_role()` is called on a non-system role, THE AppRole_Admin_Service SHALL delete the role and invalidate relevant caches. -7. WHEN a role inherits from a parent role, THE AppRole_Admin_Service SHALL compute effective permissions by merging the role's granted_tools with the parent's granted_tools (union). -8. WHEN `update_role()` modifies `jwt_role_mappings`, THE AppRole_Admin_Service SHALL invalidate the JWT mapping cache for affected mappings. -9. WHEN `add_tool_to_role()` is called with a tool not already in the role, THE AppRole_Admin_Service SHALL add the tool and recompute effective permissions. -10. WHEN `remove_tool_from_role()` is called with a tool in the role, THE AppRole_Admin_Service SHALL remove the tool and recompute effective permissions. - -### Requirement 7: AppRoleCache TTL and Invalidation Tests - -**User Story:** As a developer, I want tests for the AppRoleCache, so that I can verify TTL expiration, cache hit/miss behavior, and targeted invalidation. - -#### Acceptance Criteria - -1. BEFORE writing tests, THE developer SHALL review all inline comments and docstrings in the `AppRoleCache` source file, verifying they accurately describe each cache layer, the TTL mechanism, and the invalidation cascade behavior, and update or remove any that are stale, misleading, or incorrect. -2. WHEN a user permission entry is cached and retrieved before TTL expiration, THE AppRole_Cache SHALL return the cached value. -2. WHEN a user permission entry is cached and retrieved after TTL expiration, THE AppRole_Cache SHALL return None. -3. WHEN `invalidate_role()` is called, THE AppRole_Cache SHALL remove the role entry and clear all user permission caches. -4. WHEN `invalidate_jwt_mapping()` is called, THE AppRole_Cache SHALL remove the JWT mapping entry and clear all user permission caches. -5. WHEN `invalidate_all()` is called, THE AppRole_Cache SHALL clear all user, role, and JWT mapping caches. -6. WHEN `cleanup_expired()` is called, THE AppRole_Cache SHALL remove only expired entries from all cache layers. -7. THE AppRole_Cache `get_stats()` method SHALL return accurate counts of total and expired entries for each cache layer. - -### Requirement 8: OIDC State Store Tests - -**User Story:** As a developer, I want tests for the InMemoryStateStore, so that I can verify state storage, one-time retrieval, TTL expiration, and cleanup behavior. - -#### Acceptance Criteria - -1. BEFORE writing tests, THE developer SHALL review all inline comments and docstrings in the `InMemoryStateStore` source file, verifying they accurately describe the storage structure, TTL enforcement, one-time-use deletion semantics, and cleanup behavior, and update or remove any that are stale, misleading, or incorrect. -2. WHEN `store_state()` is called and then `get_and_delete_state()` is called with the same state, THE State_Store SHALL return `(True, OIDCStateData)` with the correct redirect_uri, code_verifier, nonce, and provider_id. -2. WHEN `get_and_delete_state()` is called a second time with the same state, THE State_Store SHALL return `(False, None)` because the state was consumed. -3. WHEN `get_and_delete_state()` is called with a state that was never stored, THE State_Store SHALL return `(False, None)`. -4. WHEN `store_state()` is called with a TTL of 0 seconds and `get_and_delete_state()` is called after the TTL expires, THE State_Store SHALL return `(False, None)`. -5. WHEN multiple states are stored and some expire, THE State_Store SHALL clean up only the expired entries during `_cleanup_expired()`. -6. FOR ALL state tokens stored with OIDCStateData, storing and then retrieving SHALL return data equivalent to the original (round-trip property). - -### Requirement 9: PKCE Generation Tests - -**User Story:** As a developer, I want tests for the PKCE code verifier and challenge generation, so that I can verify the S256 challenge method produces correct, spec-compliant values. - -#### Acceptance Criteria - -1. BEFORE writing tests, THE developer SHALL review all inline comments and docstrings in the PKCE generation code (`generate_pkce_pair()` and related helpers), verifying they accurately describe the verifier generation, S256 challenge computation, and base64url encoding, and update or remove any that are stale, misleading, or incorrect. -2. THE OIDC_Auth_Service `generate_pkce_pair()` function SHALL produce a code_verifier between 43 and 128 characters in length. -2. THE OIDC_Auth_Service `generate_pkce_pair()` function SHALL produce a code_challenge that equals `BASE64URL(SHA256(code_verifier))` with padding stripped. -3. FOR ALL generated PKCE pairs, recomputing `BASE64URL(SHA256(code_verifier))` SHALL equal the returned code_challenge (round-trip property). -4. WHEN `generate_pkce_pair()` is called multiple times, THE OIDC_Auth_Service SHALL produce unique code_verifier values each time. - -### Requirement 10: GenericOIDCAuthService Flow Tests - -**User Story:** As a developer, I want tests for the GenericOIDCAuthService, so that I can verify state generation, authorization URL building, token exchange with nonce validation, token refresh, and logout URL construction. - -#### Acceptance Criteria - -1. BEFORE writing tests, THE developer SHALL review all inline comments and docstrings in the `GenericOIDCAuthService` source file, verifying they accurately describe the OIDC flow methods (`generate_state`, `build_authorization_url`, `exchange_code_for_tokens`, `refresh_access_token`, `build_logout_url`) and how PKCE, nonce, and state interact, and update or remove any that are stale, misleading, or incorrect. -2. WHEN `generate_state()` is called, THE OIDC_Auth_Service SHALL store the state in the state store with the provider_id, code_verifier, nonce, and optional redirect_uri. -2. WHEN `build_authorization_url()` is called with PKCE enabled, THE OIDC_Auth_Service SHALL include `code_challenge` and `code_challenge_method=S256` in the URL parameters. -3. WHEN `build_authorization_url()` is called with PKCE disabled, THE OIDC_Auth_Service SHALL omit `code_challenge` and `code_challenge_method` from the URL parameters. -4. WHEN `exchange_code_for_tokens()` is called with an invalid state, THE OIDC_Auth_Service SHALL raise an HTTPException with status 400 and detail containing "Invalid or expired state". -5. WHEN `exchange_code_for_tokens()` receives an ID token with a nonce that does not match the stored nonce, THE OIDC_Auth_Service SHALL raise an HTTPException with status 400 and detail "ID token nonce validation failed.". -6. WHEN `exchange_code_for_tokens()` succeeds, THE OIDC_Auth_Service SHALL return a dict containing access_token, refresh_token, id_token, token_type, expires_in, scope, and provider_id. -7. WHEN `refresh_access_token()` receives a 400 response from the token endpoint, THE OIDC_Auth_Service SHALL raise an HTTPException with status 401 and detail containing "Invalid or expired refresh token". -8. WHEN `build_logout_url()` is called with a post_logout_redirect_uri, THE OIDC_Auth_Service SHALL append it as a query parameter to the logout endpoint. -9. WHEN `build_logout_url()` is called and no logout endpoint is configured, THE OIDC_Auth_Service SHALL return an empty string. - -### Requirement 11: Auth Routes Integration Tests - -**User Story:** As a developer, I want integration tests for the auth API routes, so that I can verify the full request/response cycle for providers listing, login initiation, token exchange, refresh, logout, and runtime endpoint resolution. - -#### Acceptance Criteria - -1. BEFORE writing tests, THE developer SHALL review all inline comments and docstrings in the auth router source file, verifying they accurately describe each endpoint's behavior, dependency injections, request/response schemas, and error handling, and update or remove any that are stale, misleading, or incorrect. -2. WHEN `GET /auth/providers` is called, THE Auth_Routes SHALL return a list of enabled providers with provider_id, display_name, logo_url, and button_color. -2. WHEN `GET /auth/login?provider_id=test` is called, THE Auth_Routes SHALL return an authorization_url and state token. -3. WHEN `GET /auth/login` is called with a non-existent provider_id, THE Auth_Routes SHALL return status 400. -4. WHEN `POST /auth/token` is called with a valid state and code, THE Auth_Routes SHALL return access_token, refresh_token, and token metadata. -5. WHEN `POST /auth/token` is called with an invalid state, THE Auth_Routes SHALL return status 400. -6. WHEN `POST /auth/refresh?provider_id=test` is called with a valid refresh token, THE Auth_Routes SHALL return a new access_token. -7. WHEN `GET /auth/logout?provider_id=test` is called, THE Auth_Routes SHALL return a logout_url. -8. WHEN `GET /auth/runtime-endpoint` is called by an authenticated user whose provider has a runtime endpoint, THE Auth_Routes SHALL return the runtime_endpoint_url, provider_id, and runtime_status. -9. WHEN `GET /auth/runtime-endpoint` is called without authentication, THE Auth_Routes SHALL return status 401. - -### Requirement 12: Frontend AuthService Tests - -**User Story:** As a developer, I want Vitest tests for the Angular AuthService, so that I can verify token storage, expiry checking, authentication state, login flow initiation, logout, and token refresh. - -#### Acceptance Criteria - -1. BEFORE writing tests, THE developer SHALL review all inline comments and docstrings in the Angular `AuthService` source file, verifying they accurately describe the signals, localStorage keys, token expiry buffer logic, `ensureAuthenticated()` refresh flow, and `login()` redirect construction, and update or remove any that are stale, misleading, or incorrect. -2. WHEN `storeTokens()` is called with a token response, THE Auth_Service_FE SHALL store access_token, refresh_token, and computed expiry timestamp in localStorage. -2. WHEN `getAccessToken()` is called after storing tokens, THE Auth_Service_FE SHALL return the stored access token. -3. WHEN `isTokenExpired()` is called and the token expiry is in the future beyond the buffer, THE Auth_Service_FE SHALL return false. -4. WHEN `isTokenExpired()` is called and the token expiry is within the buffer window, THE Auth_Service_FE SHALL return true. -5. WHEN `isTokenExpired()` is called and no expiry is stored, THE Auth_Service_FE SHALL return true. -6. WHEN `isAuthenticated()` is called with a valid non-expired token, THE Auth_Service_FE SHALL return true. -7. WHEN `isAuthenticated()` is called with no token, THE Auth_Service_FE SHALL return false. -8. WHEN `clearTokens()` is called, THE Auth_Service_FE SHALL remove access_token, refresh_token, token_expiry, and provider_id from localStorage and set currentProviderId signal to null. -9. WHEN `login()` is called, THE Auth_Service_FE SHALL store the state in sessionStorage and the provider_id in localStorage before redirecting. -10. WHEN `ensureAuthenticated()` is called with a valid token, THE Auth_Service_FE SHALL resolve without error. -11. WHEN `ensureAuthenticated()` is called with an expired token and refresh succeeds, THE Auth_Service_FE SHALL resolve without error after refreshing. -12. WHEN `ensureAuthenticated()` is called with no token, THE Auth_Service_FE SHALL throw an Error with message containing "not authenticated". - -### Requirement 13: Frontend Auth Guard Tests - -**User Story:** As a developer, I want Vitest tests for the authGuard and adminGuard, so that I can verify route protection, token refresh attempts, and role-based access control on the frontend. - -#### Acceptance Criteria - -1. BEFORE writing tests, THE developer SHALL review all inline comments and docstrings in the `authGuard` and `adminGuard` source files, verifying they accurately describe the guard logic, token refresh attempts, role checks, and redirect behavior, and update or remove any that are stale, misleading, or incorrect. -2. WHEN the user is authenticated, THE Auth_Guard SHALL return true and allow navigation. -2. WHEN the user is not authenticated and has no token, THE Auth_Guard SHALL navigate to `/auth/login` with the returnUrl query parameter and return false. -3. WHEN the user has an expired token and refresh succeeds, THE Auth_Guard SHALL return true. -4. WHEN the user has an expired token and refresh fails, THE Auth_Guard SHALL navigate to `/auth/login` and return false. -5. WHEN the user is authenticated and has an admin role, THE Admin_Guard SHALL return true. -6. WHEN the user is authenticated but lacks admin roles, THE Admin_Guard SHALL navigate to `/` and return false. -7. WHEN the user is not authenticated, THE Admin_Guard SHALL navigate to `/auth/login` and return false. - -### Requirement 14: Frontend Auth Interceptor Tests - -**User Story:** As a developer, I want Vitest tests for the authInterceptor and errorInterceptor, so that I can verify token attachment, auth endpoint skipping, 401 retry with refresh, and error handling behavior. - -#### Acceptance Criteria - -1. BEFORE writing tests, THE developer SHALL review all inline comments and docstrings in the `authInterceptor` and `errorInterceptor` source files, verifying they accurately describe the token attachment logic, auth endpoint skip list, 401 retry mechanism, streaming/silent endpoint detection, and error delegation, and update or remove any that are stale, misleading, or incorrect. -2. WHEN a request is made to a non-auth endpoint and a token exists, THE Auth_Interceptor SHALL clone the request with an `Authorization: Bearer {token}` header. -2. WHEN a request is made to an auth endpoint (`/auth/login`, `/auth/token`, `/auth/refresh`, `/auth/providers`), THE Auth_Interceptor SHALL pass the request through without modification. -3. WHEN a request is made with no token, THE Auth_Interceptor SHALL pass the request through without an Authorization header. -4. WHEN the token is expired before the request, THE Auth_Interceptor SHALL attempt to refresh the token and then attach the new token. -5. WHEN a request returns a 401 error, THE Auth_Interceptor SHALL attempt to refresh the token and retry the request once. -6. WHEN a 401 retry refresh fails, THE Auth_Interceptor SHALL clear tokens and propagate the original error. -7. WHEN a non-streaming request returns an HTTP error, THE Error_Interceptor SHALL call `errorService.handleHttpError()` with the error. -8. WHEN a streaming endpoint (`/invocations`, `/chat/stream`) returns an error, THE Error_Interceptor SHALL skip error handling and let the error propagate. -9. WHEN a silent endpoint (`/health`, `/ping`) returns an error, THE Error_Interceptor SHALL skip displaying the error to the user. - -### Requirement 15: Property-Based Tests for Permission Merging - -**User Story:** As a developer, I want property-based tests using Hypothesis (backend) and fast-check (frontend) for permission merging and token generation, so that I can verify invariants hold across a wide range of inputs. - -#### Acceptance Criteria - -1. BEFORE writing tests, THE developer SHALL review all inline comments and docstrings in the `AppRoleService._merge_permissions()`, `generate_pkce_pair()`, `InMemoryStateStore`, `has_any_role()`, and `has_all_roles()` source code, verifying they accurately describe the invariants being tested (union, idempotence, round-trip, set intersection, subset), and update or remove any that are stale, misleading, or incorrect. -2. FOR ALL lists of AppRoles with arbitrary tools and models, THE AppRole_Service `_merge_permissions()` SHALL produce a tools set that is a superset of every individual role's effective tools (union invariant). -2. FOR ALL lists of AppRoles with arbitrary tools and models, THE AppRole_Service `_merge_permissions()` SHALL produce a models set that is a superset of every individual role's effective models (union invariant). -3. FOR ALL lists of AppRoles, merging permissions SHALL be idempotent: merging the same roles twice produces the same result. -4. FOR ALL lists of AppRoles with priorities, the selected quota_tier SHALL come from the role with the highest priority value. -5. FOR ALL PKCE pairs generated by `generate_pkce_pair()`, the code_challenge SHALL equal `BASE64URL(SHA256(code_verifier))` (round-trip property). -6. FOR ALL OIDCStateData objects stored in InMemoryStateStore, storing and then retrieving SHALL return equivalent data (round-trip property). -7. FOR ALL User objects with arbitrary role lists, `has_any_role(user, *roles)` SHALL return True if and only if the intersection of user.roles and roles is non-empty (set intersection property). -8. FOR ALL User objects with arbitrary role lists, `has_all_roles(user, *roles)` SHALL return True if and only if roles is a subset of user.roles (subset property). diff --git a/.kiro/specs/auth-rbac-tests/tasks.md b/.kiro/specs/auth-rbac-tests/tasks.md deleted file mode 100644 index befc9f25..00000000 --- a/.kiro/specs/auth-rbac-tests/tasks.md +++ /dev/null @@ -1,233 +0,0 @@ -# Implementation Plan: Auth & RBAC Test Suite - -## Overview - -Incremental implementation of comprehensive test coverage for the Auth & RBAC modules. Backend tests use pytest + Hypothesis, frontend tests use Vitest + fast-check. Each task begins with a docstring/comment audit of the module under test, then implements the tests. Property-based tests are placed close to the code they validate. - -## Tasks - -- [x] 1. Set up test infrastructure and shared fixtures - - [x] 1.1 Create backend test directories and conftest files - - Create `backend/tests/auth/conftest.py` with shared fixtures: RSA key pair generation, `make_user()` factory, `make_provider()` factory, mock `AuthProviderRepository`, mock `PyJWKClient`, and a `make_jwt()` helper that signs tokens with the test RSA key - - Create `backend/tests/auth/__init__.py` and `backend/tests/rbac/__init__.py` and `backend/tests/property/__init__.py` - - Create `backend/tests/rbac/conftest.py` with fixtures: `make_app_role()` factory, mock `AppRoleRepository`, mock `AppRoleCache` - - _Requirements: 1.1, 3.1, 4.1, 5.1, 6.1, 7.1, 8.1_ - - - [x] 1.2 Verify Hypothesis and fast-check are available - - Ensure `hypothesis` is in `backend/pyproject.toml` dev dependencies; add if missing - - Ensure `fast-check` is in `frontend/ai.client/package.json` devDependencies; add if missing - - _Requirements: 15.1_ - -- [x] 2. Remove legacy EntraIDJWTValidator - - [x] 2.1 Audit comments and remove legacy validator - - Review all inline comments and docstrings in `backend/src/apis/shared/auth/jwt_validator.py` and any files that import it; fix stale comments - - Delete `backend/src/apis/shared/auth/jwt_validator.py` - - Remove all import references to `EntraIDJWTValidator` or `get_validator` from `jwt_validator` across the codebase - - Update `__init__.py` or any re-exports to exclude the deleted module - - Remove any fallback code that uses `EntraIDJWTValidator` when the generic validator is unavailable - - _Requirements: 2.1, 2.2, 2.3, 2.4, 2.5, 2.6_ - - - [x] 2.2 Verify no regression after removal - - Run existing backend tests to confirm nothing breaks: `docker compose exec dev bash -c "cd /workspace/bsu-org/agentcore-public-stack/backend && python -m pytest tests/ -v"` - - _Requirements: 2.7_ - -- [x] 3. Checkpoint - Verify test infrastructure and legacy removal - - Ensure all tests pass, ask the user if questions arise. - -- [x] 4. GenericOIDCJWTValidator tests - - [x] 4.1 Audit JWT validator comments and write unit tests - - Review and fix all inline comments and docstrings in `backend/src/apis/shared/auth/generic_jwt_validator.py` - - Create `backend/tests/auth/test_generic_jwt_validator.py` with tests covering: valid RS256 decode (1.2), invalid signature (1.3), expired token (1.4), exact issuer match (1.5), Entra ID v1↔v2 cross-version matching (1.6, 1.7), issuer mismatch rejection (1.8), audience validation (1.9, 1.10), scope enforcement (1.11), user_id pattern validation (1.12), missing user_id claim (1.13), name construction from first/last claims (1.14), roles normalization from string (1.15), email fallback to preferred_username (1.16), JWKS client caching (1.17), resolve_provider_from_token success and failure (1.18, 1.19), invalidate_cache (1.20), dot-notation claim extraction (1.21), URI-style claim lookup (1.22) - - _Requirements: 1.1–1.22_ - - - [ ]* 4.2 Write property test for dot-notation claim extraction - - **Property 11: Dot-notation claim extraction traverses nested dicts** - - **Validates: Requirements 1.21** - -- [x] 5. FastAPI auth dependency tests - - [x] 5.1 Audit auth dependency comments and write unit tests - - Review and fix all inline comments and docstrings in `backend/src/apis/shared/auth/dependencies.py` - - Create `backend/tests/auth/test_dependencies.py` with tests covering: valid Bearer token flow (3.2), no credentials 401 (3.3), failed validation 401 (3.4), no validator 500 (3.5), trusted decode success (3.6), trusted malformed token (3.7), trusted no-validator fallback (3.8), trusted missing user_id (3.9), get_current_user_id returns string (3.10) - - _Requirements: 3.1–3.10_ - -- [x] 6. RBAC role checker tests - - [x] 6.1 Audit RBAC comments and write unit tests - - Review and fix all inline comments and docstrings in `backend/src/apis/shared/auth/rbac.py` - - Create `backend/tests/auth/test_rbac.py` with tests covering: require_roles OR-logic grant (4.2), require_roles OR-logic deny (4.3), require_all_roles AND-logic grant (4.4), require_all_roles AND-logic deny with missing roles detail (4.5), empty roles list 403 (4.6), has_any_role true (4.7), has_any_role false (4.8), has_all_roles true (4.9), has_all_roles false (4.10), empty roles returns false (4.11), require_admin predefined checker (4.12) - - _Requirements: 4.1–4.12_ - - - [ ]* 6.2 Write property test for has_any_role set intersection - - **Property 9: has_any_role is set intersection** - - **Validates: Requirements 15.8** - - - [ ]* 6.3 Write property test for has_all_roles subset check - - **Property 10: has_all_roles is subset check** - - **Validates: Requirements 15.9** - -- [x] 7. Checkpoint - Verify auth layer tests - - Ensure all tests pass, ask the user if questions arise. - -- [x] 8. AppRoleService permission resolution tests - - [x] 8.1 Audit AppRoleService comments and write unit tests - - Review and fix all inline comments and docstrings in `backend/src/apis/shared/rbac/service.py` - - Create `backend/tests/rbac/test_app_role_service.py` with tests covering: tools union merge (5.2), models union merge (5.3), quota tier from highest priority (5.4), no matching roles falls back to default (5.5), no matching roles and no default returns empty (5.6), wildcard in tools (5.7), can_access_tool with wildcard (5.8), can_access_tool with matching tool (5.9), can_access_tool with no match (5.10), caching on second call (5.11), cache miss queries repo (5.12), only enabled roles merged (5.13) - - _Requirements: 5.1–5.13_ - - - [ ]* 8.2 Write property test for permission merge union - - **Property 1: Permission merge produces union of tools and models** - - **Validates: Requirements 5.2, 5.3, 5.7, 5.14** - - - [ ]* 8.3 Write property test for permission merge idempotence - - **Property 2: Permission merge is idempotent** - - **Validates: Requirements 5.15** - - - [ ]* 8.4 Write property test for quota tier from highest priority - - **Property 3: Quota tier comes from highest-priority role** - - **Validates: Requirements 5.4** - - - [ ]* 8.5 Write property test for wildcard universal tool access - - **Property 4: Wildcard grants universal tool access** - - **Validates: Requirements 5.8** - -- [x] 9. AppRoleAdminService CRUD tests - - [x] 9.1 Audit AppRoleAdminService comments and write unit tests - - Review and fix all inline comments and docstrings in `backend/src/apis/shared/rbac/admin_service.py` - - Create `backend/tests/rbac/test_app_role_admin_service.py` with tests covering: create_role success (6.2), create_role non-existent parent ValueError (6.3), create_role duplicate ValueError (6.4), update system_admin protected fields ValueError (6.5), delete system role ValueError (6.6), delete non-system role success + cache invalidation (6.7), inheritance permission merge (6.8), update jwt_role_mappings cache invalidation (6.9), add_tool_to_role (6.10), remove_tool_from_role (6.11) - - _Requirements: 6.1–6.11_ - -- [x] 10. AppRoleCache TTL and invalidation tests - - [x] 10.1 Audit AppRoleCache comments and write unit tests - - Review and fix all inline comments and docstrings in `backend/src/apis/shared/rbac/cache.py` - - Create `backend/tests/rbac/test_app_role_cache.py` with tests covering: cache hit before TTL (7.2), cache miss after TTL (7.3), invalidate_role clears role + user caches (7.4), invalidate_jwt_mapping clears mapping + user caches (7.5), invalidate_all clears everything (7.6), cleanup_expired removes only expired (7.7), get_stats accuracy (7.8) - - _Requirements: 7.1–7.8_ - -- [x] 11. Checkpoint - Verify RBAC layer tests - - Ensure all tests pass, ask the user if questions arise. - -- [x] 12. OIDC state store tests - - [x] 12.1 Audit state store comments and write unit tests - - Review and fix all inline comments and docstrings in `backend/src/apis/shared/auth/state_store.py` - - Create `backend/tests/auth/test_state_store.py` with tests covering: store and retrieve success (8.2), one-time-use second call returns None (8.3), unknown state returns None (8.4), TTL expiration (8.5), cleanup_expired removes only expired (8.6) - - _Requirements: 8.1–8.6_ - - - [ ]* 12.2 Write property test for state store round-trip - - **Property 7: State store round-trip** - - **Validates: Requirements 8.7** - - - [ ]* 12.3 Write property test for state store one-time-use - - **Property 8: State store one-time-use** - - **Validates: Requirements 8.3** - -- [x] 13. PKCE generation tests - - [x] 13.1 Audit PKCE comments and write unit tests - - Review and fix all inline comments and docstrings in the PKCE generation code in `backend/src/apis/app_api/auth/service.py` - - Create `backend/tests/auth/test_pkce.py` with tests covering: verifier length 43–128 (9.2), challenge equals BASE64URL(SHA256(verifier)) (9.3), uniqueness across calls (9.5) - - _Requirements: 9.1–9.5_ - - - [ ]* 13.2 Write property test for PKCE round-trip correctness - - **Property 5: PKCE round-trip correctness** - - **Validates: Requirements 9.2, 9.3, 9.4** - - - [ ]* 13.3 Write property test for PKCE verifier uniqueness - - **Property 6: PKCE verifier uniqueness** - - **Validates: Requirements 9.5** - -- [x] 14. GenericOIDCAuthService flow tests - - [x] 14.1 Audit OIDC auth service comments and write unit tests - - Review and fix all inline comments and docstrings in `backend/src/apis/app_api/auth/service.py` (GenericOIDCAuthService class) - - Create `backend/tests/auth/test_oidc_auth_service.py` with tests covering: generate_state stores state (10.2), build_authorization_url with PKCE (10.3), build_authorization_url without PKCE (10.4), exchange_code invalid state 400 (10.5), exchange_code nonce mismatch 400 (10.6), exchange_code success returns token dict (10.7), refresh_access_token 400 response raises 401 (10.8), build_logout_url with redirect (10.9), build_logout_url no endpoint returns empty string (10.10) - - _Requirements: 10.1–10.10_ - -- [x] 15. Auth routes integration tests - - [x] 15.1 Audit auth routes comments and write integration tests - - Review and fix all inline comments and docstrings in `backend/src/apis/app_api/auth/routes.py` - - Create `backend/tests/auth/test_auth_routes.py` using FastAPI TestClient with tests covering: GET /auth/providers returns provider list (11.2), GET /auth/login returns auth URL + state (11.3), GET /auth/login unknown provider 400 (11.4), POST /auth/token valid exchange (11.5), POST /auth/token invalid state 400 (11.6), POST /auth/refresh success (11.7), GET /auth/logout returns URL (11.8), GET /auth/runtime-endpoint authenticated (11.9), GET /auth/runtime-endpoint unauthenticated 401 (11.10) - - _Requirements: 11.1–11.10_ - -- [x] 16. Checkpoint - Verify all backend tests - - Ensure all tests pass: `docker compose exec dev bash -c "cd /workspace/bsu-org/agentcore-public-stack/backend && python -m pytest tests/auth/ tests/rbac/ tests/property/ -v"` - - Ask the user if questions arise. - -- [x] 17. Frontend AuthService tests - - [x] 17.1 Audit AuthService comments and write Vitest tests - - Review and fix all inline comments and docstrings in `frontend/ai.client/src/app/auth/auth.service.ts` - - Create `frontend/ai.client/src/app/auth/auth.service.spec.ts` with tests covering: storeTokens stores to localStorage (12.2), getAccessToken returns stored token (12.3), isTokenExpired false when valid (12.4), isTokenExpired true within buffer (12.5), isTokenExpired true when no expiry (12.6), isAuthenticated true (12.7), isAuthenticated false (12.8), clearTokens removes all keys (12.9), login stores state and provider (12.10), ensureAuthenticated resolves with valid token (12.11), ensureAuthenticated refreshes expired token (12.12), ensureAuthenticated throws when no token (12.13) - - _Requirements: 12.1–12.13_ - -- [x] 18. Frontend auth guard and admin guard tests - - [x] 18.1 Audit guard comments and write Vitest tests - - Review and fix all inline comments and docstrings in `frontend/ai.client/src/app/auth/auth.guard.ts` and `admin.guard.ts` (or equivalent files) - - Create `frontend/ai.client/src/app/auth/auth.guard.spec.ts` with tests covering: authenticated returns true (13.2), unauthenticated redirects to /auth/login with returnUrl (13.3), expired token + refresh success returns true (13.4), expired token + refresh fail redirects (13.5) - - Create `frontend/ai.client/src/app/auth/admin.guard.spec.ts` with tests covering: admin role returns true (13.6), non-admin redirects to / (13.7), unauthenticated redirects to /auth/login (13.8) - - _Requirements: 13.1–13.8_ - -- [x] 19. Frontend interceptor tests - - [x] 19.1 Audit interceptor comments and write Vitest tests - - Review and fix all inline comments and docstrings in `frontend/ai.client/src/app/auth/auth.interceptor.ts` and `error.interceptor.ts` (or equivalent files) - - Create `frontend/ai.client/src/app/auth/auth.interceptor.spec.ts` with tests covering: attaches Bearer token (14.2), skips auth endpoints (14.3), no token passes through (14.4), refreshes expired token before request (14.5), retries on 401 (14.6), 401 retry fail clears tokens (14.7) - - Create `frontend/ai.client/src/app/auth/error.interceptor.spec.ts` with tests covering: non-streaming error calls handleHttpError (14.8), streaming endpoint skips handling (14.9), silent endpoint skips display (14.10) - - _Requirements: 14.1–14.10_ - -- [x] 20. Checkpoint - Verify all frontend tests - - Ensure all tests pass: `docker compose exec dev bash -c "cd /workspace/bsu-org/agentcore-public-stack/frontend/ai.client && npx vitest --run src/app/auth/"` - - Ask the user if questions arise. - -- [x] 21. Backend property-based tests (Hypothesis) - - [x] 21.1 Create backend PBT file with Hypothesis strategies - - Create `backend/tests/property/test_pbt_permissions.py` with shared Hypothesis strategies (`st_app_role`, `st_user`, `st_oidc_state_data`, `st_role_name`, `st_tool_id`) as defined in the design document - - _Requirements: 15.1_ - - - [ ]* 21.2 Write property test: permission merge union (backend) - - **Property 1: Permission merge produces union of tools and models** - - **Validates: Requirements 15.2, 15.3** - - - [ ]* 21.3 Write property test: permission merge idempotence (backend) - - **Property 2: Permission merge is idempotent** - - **Validates: Requirements 15.4** - - - [ ]* 21.4 Write property test: quota tier from highest priority (backend) - - **Property 3: Quota tier comes from highest-priority role** - - **Validates: Requirements 15.5** - - - [ ]* 21.5 Write property test: PKCE round-trip (backend) - - **Property 5: PKCE round-trip correctness** - - **Validates: Requirements 15.6** - - - [ ]* 21.6 Write property test: state store round-trip (backend) - - **Property 7: State store round-trip** - - **Validates: Requirements 15.7** - - - [ ]* 21.7 Write property test: has_any_role set intersection (backend) - - **Property 9: has_any_role is set intersection** - - **Validates: Requirements 15.8** - - - [ ]* 21.8 Write property test: has_all_roles subset check (backend) - - **Property 10: has_all_roles is subset check** - - **Validates: Requirements 15.9** - -- [x] 22. Frontend property-based tests (fast-check) - - [x] 22.1 Create frontend PBT file with fast-check arbitraries - - Create `frontend/ai.client/src/app/auth/auth-pbt.spec.ts` with shared fast-check arbitraries (`arbRoleName`, `arbRoleList`) as defined in the design document - - _Requirements: 15.1_ - - - [ ]* 22.2 Write property test: has_any_role set intersection (frontend) - - **Property 9: has_any_role is set intersection (frontend equivalent)** - - **Validates: Requirements 15.8** - - - [ ]* 22.3 Write property test: has_all_roles subset check (frontend) - - **Property 10: has_all_roles is subset check (frontend equivalent)** - - **Validates: Requirements 15.9** - -- [x] 23. Final checkpoint - Full test suite verification - - Run all backend tests: `docker compose exec dev bash -c "cd /workspace/bsu-org/agentcore-public-stack/backend && python -m pytest tests/auth/ tests/rbac/ tests/property/ -v"` - - Run all frontend tests: `docker compose exec dev bash -c "cd /workspace/bsu-org/agentcore-public-stack/frontend/ai.client && npx vitest --run src/app/auth/"` - - Ensure all tests pass, ask the user if questions arise. - -## Notes - -- Tasks marked with `*` are optional and can be skipped for faster MVP -- Each task begins with a docstring/comment audit per the "BEFORE writing tests" acceptance criteria -- Property tests validate universal correctness properties from the design document -- All runtime commands use `docker compose exec dev` per dev environment rules -- Backend PBT uses Hypothesis with `@settings(max_examples=100)` -- Frontend PBT uses fast-check with `{ numRuns: 100 }` diff --git a/.kiro/specs/backend-architecture-cleanup/design.md b/.kiro/specs/backend-architecture-cleanup/design.md deleted file mode 100644 index 98f807a2..00000000 --- a/.kiro/specs/backend-architecture-cleanup/design.md +++ /dev/null @@ -1,770 +0,0 @@ -# Backend Architecture Cleanup - Design - -## Overview - -This design document outlines the technical approach to fix two critical architectural issues: -1. Exception suppression anti-pattern causing silent failures -2. Tight coupling between inference API and app API preventing independent deployment - -## Architecture - -### Current State - -``` -backend/src/apis/ -├── shared/ # Minimal shared code -│ ├── auth/ # JWT, RBAC (good!) -│ ├── rbac/ # Role management (good!) -│ ├── users/ # User sync (good!) -│ ├── errors.py # Error models (good!) -│ └── quota.py # Quota utilities (good!) -├── app_api/ # ECS Fargate deployment -│ ├── sessions/ # ❌ Used by inference_api -│ ├── files/ # ❌ Used by inference_api -│ ├── assistants/ # ❌ Used by inference_api -│ └── admin/ # ❌ Used by inference_api -└── inference_api/ # AgentCore Runtime deployment - └── chat/ - ├── routes.py # ❌ Imports from app_api - └── service.py # ❌ Imports from app_api -``` - -### Target State - -``` -backend/src/apis/ -├── shared/ # Expanded shared library -│ ├── auth/ # JWT, RBAC (existing) -│ ├── rbac/ # Role management (existing) -│ ├── users/ # User sync (existing) -│ ├── errors.py # Error models (existing) -│ ├── quota.py # Quota utilities (existing) -│ ├── sessions/ # ✅ NEW: Session models & metadata -│ ├── files/ # ✅ NEW: File resolver -│ ├── models/ # ✅ NEW: Managed models service -│ └── assistants/ # ✅ NEW: Assistant shared code -├── app_api/ # ECS Fargate deployment -│ ├── sessions/ # ✅ App-specific session routes -│ ├── files/ # ✅ App-specific file routes -│ ├── assistants/ # ✅ App-specific assistant routes -│ └── admin/ # ✅ Admin-only routes -└── inference_api/ # AgentCore Runtime deployment - └── chat/ - ├── routes.py # ✅ Imports from shared only - └── service.py # ✅ Imports from shared only -``` - -## Component Design - -### 1. Exception Handling Strategy - -#### 1.1 Exception Classification - -**Critical Exceptions (MUST propagate):** -- Database operation failures (DynamoDB, S3) -- Authentication/authorization failures -- Model invocation failures -- Required data validation failures -- External service failures affecting response - -**Optional Exceptions (MAY suppress with justification):** -- Telemetry/metrics collection -- Background title generation -- Optional metadata enrichment -- Cache warming operations -- Non-critical logging enhancements - -#### 1.2 Error Response Pattern - -All API endpoints must follow this pattern: - -```python -from fastapi import HTTPException -from apis.shared.errors import ErrorCode, create_error_response - -@router.get("/example") -async def example_endpoint(): - try: - # Business logic - result = await some_operation() - return result - - except HTTPException: - # Re-raise FastAPI exceptions (already have correct status) - raise - - except SpecificException as e: - # Handle specific exceptions with appropriate status codes - logger.error(f"Specific error: {e}", exc_info=True) - raise HTTPException( - status_code=400, # or appropriate code - detail=create_error_response( - code=ErrorCode.BAD_REQUEST, - message="User-friendly message", - detail=str(e) - ) - ) - - except Exception as e: - # Catch-all for unexpected errors - logger.error(f"Unexpected error: {e}", exc_info=True) - raise HTTPException( - status_code=500, - detail=create_error_response( - code=ErrorCode.INTERNAL_ERROR, - message="An unexpected error occurred", - detail=str(e) - ) - ) -``` - -#### 1.3 Suppression Documentation Pattern - -When suppression is justified: - -```python -try: - await optional_telemetry_operation() -except Exception as e: - # JUSTIFICATION: Telemetry failures should not break user requests. - # This is a fire-and-forget operation with no impact on response. - logger.warning(f"Telemetry failed (non-critical): {e}") - # No re-raise - explicitly suppressed -``` - -### 2. Shared Library Extraction - -#### 2.1 Session Module (`apis/shared/sessions/`) - -**Files to create:** -- `apis/shared/sessions/__init__.py` - Module exports -- `apis/shared/sessions/models.py` - Session data models -- `apis/shared/sessions/metadata.py` - Metadata operations -- `apis/shared/sessions/storage.py` - Storage abstraction - -**Models to move:** -```python -# From: apis/app_api/sessions/models.py -# To: apis/shared/sessions/models.py - -class SessionMetadata(BaseModel): - session_id: str - user_id: str - title: str - status: str - created_at: str - last_message_at: str - message_count: int - starred: bool - tags: List[str] - preferences: Optional[SessionPreferences] - # ... all session-related models -``` - -**Services to move:** -```python -# From: apis/app_api/sessions/services/metadata.py -# To: apis/shared/sessions/metadata.py - -async def store_session_metadata( - session_id: str, - user_id: str, - session_metadata: SessionMetadata -) -> None: - """Store session metadata (DynamoDB + local file)""" - # Implementation stays the same - # Error handling IMPROVED to propagate failures - -async def get_session_metadata( - session_id: str, - user_id: str -) -> Optional[SessionMetadata]: - """Retrieve session metadata""" - # Implementation stays the same - # Error handling IMPROVED to propagate failures -``` - -#### 2.2 Files Module (`apis/shared/files/`) - -**Files to create:** -- `apis/shared/files/__init__.py` - Module exports -- `apis/shared/files/file_resolver.py` - File resolution from S3 -- `apis/shared/files/models.py` - File-related models - -**Code to move:** -```python -# From: apis/app_api/files/file_resolver.py -# To: apis/shared/files/file_resolver.py - -class FileResolver: - """Resolves file upload IDs to actual file content from S3""" - - async def resolve_files( - self, - user_id: str, - upload_ids: List[str], - max_files: int = 5 - ) -> List[ResolvedFileContent]: - """Resolve upload IDs to file content""" - # Implementation stays the same - # Error handling IMPROVED to propagate failures -``` - -#### 2.3 Models Module (`apis/shared/models/`) - -**Files to create:** -- `apis/shared/models/__init__.py` - Module exports -- `apis/shared/models/managed_models.py` - Model management service -- `apis/shared/models/models.py` - Model data models - -**Code to move:** -```python -# From: apis/app_api/admin/services/managed_models.py -# To: apis/shared/models/managed_models.py - -async def list_managed_models() -> List[ManagedModel]: - """List all managed models from storage""" - # Implementation stays the same - # Error handling IMPROVED to propagate failures - -async def get_managed_model(model_id: str) -> Optional[ManagedModel]: - """Get a specific managed model""" - # Implementation stays the same - # Error handling IMPROVED to propagate failures -``` - -#### 2.4 Assistants Module (`apis/shared/assistants/`) - -**Files to create:** -- `apis/shared/assistants/__init__.py` - Module exports -- `apis/shared/assistants/models.py` - Assistant data models -- `apis/shared/assistants/service.py` - Core assistant operations -- `apis/shared/assistants/rag_service.py` - RAG operations - -**Code to move:** -```python -# From: apis/app_api/assistants/services/assistant_service.py -# To: apis/shared/assistants/service.py - -async def get_assistant_with_access_check( - assistant_id: str, - user_id: str, - user_email: str -) -> Optional[Assistant]: - """Get assistant with RBAC access check""" - # Implementation stays the same - # Error handling IMPROVED to propagate failures - -async def assistant_exists(assistant_id: str) -> bool: - """Check if assistant exists""" - # Implementation stays the same -``` - -```python -# From: apis/app_api/assistants/services/rag_service.py -# To: apis/shared/assistants/rag_service.py - -async def search_assistant_knowledgebase_with_formatting( - assistant_id: str, - query: str, - top_k: int = 5 -) -> List[Dict[str, Any]]: - """Search assistant knowledge base""" - # Implementation stays the same - # Error handling IMPROVED to propagate failures - -def augment_prompt_with_context( - user_message: str, - context_chunks: List[Dict[str, Any]] -) -> str: - """Augment user message with RAG context""" - # Implementation stays the same -``` - -### 3. Import Path Updates - -#### 3.1 Inference API Updates - -**File: `apis/inference_api/chat/service.py`** -```python -# BEFORE: -from apis.app_api.sessions.models import SessionMetadata -from apis.app_api.sessions.services.metadata import store_session_metadata - -# AFTER: -from apis.shared.sessions.models import SessionMetadata -from apis.shared.sessions.metadata import store_session_metadata -``` - -**File: `apis/inference_api/chat/routes.py`** -```python -# BEFORE: -from apis.app_api.admin.services.managed_models import list_managed_models -from apis.app_api.files.file_resolver import get_file_resolver -from apis.app_api.assistants.services.assistant_service import ( - get_assistant_with_access_check, - mark_share_as_interacted, -) -from apis.app_api.assistants.services.rag_service import ( - augment_prompt_with_context, - search_assistant_knowledgebase_with_formatting, -) -from apis.app_api.sessions.models import SessionMetadata -from apis.app_api.sessions.services.metadata import ( - get_session_metadata, - store_session_metadata, -) - -# AFTER: -from apis.shared.models.managed_models import list_managed_models -from apis.shared.files.file_resolver import get_file_resolver -from apis.shared.assistants.service import ( - get_assistant_with_access_check, - mark_share_as_interacted, -) -from apis.shared.assistants.rag_service import ( - augment_prompt_with_context, - search_assistant_knowledgebase_with_formatting, -) -from apis.shared.sessions.models import SessionMetadata -from apis.shared.sessions.metadata import ( - get_session_metadata, - store_session_metadata, -) -``` - -#### 3.2 App API Updates - -All app API modules that use the moved code must update imports: - -```python -# BEFORE: -from apis.app_api.sessions.models import SessionMetadata -from apis.app_api.sessions.services.metadata import store_session_metadata - -# AFTER: -from apis.shared.sessions.models import SessionMetadata -from apis.shared.sessions.metadata import store_session_metadata -``` - -### 4. Error Handling Improvements - -#### 4.1 Files to Fix - -Based on grep results, these files need error handling improvements: - -**High Priority (Core Operations):** -1. `apis/app_api/sessions/services/metadata.py` - Multiple suppressions -2. `apis/app_api/storage/local_file_storage.py` - Session error logging -3. `apis/app_api/admin/services/managed_models.py` - Model operations -4. `apis/shared/users/sync.py` - User sync failures -5. `apis/shared/rbac/seeder.py` - Role seeding failures - -**Medium Priority (Service Operations):** -6. `apis/app_api/admin/routes.py` - Multiple exception handlers -7. `apis/app_api/users/routes.py` - User search errors -8. `apis/app_api/admin/services/model_access.py` - Permission checks - -**Low Priority (Optional Operations):** -9. `apis/shared/auth/dependencies.py` - User sync (already justified) -10. `apis/shared/auth/jwt_validator.py` - Debug logging (justified) -11. `apis/shared/auth/state_store.py` - Fallback to in-memory (justified) - -#### 4.2 Metadata Storage Pattern - -**Current (WRONG):** -```python -try: - await store_to_dynamodb(data) -except Exception as e: - logger.error(f"Failed to store: {e}") - # Don't raise - metadata storage failures shouldn't break the app - # ❌ WRONG: This is a critical operation! -``` - -**Fixed (CORRECT):** -```python -try: - await store_to_dynamodb(data) -except ClientError as e: - logger.error(f"DynamoDB error storing metadata: {e}", exc_info=True) - raise HTTPException( - status_code=503, - detail=create_error_response( - code=ErrorCode.SERVICE_UNAVAILABLE, - message="Failed to store session metadata", - detail=str(e) - ) - ) -except Exception as e: - logger.error(f"Unexpected error storing metadata: {e}", exc_info=True) - raise HTTPException( - status_code=500, - detail=create_error_response( - code=ErrorCode.INTERNAL_ERROR, - message="An unexpected error occurred", - detail=str(e) - ) - ) -``` - -#### 4.3 Title Generation Pattern (Justified Suppression) - -**Current (ACCEPTABLE with better docs):** -```python -try: - title = await generate_title(message) - await store_metadata(title=title) - return title -except Exception as e: - logger.error(f"Failed to generate title: {e}", exc_info=True) - # Don't re-raise - title generation is nice-to-have - return "New Conversation" -``` - -**Improved (BETTER):** -```python -try: - title = await generate_title(message) - await store_metadata(title=title) - return title -except Exception as e: - # JUSTIFICATION: Title generation is a non-critical enhancement. - # Failures should not block the chat request. We return a fallback - # title and log the error for monitoring. - logger.error(f"Title generation failed (non-critical): {e}", exc_info=True) - return "New Conversation" # Fallback title -``` - -### 5. Testing Strategy - -#### 5.1 Unit Tests - -**Test exception propagation:** -```python -# tests/apis/shared/sessions/test_metadata.py - -async def test_store_session_metadata_dynamodb_failure(): - """Verify DynamoDB failures propagate as HTTPException""" - with patch('boto3.client') as mock_client: - mock_client.return_value.put_item.side_effect = ClientError(...) - - with pytest.raises(HTTPException) as exc_info: - await store_session_metadata(session_id, user_id, metadata) - - assert exc_info.value.status_code == 503 - assert "SERVICE_UNAVAILABLE" in str(exc_info.value.detail) -``` - -**Test import independence:** -```python -# tests/apis/inference_api/test_imports.py - -def test_no_app_api_imports(): - """Verify inference_api has no imports from app_api""" - import ast - import os - - inference_api_dir = "backend/src/apis/inference_api" - - for root, dirs, files in os.walk(inference_api_dir): - for file in files: - if file.endswith('.py'): - filepath = os.path.join(root, file) - with open(filepath) as f: - tree = ast.parse(f.read()) - - for node in ast.walk(tree): - if isinstance(node, ast.ImportFrom): - assert not node.module.startswith('apis.app_api'), \ - f"Found app_api import in {filepath}: {node.module}" -``` - -#### 5.2 Integration Tests - -**Test API error responses:** -```python -# tests/apis/app_api/test_error_responses.py - -async def test_session_metadata_storage_failure_returns_503(client): - """Verify storage failures return 503, not 200""" - with patch('apis.shared.sessions.metadata.store_session_metadata') as mock: - mock.side_effect = ClientError(...) - - response = await client.post("/sessions", json={...}) - - assert response.status_code == 503 - assert response.json()["error"]["code"] == "service_unavailable" -``` - -#### 5.3 Deployment Tests - -**Test independent builds:** -```bash -# Test inference API builds without app API -cd backend -docker build -f Dockerfile.inference-api -t inference-api:test . - -# Test app API builds without inference API -docker build -f Dockerfile.app-api -t app-api:test . -``` - -## Implementation Plan - -### Phase 1: Shared Library Extraction (No Breaking Changes) - -**Goal:** Move shared code to `apis/shared/` without breaking existing functionality - -**Steps:** -1. Create new shared modules with copied code -2. Update imports in inference_api to use shared modules -3. Update imports in app_api to use shared modules -4. Verify both APIs still work -5. Remove duplicate code from app_api (keep only app-specific code) - -**Validation:** -- All tests pass -- Both APIs start successfully -- No import errors -- Existing functionality unchanged - -### Phase 2: Exception Handling Improvements (Incremental) - -**Goal:** Fix exception suppression patterns file-by-file - -**Priority Order:** -1. Session metadata operations (high impact) -2. Storage operations (high impact) -3. Admin operations (medium impact) -4. Optional operations (low impact, document justification) - -**Per-File Process:** -1. Identify all exception handlers -2. Classify as critical or optional -3. Add proper error propagation for critical operations -4. Document justification for optional suppressions -5. Add unit tests for error cases -6. Verify API returns correct status codes - -**Validation:** -- Unit tests for error propagation -- Integration tests for API status codes -- Manual testing of error scenarios -- No regressions in existing functionality - -### Phase 3: Documentation & Cleanup - -**Goal:** Document patterns and clean up technical debt - -**Steps:** -1. Create error handling guide for developers -2. Add code comments explaining patterns -3. Update API documentation with error responses -4. Remove old comments about suppression -5. Add linting rules to catch future violations - -## Migration Guide - -### For Developers - -**When writing new code:** -1. Always propagate exceptions unless explicitly justified -2. Use `HTTPException` with appropriate status codes -3. Use `ErrorCode` enum from `apis/shared/errors.py` -4. Document any exception suppression with `# JUSTIFICATION:` comment -5. Import from `apis/shared/` for cross-API code - -**When fixing existing code:** -1. Identify the exception handler -2. Determine if operation is critical or optional -3. If critical: Add proper error propagation -4. If optional: Add justification comment -5. Add unit test for error case -6. Verify API returns correct status code - -### For Operations - -**Monitoring improvements:** -- 5xx errors will now be visible in logs and metrics -- Error responses include structured `ErrorCode` for alerting -- Failed operations will no longer silently succeed - -**Deployment changes:** -- Inference API and App API can be deployed independently -- No shared code dependencies between deployments -- Rollback one API without affecting the other - -## Rollback Plan - -### Phase 1 Rollback (Shared Library) - -If issues arise after shared library extraction: - -1. Revert import changes in inference_api -2. Revert import changes in app_api -3. Remove new shared modules -4. Restore original app_api code - -**Risk:** Low - code is copied, not moved initially - -### Phase 2 Rollback (Exception Handling) - -If issues arise after error handling improvements: - -1. Identify problematic file -2. Revert exception handling changes in that file -3. Keep other improvements -4. File bug for investigation - -**Risk:** Low - changes are incremental per-file - -## Success Criteria - -### Functional Requirements - -✅ All API endpoints return appropriate HTTP status codes -✅ Failed operations return 4xx/5xx, never 200 OK -✅ Error responses use structured `ErrorCode` enum -✅ Inference API has zero imports from `apis.app_api` -✅ Both APIs can build and deploy independently - -### Non-Functional Requirements - -✅ No breaking changes to API contracts -✅ No database schema changes required -✅ Existing functionality continues to work -✅ Test coverage for error cases -✅ Documentation for error handling patterns - -### Operational Requirements - -✅ Improved error visibility in logs -✅ Structured error codes for alerting -✅ Independent deployment capability -✅ Faster debugging of issues -✅ Better observability - -## Risks & Mitigation - -### Risk 1: Breaking Changes - -**Risk:** Import path changes break existing code - -**Mitigation:** -- Incremental approach (copy first, then update imports) -- Comprehensive testing at each step -- Keep old code until verified working -- Rollback plan ready - -### Risk 2: Performance Impact - -**Risk:** Error propagation adds latency - -**Mitigation:** -- Error handling is already present, just improving it -- No new operations added -- Async operations remain async -- Monitor performance metrics - -### Risk 3: Incomplete Migration - -**Risk:** Some files still suppress exceptions - -**Mitigation:** -- Systematic file-by-file approach -- Grep search to find all instances -- Code review checklist -- Linting rules to prevent regression - -### Risk 4: Deployment Complexity - -**Risk:** Shared library changes affect both APIs - -**Mitigation:** -- Deploy both APIs together initially -- Test in staging environment first -- Gradual rollout to production -- Monitor error rates closely - -## Appendix - -### A. Error Code Mapping - -| HTTP Status | ErrorCode | Use Case | -|-------------|-----------|----------| -| 400 | BAD_REQUEST | Invalid input, malformed request | -| 401 | UNAUTHORIZED | Missing or invalid authentication | -| 403 | FORBIDDEN | Insufficient permissions | -| 404 | NOT_FOUND | Resource doesn't exist | -| 409 | CONFLICT | Resource already exists | -| 422 | VALIDATION_ERROR | Input validation failed | -| 429 | RATE_LIMIT_EXCEEDED | Too many requests | -| 500 | INTERNAL_ERROR | Unexpected server error | -| 503 | SERVICE_UNAVAILABLE | External service failure | -| 504 | TIMEOUT | Operation timed out | - -### B. Shared Module Structure - -``` -apis/shared/ -├── __init__.py -├── errors.py # ✅ Existing -├── quota.py # ✅ Existing -├── auth/ # ✅ Existing -│ ├── dependencies.py -│ ├── jwt_validator.py -│ ├── models.py -│ └── rbac.py -├── rbac/ # ✅ Existing -│ ├── models.py -│ ├── repository.py -│ ├── service.py -│ └── seeder.py -├── users/ # ✅ Existing -│ ├── models.py -│ ├── repository.py -│ └── sync.py -├── sessions/ # ✅ NEW -│ ├── __init__.py -│ ├── models.py -│ ├── metadata.py -│ └── storage.py -├── files/ # ✅ NEW -│ ├── __init__.py -│ ├── models.py -│ └── file_resolver.py -├── models/ # ✅ NEW -│ ├── __init__.py -│ ├── models.py -│ └── managed_models.py -└── assistants/ # ✅ NEW - ├── __init__.py - ├── models.py - ├── service.py - └── rag_service.py -``` - -### C. Files Requiring Changes - -**Shared Library Creation (Phase 1):** -- Create: `apis/shared/sessions/` (4 files) -- Create: `apis/shared/files/` (3 files) -- Create: `apis/shared/models/` (3 files) -- Create: `apis/shared/assistants/` (4 files) - -**Import Updates (Phase 1):** -- Update: `apis/inference_api/chat/routes.py` -- Update: `apis/inference_api/chat/service.py` -- Update: All app_api files using moved code (~20 files) - -**Error Handling Fixes (Phase 2):** -- Fix: `apis/shared/sessions/metadata.py` (after move) -- Fix: `apis/shared/users/sync.py` -- Fix: `apis/shared/rbac/seeder.py` -- Fix: `apis/app_api/storage/local_file_storage.py` -- Fix: `apis/app_api/admin/routes.py` -- Fix: `apis/app_api/admin/services/managed_models.py` -- Fix: `apis/app_api/admin/services/model_access.py` -- Fix: `apis/app_api/users/routes.py` - -**Total:** ~50 files to modify diff --git a/.kiro/specs/backend-architecture-cleanup/requirements.md b/.kiro/specs/backend-architecture-cleanup/requirements.md deleted file mode 100644 index f480085e..00000000 --- a/.kiro/specs/backend-architecture-cleanup/requirements.md +++ /dev/null @@ -1,204 +0,0 @@ -# Backend Architecture Cleanup - Requirements - -## Overview - -This spec addresses critical architectural issues in the backend codebase: -1. **Exception suppression** - Errors are logged but not bubbled up, causing API endpoints to return 200 OK even when backend operations fail -2. **Tight coupling** - The inference API (deployed to AgentCore Runtime) imports from app API (deployed to ECS Fargate), violating deployment separation - -## Problem Statement - -### Problem 1: Exception Suppression Anti-Pattern - -Throughout the backend, exceptions are caught, logged, and then execution continues without re-raising or returning error responses. This results in: -- API endpoints returning 200 OK when operations actually failed -- Silent failures that are difficult to diagnose -- Inconsistent error handling across the codebase -- Poor observability and debugging experience - -**Examples found:** -- `apis/shared/users/sync.py:90` - User sync failures don't break requests (comment: "Don't re-raise") -- `apis/shared/rbac/seeder.py:83` - Role seeding failures continue silently -- `apis/app_api/sessions/services/metadata.py:158` - Metadata storage failures suppressed (comment: "Don't raise") -- `apis/app_api/sessions/services/metadata.py:271` - DynamoDB metadata failures suppressed -- `apis/app_api/sessions/services/metadata.py:409` - Cost summary update failures suppressed -- `apis/app_api/sessions/services/metadata.py:505` - System rollup failures suppressed -- `apis/app_api/storage/local_file_storage.py:218` - Session error logging without propagation -- Multiple instances in admin routes, storage layers, and service modules - -### Problem 2: Deployment Coupling - -The inference API (AgentCore Runtime deployment) directly imports from app API modules: -- `apis/inference_api/chat/service.py` imports from `apis.app_api.sessions.models` -- `apis/inference_api/chat/service.py` imports from `apis.app_api.sessions.services.metadata` -- `apis/inference_api/chat/routes.py` imports from `apis.app_api.admin.services.managed_models` -- `apis/inference_api/chat/routes.py` imports from `apis.app_api.files.file_resolver` -- `apis/inference_api/chat/routes.py` imports from `apis.app_api.assistants.services.*` -- `apis/inference_api/chat/routes.py` imports from `apis.app_api.sessions.*` - -This creates deployment issues: -- Inference API container must include app API code -- Changes to app API can break inference API -- Cannot deploy/scale services independently -- Violates separation of concerns - -## User Stories - -### 1. Exception Handling - -**As a** cloud architect -**I want** all backend exceptions to bubble up to API endpoints with appropriate HTTP status codes -**So that** I can properly diagnose issues and clients receive accurate error responses - -**Acceptance Criteria:** -1.1. All caught exceptions must either be re-raised or converted to HTTPException with appropriate status codes -1.2. Only truly optional operations (like metrics, logging enhancements) may suppress exceptions with explicit justification -1.3. API endpoints return 4xx/5xx status codes when operations fail, never 200 OK -1.4. Error responses include structured error information using the existing `ErrorCode` enum -1.5. Suppressed exceptions must be explicitly documented with comments explaining why suppression is safe - -### 2. Shared Module Extraction - -**As a** cloud architect -**I want** common code used by both APIs to live in the shared library -**So that** inference API and app API can be deployed independently - -**Acceptance Criteria:** -2.1. Session models are moved to `apis/shared/sessions/models.py` -2.2. Session metadata operations are moved to `apis/shared/sessions/metadata.py` -2.3. File resolver is moved to `apis/shared/files/file_resolver.py` -2.4. Managed models service is moved to `apis/shared/models/managed_models.py` -2.5. Assistant-related shared code is moved to `apis/shared/assistants/` -2.6. Inference API has zero imports from `apis.app_api.*` -2.7. App API imports from shared library where appropriate -2.8. Both APIs can build and deploy independently - -### 3. Error Response Consistency - -**As a** frontend developer -**I want** consistent error response formats across all API endpoints -**So that** I can handle errors predictably in the UI - -**Acceptance Criteria:** -3.1. All error responses use the `ErrorDetail` model from `apis/shared/errors.py` -3.2. HTTP status codes correctly reflect error types (400, 401, 403, 404, 409, 422, 429, 500, 503, 504) -3.3. Error responses include `code`, `message`, and optional `detail` fields -3.4. SSE streams use `ConversationalErrorEvent` for user-facing errors -3.5. Internal errors include sufficient detail for debugging without exposing sensitive information - -### 4. Backward Compatibility - -**As a** system operator -**I want** these changes to maintain API compatibility -**So that** existing clients continue to work without modification - -**Acceptance Criteria:** -4.1. API endpoint paths remain unchanged -4.2. Request/response schemas remain unchanged (except error responses improve) -4.3. Existing functionality continues to work -4.4. Database schemas remain unchanged -4.5. Environment variables remain unchanged - -## Technical Context - -### Current Architecture - -``` -backend/src/ -├── apis/ -│ ├── shared/ # Shared utilities (minimal) -│ │ ├── auth/ # JWT validation, RBAC -│ │ ├── rbac/ # Role-based access control -│ │ ├── users/ # User sync service -│ │ ├── errors.py # Error models (good!) -│ │ └── quota.py # Quota utilities -│ ├── app_api/ # Main API (ECS Fargate) -│ │ ├── sessions/ # Session management -│ │ ├── files/ # File operations -│ │ ├── assistants/ # Assistant services -│ │ └── admin/ # Admin operations -│ └── inference_api/ # AgentCore Runtime API -│ └── chat/ # Chat invocation -└── agents/ # Agent implementations -``` - -### Deployment Targets - -- **App API**: ECS Fargate container, port 8000, full application features -- **Inference API**: AgentCore Runtime container, port 8001, minimal endpoints (/ping, /invocations) - -### Existing Error Infrastructure - -The codebase already has good error models in `apis/shared/errors.py`: -- `ErrorCode` enum with standard error types -- `ErrorDetail` model for structured errors -- `StreamErrorEvent` for SSE errors -- `ConversationalErrorEvent` for user-facing stream errors -- Helper functions for error response creation - -**We need to USE these consistently!** - -## Dependencies - -- FastAPI (existing) -- Pydantic (existing) -- Python 3.13+ (existing) -- boto3 (existing) -- Existing database schemas (no changes) - -## Constraints - -1. **No breaking changes** to API contracts -2. **No database migrations** required -3. **Maintain existing functionality** - only improve error handling -4. **Independent deployability** - inference API must not depend on app API -5. **Backward compatibility** - existing clients must continue working - -## Success Metrics - -1. Zero instances of caught exceptions that don't re-raise or return errors -2. Zero imports from `apis.app_api` in `apis.inference_api` -3. All API endpoints return appropriate HTTP status codes -4. Improved error observability in logs and monitoring -5. Both APIs can build and deploy independently - -## Out of Scope - -- Frontend error handling improvements (separate effort) -- New error types or codes (use existing `ErrorCode` enum) -- Logging infrastructure changes -- Monitoring/alerting setup -- Performance optimization -- New features or functionality - -## Notes - -### Exception Suppression Philosophy - -**When to suppress exceptions:** -- ✅ Optional telemetry/metrics that shouldn't break requests -- ✅ Best-effort operations with explicit fallbacks -- ✅ Background tasks that are truly fire-and-forget - -**When to propagate exceptions:** -- ❌ Core business logic failures -- ❌ Data persistence failures -- ❌ Authentication/authorization failures -- ❌ External service failures that affect the response -- ❌ Validation failures - -**Rule of thumb:** If the operation's failure means the API response is incomplete or incorrect, the exception MUST propagate. - -### Shared Library Organization - -The shared library should contain: -- Models used by both APIs -- Services that both APIs need (with no API-specific logic) -- Utilities and helpers -- Error definitions -- Authentication/authorization - -The shared library should NOT contain: -- API-specific route handlers -- API-specific business logic -- Deployment-specific configuration diff --git a/.kiro/specs/backend-architecture-cleanup/tasks.md b/.kiro/specs/backend-architecture-cleanup/tasks.md deleted file mode 100644 index 9bd5eb22..00000000 --- a/.kiro/specs/backend-architecture-cleanup/tasks.md +++ /dev/null @@ -1,284 +0,0 @@ -# Backend Architecture Cleanup - Tasks - -## Phase 1: Shared Library Extraction ✅ COMPLETED - -### 1. Create Shared Sessions Module ✅ - -- [x] 1.1 Create `apis/shared/sessions/__init__.py` with module exports -- [x] 1.2 Copy session models from `apis/app_api/sessions/models.py` to `apis/shared/sessions/models.py` -- [x] 1.3 Copy metadata operations from `apis/app_api/sessions/services/metadata.py` to `apis/shared/sessions/metadata.py` -- [x] 1.4 Copy message operations from `apis/app_api/sessions/services/messages.py` to `apis/shared/sessions/messages.py` -- [x] 1.5 Update imports within shared sessions module to use relative imports -- [x] 1.6 Verify shared sessions module can be imported without errors - -### 2. Create Shared Files Module ✅ - -- [x] 2.1 Create `apis/shared/files/__init__.py` with module exports -- [x] 2.2 Copy file models from `apis/app_api/files/models.py` to `apis/shared/files/models.py` -- [x] 2.3 Copy file resolver from `apis/app_api/files/file_resolver.py` to `apis/shared/files/file_resolver.py` -- [x] 2.4 Copy file repository from `apis/app_api/files/repository.py` to `apis/shared/files/repository.py` -- [x] 2.5 Update imports within shared files module to use relative imports -- [x] 2.6 Verify shared files module can be imported without errors - -### 3. Create Shared Models Module ✅ - -- [x] 3.1 Create `apis/shared/models/__init__.py` with module exports -- [x] 3.2 Copy managed models service from `apis/app_api/admin/services/managed_models.py` to `apis/shared/models/managed_models.py` -- [x] 3.3 Extract model data models to `apis/shared/models/models.py` -- [x] 3.4 Update imports within shared models module to use relative imports -- [x] 3.5 Verify shared models module can be imported without errors - -### 4. Create Shared Assistants Module ✅ - -- [x] 4.1 Create `apis/shared/assistants/__init__.py` with module exports -- [x] 4.2 Copy assistant models from `apis/app_api/assistants/models.py` to `apis/shared/assistants/models.py` -- [x] 4.3 Copy core assistant service from `apis/app_api/assistants/services/assistant_service.py` to `apis/shared/assistants/service.py` -- [x] 4.4 Copy RAG service from `apis/app_api/assistants/services/rag_service.py` to `apis/shared/assistants/rag_service.py` -- [x] 4.5 Update imports within shared assistants module to use relative imports -- [x] 4.6 Verify shared assistants module can be imported without errors - -### 5. Update Inference API Imports ✅ - -- [x] 5.1 Update `apis/inference_api/chat/service.py` to import from `apis.shared.sessions` -- [x] 5.2 Update `apis/inference_api/chat/routes.py` to import sessions from `apis.shared.sessions` -- [x] 5.3 Update `apis/inference_api/chat/routes.py` to import files from `apis.shared.files` -- [x] 5.4 Update `apis/inference_api/chat/routes.py` to import models from `apis.shared.models` -- [x] 5.5 Update `apis/inference_api/chat/routes.py` to import assistants from `apis.shared.assistants` -- [x] 5.6 Verify inference API starts without import errors -- [x] 5.7 Test inference API `/ping` endpoint -- [x] 5.8 Test inference API `/invocations` endpoint with sample request - -### 6. Update App API Imports ✅ - -- [x] 6.1 Update `apis/app_api/sessions/routes.py` to import from `apis.shared.sessions` -- [x] 6.2 Update `apis/app_api/sessions/services/` files to import from `apis.shared.sessions` -- [x] 6.3 Update `apis/app_api/files/routes.py` to import from `apis.shared.files` -- [x] 6.4 Update `apis/app_api/files/service.py` to import from `apis.shared.files` -- [x] 6.5 Update `apis/app_api/admin/routes.py` to import models from `apis.shared.models` -- [x] 6.6 Update `apis/app_api/assistants/routes.py` to import from `apis.shared.assistants` -- [x] 6.7 Update `apis/app_api/assistants/services/` files to import from `apis.shared.assistants` -- [x] 6.8 Update `apis/app_api/chat/routes.py` to import from shared modules -- [x] 6.9 Update `apis/app_api/memory/routes.py` to import from shared modules -- [x] 6.10 Verify app API starts without import errors -- [x] 6.11 Test app API health endpoint -- [x] 6.12 Test app API session endpoints - -### 7. Verify Independent Deployment - -- [ ] 7.1 Build inference API Docker image independently -- [ ] 7.2 Build app API Docker image independently -- [ ] 7.3 Run inference API container and verify it starts -- [ ] 7.4 Run app API container and verify it starts -- [x] 7.5 Verify no cross-API imports using static analysis -- [ ] 7.6 Run full test suite for both APIs - -### 8. Clean Up Duplicate Code ✅ - -- [x] 8.1 Remove duplicate session code from `apis/app_api/sessions/models.py` (keep only app-specific) -- [x] 8.2 Remove duplicate file code from `apis/app_api/files/` (keep only app-specific routes) -- [x] 8.3 Remove duplicate model code from `apis/app_api/admin/services/managed_models.py` (keep only admin-specific) -- [x] 8.4 Remove duplicate assistant code from `apis/app_api/assistants/` (keep only app-specific routes) -- [x] 8.5 Update any remaining imports to use shared modules -- [x] 8.6 Verify no broken imports after cleanup - -## Phase 2: Exception Handling Improvements ✅ COMPLETED - -### 9. Fix Session Metadata Error Handling ✅ - -- [x] 9.1 Update `store_session_metadata()` in `apis/shared/sessions/metadata.py` to propagate DynamoDB errors -- [x] 9.2 Update `store_session_metadata()` to propagate file storage errors -- [x] 9.3 Update `get_session_metadata()` to propagate retrieval errors -- [x] 9.4 Update `update_cost_summary()` - Justified suppression documented (fire-and-forget background operation) -- [x] 9.5 Update `update_system_rollups()` - Justified suppression documented (supplementary analytics) -- [x] 9.6 Add justification comments for remaining suppressions (GSI lookup, pagination, individual session parsing) -- [x] 9.7 Add unit tests for error propagation in metadata operations -- [x] 9.8 Test API returns 503 when DynamoDB is unavailable - -### 10. Fix Storage Error Handling ✅ - -- [x] 10.1 Update `local_file_storage.py` session error handling - Justified suppressions documented (aggregation resilience) -- [x] 10.2 Update `dynamodb_storage.py` error handling - No changes needed (already propagates) -- [x] 10.3 Add proper HTTPException with status codes for storage failures -- [x] 10.4 Add unit tests for storage error propagation -- [x] 10.5 Test API returns appropriate status codes for storage failures - -### 11. Fix Managed Models Error Handling ✅ - -- [x] 11.1 Update `create_managed_model()` in `apis/shared/models/managed_models.py` - Already propagates errors -- [x] 11.2 Update `update_managed_model()` to propagate errors -- [x] 11.3 Update `delete_managed_model()` to propagate errors -- [x] 11.4 Update `list_managed_models()` to propagate critical errors -- [x] 11.5 Add proper HTTPException with status codes for model operations -- [x] 11.6 Add unit tests for model operation error propagation -- [x] 11.7 Test API returns appropriate status codes for model operation failures - -### 12. Fix User Sync Error Handling ✅ - -- [x] 12.1 Review `apis/shared/users/sync.py` exception handling -- [x] 12.2 Add justification comment for sync failure suppression (best-effort, auth still works) -- [x] 12.3 Consider propagating critical sync failures - Decided: suppression is appropriate -- [x] 12.4 Add unit tests for user sync error scenarios -- [x] 12.5 Document when sync failures should/shouldn't break requests - -### 13. Fix RBAC Seeder Error Handling ✅ - -- [x] 13.1 Review `apis/shared/rbac/seeder.py` exception handling -- [x] 13.2 Add justification comment for role seeding suppression (resilient startup) -- [x] 13.3 Consider propagating critical seeding failures - Decided: partial seeding is acceptable -- [x] 13.4 Add unit tests for seeder error scenarios -- [x] 13.5 Document seeder error handling strategy - -### 14. Fix Admin Routes Error Handling ✅ - -- [x] 14.1 Review `apis/app_api/admin/routes.py` - Already has proper error handling -- [x] 14.2 Verify Gemini model listing error handling - Already correct -- [x] 14.3 Verify OpenAI model listing error handling - Already correct -- [x] 14.4 Verify enabled models CRUD error handling - Already correct -- [x] 14.5 Ensure all admin routes return appropriate status codes - Verified -- [x] 14.6 Add integration tests for admin route error responses -- [x] 14.7 Test API returns correct status codes for admin operation failures - -### 15. Fix Model Access Error Handling ✅ - -- [x] 15.1 Update `apis/app_api/admin/services/model_access.py` permission check error handling -- [x] 15.2 Decide if permission check failures should propagate or fall back - Decided: fallback to JWT roles -- [x] 15.3 Add justification comments for suppressions (AppRole → JWT fallback) -- [x] 15.4 Add unit tests for permission check error scenarios -- [x] 15.5 Document permission check error handling strategy - -### 16. Fix User Routes Error Handling ✅ - -- [x] 16.1 Review `apis/app_api/users/routes.py` - Already has proper error handling -- [x] 16.2 Ensure user operations return appropriate status codes - Verified -- [x] 16.3 Add integration tests for user route error responses -- [x] 16.4 Test API returns correct status codes for user operation failures - -### 17. Document Justified Suppressions ✅ - -- [x] 17.1 Add justification comment to title generation error handling -- [x] 17.2 Add justification comment to telemetry/metrics error handling -- [x] 17.3 Add justification comment to optional cache operations -- [x] 17.4 Add justification comment to debug logging failures -- [x] 17.5 Create list of all justified suppressions for code review - Created `JUSTIFIED_EXCEPTION_SUPPRESSIONS.md` - -## Phase 3: Validation & Testing - -### 18. Docker Build Verification - -- [ ] 18.1 Build inference API Docker image: `docker build -f backend/Dockerfile.inference-api -t inference-api:test .` -- [ ] 18.2 Build app API Docker image: `docker build -f backend/Dockerfile.app-api -t app-api:test .` -- [ ] 18.3 Run inference API container and verify startup: `docker run -p 8001:8001 inference-api:test` -- [ ] 18.4 Run app API container and verify startup: `docker run -p 8000:8000 app-api:test` -- [ ] 18.5 Test inference API health endpoint: `curl http://localhost:8001/ping` -- [ ] 18.6 Test app API health endpoint: `curl http://localhost:8000/health` - -### 19. Integration Testing - -- [ ] 19.1 Set up test environment with required AWS credentials -- [ ] 19.2 Run pytest test suite: `python -m pytest tests/ -v` -- [ ] 19.3 Verify all existing tests pass -- [ ] 19.4 Test session creation and retrieval via API -- [ ] 19.5 Test file upload and resolution via API -- [ ] 19.6 Test assistant operations via API -- [ ] 19.7 Test error responses return correct status codes - -### 20. Manual Smoke Testing - -- [ ] 20.1 Start both APIs locally (app API on 8000, inference API on 8001) -- [ ] 20.2 Create a new chat session via app API -- [ ] 20.3 Send a message via inference API and verify response -- [ ] 20.4 Upload a file and verify it can be resolved -- [ ] 20.5 Test assistant with RAG knowledge base -- [ ] 20.6 Verify error handling by simulating DynamoDB failure -- [ ] 20.7 Check logs for proper error messages and stack traces - -## Phase 4: Documentation & Cleanup - -### 21. Update Documentation - -- [ ] 21.1 Update `backend/README.md` with new shared module structure -- [ ] 21.2 Document error handling patterns for developers -- [ ] 21.3 Add API error response examples to documentation -- [ ] 21.4 Update deployment guide with independent deployment instructions -- [ ] 21.5 Document monitoring recommendations for error tracking - -### 22. Code Quality & Linting - -- [ ] 22.1 Run ruff linter: `ruff check backend/src/` -- [ ] 22.2 Run black formatter: `black backend/src/` -- [ ] 22.3 Run mypy type checker: `mypy backend/src/` -- [ ] 22.4 Fix any linting or type errors -- [ ] 22.5 Add pre-commit hooks for code quality checks - -### 23. Final Cleanup - -- [ ] 23.1 Remove any unused imports across the codebase -- [ ] 23.2 Remove commented-out code -- [ ] 23.3 Verify all TODO comments are addressed or documented -- [ ] 23.4 Clean up any temporary test files -- [ ] 23.5 Update CHANGELOG with architectural improvements - -## Notes - -### Completed Work Summary - -**Phase 1: Shared Library Extraction ✅** -- All 4 shared modules created (sessions, files, models, assistants) -- All inference API imports updated to use shared modules -- All app API imports updated to use shared modules -- Duplicate code removed from app_api -- Zero imports from `apis.app_api` in `apis.inference_api` (verified) - -**Phase 2: Exception Handling Improvements ✅** -- 18 exception handlers fixed across 6 files -- 11 handlers now propagate errors with proper HTTP status codes -- 10 handlers documented with clear justifications for suppression -- Created comprehensive documentation: `JUSTIFIED_EXCEPTION_SUPPRESSIONS.md` -- Error handling patterns established for future development - -### Remaining Work - -**Phase 3: Validation & Testing** -- Docker build and container verification -- Integration testing with pytest -- Manual smoke testing of both APIs -- Error response validation - -**Phase 4: Documentation & Cleanup** -- Update developer documentation -- Code quality checks (ruff, black, mypy) -- Final cleanup and CHANGELOG update - -### Task Dependencies - -- Phase 1 ✅ COMPLETED -- Phase 2 ✅ COMPLETED -- Phase 3 requires Phase 1 & 2 completion -- Phase 4 can be done in parallel with Phase 3 - -### Estimated Effort - -- ✅ Phase 1: 2-3 days (COMPLETED) -- ✅ Phase 2: 3-4 days (COMPLETED) -- Phase 3: 1-2 days (validation & testing) -- Phase 4: 1 day (documentation & cleanup) -- **Remaining: 2-3 days** - -### Risk Mitigation - -- ✅ Import independence verified via static analysis -- ✅ Exception handling patterns documented -- ⏭️ Docker builds will verify true deployment independence -- ⏭️ Integration tests will catch any runtime issues -- ⏭️ Manual testing will validate end-to-end functionality - -### Success Criteria - -✅ Zero imports from `apis.app_api` in `apis.inference_api` -✅ Shared library modules created and functional -✅ Both APIs import from shared modules correctly -✅ Error handling improved in critical paths -✅ Justified suppressions documented with comments -⏭️ Both APIs can build and deploy independently (Docker verification pending) -⏭️ All tests pass (integration testing pending) -⏭️ Documentation updated (pending) diff --git a/.kiro/specs/bootstrap-data-seeding/.config.kiro b/.kiro/specs/bootstrap-data-seeding/.config.kiro deleted file mode 100644 index 68e612e3..00000000 --- a/.kiro/specs/bootstrap-data-seeding/.config.kiro +++ /dev/null @@ -1 +0,0 @@ -{"specId": "c35590f8-b01e-4ac4-b7b6-83a038b22707", "workflowType": "requirements-first", "specType": "feature"} \ No newline at end of file diff --git a/.kiro/specs/bootstrap-data-seeding/design.md b/.kiro/specs/bootstrap-data-seeding/design.md deleted file mode 100644 index 5ad424bf..00000000 --- a/.kiro/specs/bootstrap-data-seeding/design.md +++ /dev/null @@ -1,403 +0,0 @@ -# Design Document: Bootstrap Data Seeding - -## Overview - -This feature replaces the manual post-deployment setup process with an automated, CI/CD-driven bootstrap data seeding pipeline. After infrastructure and App API stacks are deployed, a GitHub Actions workflow invokes a unified Python seed script (`backend/scripts/seed_bootstrap_data.py`) via shell wrappers in `scripts/stack-bootstrap/`. The script writes seed data to three DynamoDB tables and one Secrets Manager secret, resolving resource names from SSM Parameter Store. - -The design follows the project's established patterns: -- **Shell Scripts First**: Workflow YAML calls scripts in `scripts/stack-bootstrap/`; no inline logic. -- **SSM for resource discovery**: Table names and secret ARNs resolved at runtime via `/${projectPrefix}/...` parameters. -- **GitHub secrets/variables**: Sensitive auth provider config from secrets; non-sensitive from variables. -- **Idempotent writes**: Check-before-write with `attribute_not_exists` conditions or get-then-skip logic. - -## Architecture - -```mermaid -flowchart TD - GH["GitHub Actions
bootstrap-data-seeding.yml"] -->|calls| SEED_SH["scripts/stack-bootstrap/seed.sh"] - SEED_SH -->|sources| LOAD_ENV["scripts/common/load-env.sh"] - SEED_SH -->|invokes| SEED_PY["backend/scripts/seed_bootstrap_data.py"] - - SEED_PY -->|reads| SSM["SSM Parameter Store
/${projectPrefix}/..."] - SSM -->|table names, secret ARN| SEED_PY - - SEED_PY -->|writes| AUTH_TABLE["DynamoDB: auth-providers
PK: AUTH_PROVIDER#{id}"] - SEED_PY -->|writes| SECRETS["Secrets Manager
auth-provider-secrets"] - SEED_PY -->|writes| QUOTA_TABLE["DynamoDB: user-quotas
PK: QUOTA_TIER#{id}
PK: ASSIGNMENT#{id}"] - SEED_PY -->|writes| MODELS_TABLE["DynamoDB: managed-models
PK: MODEL#{uuid}"] - - GH_SECRETS["GitHub Secrets
CLIENT_ID, CLIENT_SECRET,
SECRETS_ARN"] -->|env vars| GH - GH_VARS["GitHub Variables
PROVIDER_ID, DISPLAY_NAME,
ISSUER_URL, BUTTON_COLOR"] -->|env vars| GH -``` - -## Components and Interfaces - -### 1. GitHub Actions Workflow (`bootstrap-data-seeding.yml`) - -Thin orchestration layer. Supports `workflow_dispatch` with environment input. Reads auth provider config from GitHub secrets (sensitive) and variables (non-sensitive). Delegates all logic to `scripts/stack-bootstrap/seed.sh`. - -**Environment variables passed to seed.sh:** - -| Variable | Source | Required | Description | -|---|---|---|---| -| `SEED_AUTH_PROVIDER_ID` | `vars.SEED_AUTH_PROVIDER_ID` | No | Provider slug (e.g., `entra-id`) | -| `SEED_AUTH_DISPLAY_NAME` | `vars.SEED_AUTH_DISPLAY_NAME` | No | Login page display name | -| `SEED_AUTH_ISSUER_URL` | `vars.SEED_AUTH_ISSUER_URL` | No | OIDC issuer URL | -| `SEED_AUTH_CLIENT_ID` | `secrets.SEED_AUTH_CLIENT_ID` | No | OAuth client ID | -| `SEED_AUTH_CLIENT_SECRET` | `secrets.SEED_AUTH_CLIENT_SECRET` | No | OAuth client secret | -| `SEED_AUTH_BUTTON_COLOR` | `vars.SEED_AUTH_BUTTON_COLOR` | No | Hex color for login button | -| `CDK_PROJECT_PREFIX` | `vars.CDK_PROJECT_PREFIX` | Yes | SSM parameter prefix | -| `CDK_AWS_REGION` | `vars.AWS_REGION` | Yes | AWS region | - -Auth provider seeding is skipped if `SEED_AUTH_ISSUER_URL`, `SEED_AUTH_CLIENT_ID`, or `SEED_AUTH_CLIENT_SECRET` are not set. - -### 2. Shell Scripts (`scripts/stack-bootstrap/`) - -| Script | Purpose | -|---|---| -| `install.sh` | Installs Python dependencies (`boto3`, `httpx`) | -| `seed.sh` | Sources `load-env.sh`, resolves SSM parameters, invokes `seed_bootstrap_data.py` | - -`seed.sh` resolves the following from SSM before invoking the Python script: -- `/${projectPrefix}/auth/auth-providers-table-name` -- `/${projectPrefix}/auth/auth-provider-secrets-arn` -- `/${projectPrefix}/quota/user-quotas-table-name` -- `/${projectPrefix}/admin/managed-models-table-name` - -These are passed as environment variables to the Python script. - -### 3. Python Seed Script (`backend/scripts/seed_bootstrap_data.py`) - -Single-file script with four seeder functions, a summary reporter, and a `main()` entry point. No external dependencies beyond `boto3` and `httpx`. - -**Interface:** - -```python -def seed_auth_provider( - table_name: str, - secrets_arn: str, - region: str, - provider_id: str, - display_name: str, - issuer_url: str, - client_id: str, - client_secret: str, - button_color: str | None = None, - discover: bool = True, -) -> SeedResult - -def seed_default_quota_tier( - table_name: str, - region: str, -) -> SeedResult - -def seed_default_quota_assignment( - table_name: str, - region: str, - tier_id: str, -) -> SeedResult - -def seed_default_models( - table_name: str, - region: str, -) -> SeedResult - -def main() -> None -``` - -Each function returns a `SeedResult` dataclass: - -```python -@dataclass -class SeedResult: - category: str # "auth_provider", "quota_tier", "quota_assignment", "model" - created: int - skipped: int - failed: int - details: list[str] # Human-readable log lines -``` - -### 4. Seeder Components - -#### Auth Provider Seeder - -Reuses the same DynamoDB item schema as the existing `seed_auth_provider.py`: - -```python -{ - "PK": "AUTH_PROVIDER#{provider_id}", - "SK": "AUTH_PROVIDER#{provider_id}", - "GSI1PK": "ENABLED#true", - "GSI1SK": "AUTH_PROVIDER#{provider_id}", - "providerId": provider_id, - "displayName": display_name, - "providerType": "oidc", - "enabled": True, - "issuerUrl": issuer_url, - "clientId": client_id, - "scopes": "openid profile email", - "responseType": "code", - "pkceEnabled": True, - "userIdClaim": "sub", - "emailClaim": "email", - "nameClaim": "name", - "rolesClaim": "roles", - "pictureClaim": "picture", - "firstNameClaim": "given_name", - "lastNameClaim": "family_name", - # + discovered endpoints if --discover - "createdAt": "", - "updatedAt": "", - "createdBy": "bootstrap-seed", -} -``` - -Idempotency: `get_item` by PK/SK before writing. If item exists, skip and log. - -OIDC discovery: Fetches `{issuer_url}/.well-known/openid-configuration` to populate `authorizationEndpoint`, `tokenEndpoint`, `jwksUri`, `userinfoEndpoint`, `endSessionEndpoint`. On failure, logs warning and continues without endpoints. - -Secrets Manager: Reads existing secret JSON, adds `{provider_id: client_secret}` key, writes back. If provider key already exists, skips. - -#### Quota Tier Seeder - -Writes a single default tier with hardcoded values: - -```python -{ - "PK": "QUOTA_TIER#default", - "SK": "METADATA", - "tierId": "default", - "tierName": "Default Tier", - "description": "Default quota tier for all users", - "monthlyCostLimit": Decimal("50.00"), - "periodType": "monthly", - "softLimitPercentage": Decimal("80.0"), - "actionOnLimit": "block", - "enabled": True, - "createdAt": "", - "updatedAt": "", - "createdBy": "bootstrap-seed", -} -``` - -Idempotency: `get_item` by PK=`QUOTA_TIER#default`, SK=`METADATA`. Skip if exists. - -#### Quota Assignment Seeder - -Writes a single default assignment linking all users to the default tier: - -```python -{ - "PK": "ASSIGNMENT#default-assignment", - "SK": "METADATA", - "GSI1PK": "ASSIGNMENT_TYPE#default_tier", - "GSI1SK": "PRIORITY#100#default-assignment", - "assignmentId": "default-assignment", - "tierId": "default", - "assignmentType": "default_tier", - "priority": 100, - "enabled": True, - "createdAt": "", - "updatedAt": "", - "createdBy": "bootstrap-seed", -} -``` - -Idempotency: `get_item` by PK=`ASSIGNMENT#default-assignment`, SK=`METADATA`. Skip if exists. - -#### Model Seeder - -Writes two default Bedrock model registrations using **global cross-region inference profile IDs** (the `us.anthropic.*` prefix). Each model gets a deterministic UUID derived from the model ID (using `uuid5` with a fixed namespace) to ensure idempotency across runs. - -Model data sourced from: -- Model IDs & inference profile IDs: [AWS Bedrock supported models](https://docs.aws.amazon.com/bedrock/latest/userguide/models-supported.html) and [inference profiles](https://docs.aws.amazon.com/bedrock/latest/userguide/inference-profiles-support.html) -- Pricing: [AWS Bedrock pricing](https://aws.amazon.com/bedrock/pricing) (Anthropic on-demand tier) -- Token limits: Anthropic model specifications (200K context, 64K max output for both models) - -**Claude Haiku 4.5 (default model):** - -```python -{ - "PK": "MODEL#{deterministic_uuid}", - "SK": "MODEL#{deterministic_uuid}", - "GSI1PK": "MODEL#us.anthropic.claude-haiku-4-5-20251001-v1:0", - "GSI1SK": "MODEL#{deterministic_uuid}", - "id": deterministic_uuid, - "modelId": "us.anthropic.claude-haiku-4-5-20251001-v1:0", - "modelName": "Claude Haiku 4.5", - "provider": "bedrock", - "providerName": "Amazon Bedrock", - "inputModalities": ["text", "image"], - "outputModalities": ["text"], - "maxInputTokens": 200000, - "maxOutputTokens": 64000, - "allowedAppRoles": [], - "availableToRoles": [], - "enabled": True, - "inputPricePerMillionTokens": Decimal("1.00"), - "outputPricePerMillionTokens": Decimal("5.00"), - "cacheWritePricePerMillionTokens": Decimal("1.25"), - "cacheReadPricePerMillionTokens": Decimal("0.10"), - "isReasoningModel": False, - "supportsCaching": True, - "isDefault": True, - "createdAt": "", - "updatedAt": "", -} -``` - -**Claude Sonnet 4.6:** - -```python -{ - # Same structure, different values: - "modelId": "us.anthropic.claude-sonnet-4-6", - "modelName": "Claude Sonnet 4.6", - "inputModalities": ["text", "image"], - "outputModalities": ["text"], - "maxInputTokens": 200000, - "maxOutputTokens": 64000, - "inputPricePerMillionTokens": Decimal("3.00"), - "outputPricePerMillionTokens": Decimal("15.00"), - "cacheWritePricePerMillionTokens": Decimal("3.75"), - "cacheReadPricePerMillionTokens": Decimal("0.30"), - "isReasoningModel": False, - "supportsCaching": True, - "isDefault": False, -} -``` - -Idempotency: Query `ModelIdIndex` GSI with `GSI1PK = MODEL#{modelId}`. Skip if exists. - -## Data Models - -### SSM Parameter Paths (read-only, created by AppApiStack) - -| Parameter Path | Value | -|---|---| -| `/${projectPrefix}/auth/auth-providers-table-name` | Auth providers DynamoDB table name | -| `/${projectPrefix}/auth/auth-provider-secrets-arn` | Secrets Manager secret ARN | -| `/${projectPrefix}/quota/user-quotas-table-name` | User quotas DynamoDB table name | -| `/${projectPrefix}/admin/managed-models-table-name` | Managed models DynamoDB table name | - -### DynamoDB Item Schemas - -All items follow the existing schemas defined in the application code. The seed script writes items that are byte-for-byte compatible with what the admin API would create. Key patterns: - -| Table | PK Pattern | SK Pattern | -|---|---|---| -| auth-providers | `AUTH_PROVIDER#{providerId}` | `AUTH_PROVIDER#{providerId}` | -| user-quotas (tier) | `QUOTA_TIER#{tierId}` | `METADATA` | -| user-quotas (assignment) | `ASSIGNMENT#{assignmentId}` | `METADATA` | -| managed-models | `MODEL#{uuid}` | `MODEL#{uuid}` | - -### Secrets Manager Schema - -The auth provider secrets secret stores a JSON map: - -```json -{ - "entra-id": "client-secret-value", - "okta-prod": "another-secret-value" -} -``` - - -## Correctness Properties - -*A property is a characteristic or behavior that should hold true across all valid executions of a system — essentially, a formal statement about what the system should do. Properties serve as the bridge between human-readable specifications and machine-verifiable correctness guarantees.* - -### Property 1: Auth provider item schema correctness - -*For any* valid auth provider configuration (provider ID, display name, issuer URL, client ID), the DynamoDB item produced by the Auth Provider Seeder SHALL have `PK` equal to `AUTH_PROVIDER#{providerId}`, `SK` equal to `AUTH_PROVIDER#{providerId}`, `GSI1PK` equal to `ENABLED#true`, and contain all required fields (`providerId`, `displayName`, `providerType`, `issuerUrl`, `clientId`, `scopes`, `createdAt`, `updatedAt`, `createdBy`). - -**Validates: Requirements 1.1** - -### Property 2: Secret storage round-trip - -*For any* valid provider ID and client secret string, after the Auth Provider Seeder writes to Secrets Manager, reading the secret back and parsing the JSON SHALL yield a map containing the provider ID as a key with the original client secret as its value. - -**Validates: Requirements 1.2** - -### Property 3: OIDC discovery endpoint mapping - -*For any* valid OIDC discovery response containing `authorization_endpoint`, `token_endpoint`, `jwks_uri`, `userinfo_endpoint`, and `end_session_endpoint`, the Auth Provider Seeder SHALL map these to the corresponding DynamoDB item fields (`authorizationEndpoint`, `tokenEndpoint`, `jwksUri`, `userinfoEndpoint`, `endSessionEndpoint`). - -**Validates: Requirements 1.3** - -### Property 4: Seed idempotence - -*For any* valid seed configuration, running the seed script twice with identical inputs SHALL produce the same database state as running it once. Specifically, the second run SHALL skip all items (created=0) and the DynamoDB items SHALL be byte-for-byte identical after both runs. - -**Validates: Requirements 1.4, 2.3, 3.3, 4.4, 7.1, 7.2, 7.4** - -### Property 5: Model registration field completeness - -*For any* model in the default model set, the DynamoDB item SHALL contain all required fields: `modelId`, `modelName`, `provider`, `providerName`, `inputModalities`, `outputModalities`, `maxInputTokens`, `maxOutputTokens`, `allowedAppRoles`, `availableToRoles`, `enabled`, `inputPricePerMillionTokens`, `outputPricePerMillionTokens`, `isReasoningModel`, `supportsCaching`, `isDefault`, `createdAt`, `updatedAt`. - -**Validates: Requirements 4.2, 4.6** - -### Property 6: Exactly one default model invariant - -*For any* successful run of the Model Seeder, across all seeded model items, exactly one SHALL have `isDefault` set to `True`. - -**Validates: Requirements 4.3** - -### Property 7: Summary accuracy - -*For any* seed run, the reported summary SHALL have `created + skipped + failed` equal to the total number of seed items attempted for each category, and the `created` count SHALL equal the number of new items actually written to DynamoDB. - -**Validates: Requirements 8.1, 8.4** - -## Error Handling - -| Scenario | Behavior | Exit Code | -|---|---|---| -| Missing auth provider env vars (issuer, client ID, or client secret) | Skip auth provider seeding entirely, log warning listing missing vars | 0 | -| OIDC discovery HTTP failure | Log warning with status code, continue seeding without discovered endpoints | 0 | -| OIDC discovery network timeout | Log warning, continue seeding without discovered endpoints | 0 | -| DynamoDB `put_item` failure (auth provider) | Log error with exception details, mark item as failed in summary | 1 | -| DynamoDB `put_item` failure (quota tier/assignment) | Log error with exception details, mark item as failed in summary | 1 | -| DynamoDB `put_item` failure (model) | Log error with exception details, mark item as failed in summary | 1 | -| Secrets Manager `get_secret_value` failure | Log error, mark auth provider as failed in summary | 1 | -| Secrets Manager `put_secret_value` failure | Log error, mark auth provider as failed in summary | 1 | -| SSM parameter not found (in seed.sh) | Script fails with `set -euo pipefail`, non-zero exit | 1 | -| All items already seeded (full skip) | Log that all items were already present, exit successfully | 0 | -| Partial failure (some items succeed, some fail) | Complete all seed operations, report mixed summary, exit non-zero | 1 | - -The Python script uses a try/except around each individual seed operation so that a failure in one category (e.g., auth provider) does not prevent seeding of other categories (e.g., models). The final exit code is non-zero if any operation failed. - -## Testing Strategy - -### Unit Tests (pytest) - -Focus on specific examples and edge cases: - -- Default quota tier has expected hardcoded values ($50 monthly limit, 80% soft limit, block action) -- Default quota assignment has `default_tier` type, priority 100, linked to `default` tier -- Default models include Claude Haiku 4.5 (`us.anthropic.claude-haiku-4-5-20251001-v1:0`) and Claude Sonnet 4.6 (`us.anthropic.claude-sonnet-4-6`) with correct global inference profile IDs -- Haiku 4.5 is marked as default, Sonnet 4.6 is not -- `allowedAppRoles` and `availableToRoles` are empty lists on all models -- Missing auth env vars triggers skip with appropriate warning message -- OIDC discovery failure logs warning and continues -- Summary format includes all four categories -- Deterministic UUID generation produces consistent IDs across runs - -### Property-Based Tests (pytest + Hypothesis) - -Each correctness property is implemented as a single property-based test with minimum 100 iterations. Tests use `hypothesis` for input generation. - -- **Feature: bootstrap-data-seeding, Property 1: Auth provider item schema correctness** — Generate random valid provider configs, verify DynamoDB item structure -- **Feature: bootstrap-data-seeding, Property 2: Secret storage round-trip** — Generate random provider IDs and secrets, verify round-trip through mock Secrets Manager -- **Feature: bootstrap-data-seeding, Property 3: OIDC discovery endpoint mapping** — Generate random discovery response dicts, verify field mapping -- **Feature: bootstrap-data-seeding, Property 4: Seed idempotence** — Generate random valid seed configs, run seeder twice against mock DynamoDB, compare states -- **Feature: bootstrap-data-seeding, Property 5: Model registration field completeness** — Verify all default models have all required fields -- **Feature: bootstrap-data-seeding, Property 6: Exactly one default model invariant** — Run model seeder, count items with `isDefault=True` -- **Feature: bootstrap-data-seeding, Property 7: Summary accuracy** — Generate random pre-existing states, run seeder, verify summary counts match actual operations - -### Test Infrastructure - -- Use `moto` library to mock DynamoDB and Secrets Manager (no real AWS calls in tests) -- Use `responses` or `httpx` mock to simulate OIDC discovery endpoints -- Property tests use `@settings(max_examples=100)` for adequate coverage -- Tests located at `backend/tests/scripts/test_seed_bootstrap_data.py` diff --git a/.kiro/specs/bootstrap-data-seeding/requirements.md b/.kiro/specs/bootstrap-data-seeding/requirements.md deleted file mode 100644 index a1e79cd1..00000000 --- a/.kiro/specs/bootstrap-data-seeding/requirements.md +++ /dev/null @@ -1,116 +0,0 @@ -# Requirements Document - -## Introduction - -This feature automates the initial application bootstrap and data seeding process via GitHub Actions. Currently, first-time deployments leave the application in an unconfigured state — no auth providers, no quota tiers, no quota assignments, and no registered Bedrock models. Users see a manual setup guide on the login page and must run scripts by hand. This feature replaces that manual process with a CI/CD-driven seeding workflow that runs after infrastructure deployment, pulling configuration from GitHub Actions secrets/variables and applying sensible defaults for non-sensitive data. - -## Glossary - -- **Seed_Workflow**: The GitHub Actions workflow (`bootstrap-data-seeding.yml`) that orchestrates all data seeding jobs -- **Seed_Script**: A Python script (`backend/scripts/seed_bootstrap_data.py`) that writes seed data to DynamoDB and Secrets Manager -- **Auth_Provider_Seeder**: The component within the Seed_Script responsible for seeding OIDC authentication provider configuration into the auth-providers DynamoDB table and client secrets into Secrets Manager -- **Quota_Seeder**: The component within the Seed_Script responsible for seeding default quota tiers and quota assignments into the user-quotas DynamoDB table -- **Model_Seeder**: The component within the Seed_Script responsible for seeding default Bedrock model registrations into the managed-models DynamoDB table -- **Bootstrap_Scripts**: Shell scripts in `scripts/stack-bootstrap/` that wrap the Seed_Script invocation following the project's Shell Scripts First philosophy -- **DynamoDB_Auth_Providers_Table**: The DynamoDB table storing OIDC authentication provider configurations (PK/SK pattern: `AUTH_PROVIDER#{id}`) -- **DynamoDB_User_Quotas_Table**: The DynamoDB table storing quota tiers (PK: `TIER#{id}`) and quota assignments (PK: `ASSIGNMENT#{id}`) -- **DynamoDB_Managed_Models_Table**: The DynamoDB table storing registered Bedrock model configurations -- **Secrets_Manager_Auth_Secret**: The AWS Secrets Manager secret storing OIDC client secrets as a JSON map of `{provider_id: secret}` -- **SSM_Parameter_Store**: AWS Systems Manager Parameter Store, used to resolve DynamoDB table names and Secrets Manager ARNs at runtime via the `/${projectPrefix}/...` convention - -## Requirements - -### Requirement 1: Auth Provider Seeding via CI/CD - -**User Story:** As a platform operator, I want the first OIDC auth provider to be automatically seeded during deployment, so that users can sign in immediately after the initial deploy without manual script execution. - -#### Acceptance Criteria - -1. WHEN the Seed_Workflow is triggered and auth provider GitHub secrets are configured, THE Auth_Provider_Seeder SHALL write the OIDC provider configuration to the DynamoDB_Auth_Providers_Table using the same item schema as the existing `seed_auth_provider.py` script -2. WHEN the Seed_Workflow is triggered and auth provider GitHub secrets are configured, THE Auth_Provider_Seeder SHALL store the OIDC client secret in the Secrets_Manager_Auth_Secret under the provider ID key -3. WHEN the `--discover` flag is enabled, THE Auth_Provider_Seeder SHALL fetch OIDC endpoints from the issuer URL's `.well-known/openid-configuration` endpoint and populate authorization, token, JWKS, userinfo, and end-session endpoints -4. IF the auth provider already exists in the DynamoDB_Auth_Providers_Table, THEN THE Auth_Provider_Seeder SHALL skip the write and log that the provider was already seeded -5. IF required auth provider secrets (issuer URL, client ID, client secret) are not configured in GitHub, THEN THE Seed_Workflow SHALL skip auth provider seeding and log a warning indicating which values are missing -6. THE Auth_Provider_Seeder SHALL read DynamoDB table names and Secrets Manager ARNs from SSM_Parameter_Store using the `/${projectPrefix}/auth/...` parameter paths - -### Requirement 2: Default Quota Tier Seeding - -**User Story:** As a platform operator, I want default quota tiers seeded automatically on first deploy, so that users have reasonable usage limits out of the box without manual admin configuration. - -#### Acceptance Criteria - -1. WHEN the Seed_Workflow is triggered, THE Quota_Seeder SHALL create a default quota tier in the DynamoDB_User_Quotas_Table with a PK of `TIER#{tier_id}` and SK of `TIER#{tier_id}` -2. THE Quota_Seeder SHALL seed the default tier with a monthly cost limit, a soft limit percentage of 80%, and an action-on-limit of "block" -3. IF a quota tier with the same tier ID already exists in the DynamoDB_User_Quotas_Table, THEN THE Quota_Seeder SHALL skip the write and log that the tier was already seeded -4. THE Quota_Seeder SHALL use sensible hardcoded defaults for quota tier values, requiring no GitHub secrets or variables for this data - -### Requirement 3: Default Quota Assignment Seeding - -**User Story:** As a platform operator, I want a default quota assignment seeded automatically, so that all users are assigned a quota tier without requiring per-user admin action. - -#### Acceptance Criteria - -1. WHEN the Seed_Workflow is triggered, THE Quota_Seeder SHALL create a default quota assignment in the DynamoDB_User_Quotas_Table with assignment type `default_tier` and priority 100 -2. THE Quota_Seeder SHALL link the default assignment to the default quota tier created in Requirement 2 -3. IF a quota assignment with the same assignment ID already exists in the DynamoDB_User_Quotas_Table, THEN THE Quota_Seeder SHALL skip the write and log that the assignment was already seeded -4. THE Quota_Seeder SHALL use sensible hardcoded defaults for assignment values, requiring no GitHub secrets or variables for this data - -### Requirement 4: Default Bedrock Model Registration - -**User Story:** As a platform operator, I want default Bedrock models pre-registered on first deploy, so that users can start conversations immediately without an admin manually adding models. - -#### Acceptance Criteria - -1. WHEN the Seed_Workflow is triggered, THE Model_Seeder SHALL create model registrations in the DynamoDB_Managed_Models_Table for a set of default Bedrock models (Claude Haiku and Claude Sonnet at minimum) -2. THE Model_Seeder SHALL populate each model registration with model ID, model name, provider, input/output modalities, token limits, pricing per million tokens, cache pricing, and caching support flag -3. THE Model_Seeder SHALL mark exactly one model as the default model for new sessions -4. IF a model with the same model ID already exists in the DynamoDB_Managed_Models_Table, THEN THE Model_Seeder SHALL skip the write and log that the model was already seeded -5. THE Model_Seeder SHALL use sensible hardcoded defaults for model configuration, requiring no GitHub secrets or variables for this data -6. THE Model_Seeder SHALL set `allowedAppRoles` and `availableToRoles` to empty lists so all users can access the default models - -### Requirement 5: GitHub Actions Workflow Integration - -**User Story:** As a platform operator, I want the seeding process integrated into the CI/CD pipeline, so that bootstrap data is applied automatically after infrastructure deployment. - -#### Acceptance Criteria - -1. THE Seed_Workflow SHALL be defined as a GitHub Actions workflow file at `.github/workflows/bootstrap-data-seeding.yml` -2. THE Seed_Workflow SHALL support `workflow_dispatch` for manual triggering with an environment input -3. THE Seed_Workflow SHALL support being called after infrastructure and App API deployments via `workflow_call` or manual dispatch -4. THE Seed_Workflow SHALL read auth provider configuration from GitHub secrets for sensitive values (client ID, client secret, secrets ARN) and GitHub variables for non-sensitive values (provider ID, display name, issuer URL, button color) -5. THE Seed_Workflow SHALL delegate all logic to shell scripts in `scripts/stack-bootstrap/` following the Shell Scripts First philosophy -6. THE Seed_Workflow SHALL source `scripts/common/load-env.sh` to resolve the project prefix and AWS configuration - -### Requirement 6: Shell Scripts First Architecture - -**User Story:** As a developer, I want the seeding logic in shell scripts rather than workflow YAML, so that I can run and test the seeding process locally. - -#### Acceptance Criteria - -1. THE Bootstrap_Scripts SHALL include a `scripts/stack-bootstrap/seed.sh` script that invokes the Seed_Script with appropriate environment variables -2. THE Bootstrap_Scripts SHALL include a `scripts/stack-bootstrap/install.sh` script that installs Python dependencies needed by the Seed_Script -3. THE Bootstrap_Scripts SHALL use `set -euo pipefail` for error handling -4. THE Bootstrap_Scripts SHALL be executable locally by sourcing `scripts/common/load-env.sh` and setting the required environment variables -5. THE Bootstrap_Scripts SHALL resolve DynamoDB table names and Secrets Manager ARNs from SSM_Parameter_Store using the project prefix convention - -### Requirement 7: Idempotent Seeding - -**User Story:** As a platform operator, I want the seeding process to be safely re-runnable, so that re-deploying or re-triggering the workflow does not corrupt or duplicate existing data. - -#### Acceptance Criteria - -1. THE Seed_Script SHALL check for existing records before writing each seed item -2. WHEN a seed item already exists, THE Seed_Script SHALL skip the write and log a message indicating the item was already present -3. THE Seed_Script SHALL complete successfully (exit code 0) even when all items are already seeded -4. FOR ALL seed operations, running the Seed_Script twice with identical inputs SHALL produce the same database state as running the Seed_Script once (idempotence property) - -### Requirement 8: Observability and Error Handling - -**User Story:** As a platform operator, I want clear logging and error reporting from the seeding process, so that I can diagnose failures during deployment. - -#### Acceptance Criteria - -1. THE Seed_Script SHALL log the outcome of each seed operation (created, skipped, or failed) with the item type and identifier -2. IF a DynamoDB or Secrets Manager write fails, THEN THE Seed_Script SHALL log the error details and exit with a non-zero exit code -3. IF OIDC discovery fails for the auth provider, THEN THE Seed_Script SHALL log a warning and continue seeding with manually provided or default endpoint values -4. THE Seed_Script SHALL produce a summary at completion listing the count of items created, skipped, and failed for each data category (auth providers, quota tiers, quota assignments, models) diff --git a/.kiro/specs/bootstrap-data-seeding/tasks.md b/.kiro/specs/bootstrap-data-seeding/tasks.md deleted file mode 100644 index 653716f1..00000000 --- a/.kiro/specs/bootstrap-data-seeding/tasks.md +++ /dev/null @@ -1,153 +0,0 @@ -# Implementation Plan: Bootstrap Data Seeding - -## Overview - -Automate post-deployment bootstrap data seeding via a unified Python script invoked by GitHub Actions. The implementation follows the project's Shell Scripts First philosophy, with shell wrappers in `scripts/stack-bootstrap/` delegating to `backend/scripts/seed_bootstrap_data.py`. The script seeds auth providers, quota tiers, quota assignments, and Bedrock models into DynamoDB, with idempotent check-before-write logic and structured summary reporting. - -## Tasks - -- [x] 1. Create the Python seed script with core data structures and entry point - - [x] 1.1 Create `backend/scripts/seed_bootstrap_data.py` with `SeedResult` dataclass, logging setup, and `main()` entry point that reads environment variables and dispatches to seeder functions - - Define `SeedResult` with `category`, `created`, `skipped`, `failed`, `details` fields - - `main()` reads env vars (`SEED_AUTH_*`, `DDB_AUTH_PROVIDERS_TABLE`, `DDB_USER_QUOTAS_TABLE`, `DDB_MANAGED_MODELS_TABLE`, `SECRETS_AUTH_ARN`, `AWS_REGION`), calls each seeder, collects results, prints summary, exits non-zero if any failures - - Skip auth provider seeding if `SEED_AUTH_ISSUER_URL`, `SEED_AUTH_CLIENT_ID`, or `SEED_AUTH_CLIENT_SECRET` are missing, log warning listing which are absent - - _Requirements: 1.5, 7.3, 8.1, 8.2, 8.4_ - - - [x] 1.2 Implement `seed_auth_provider()` function - - Accept `table_name`, `secrets_arn`, `region`, `provider_id`, `display_name`, `issuer_url`, `client_id`, `client_secret`, `button_color`, `discover` parameters - - Check for existing item via `get_item` on PK/SK `AUTH_PROVIDER#{provider_id}` — skip if exists - - If `discover=True`, fetch `{issuer_url}/.well-known/openid-configuration` via `httpx`, map `authorization_endpoint`, `token_endpoint`, `jwks_uri`, `userinfo_endpoint`, `end_session_endpoint` to DynamoDB fields; on failure log warning and continue - - Write DynamoDB item matching the schema in the design (all required fields, `createdBy: bootstrap-seed`) - - Read existing Secrets Manager JSON, add `{provider_id: client_secret}` key if not present, write back - - Return `SeedResult` with counts - - _Requirements: 1.1, 1.2, 1.3, 1.4, 1.6, 8.3_ - - - [x] 1.3 Implement `seed_default_quota_tier()` function - - Write default tier item with PK=`QUOTA_TIER#default`, SK=`METADATA`, $50 monthly limit, 80% soft limit, block action - - Check for existing item via `get_item` — skip if exists - - Return `SeedResult` - - _Requirements: 2.1, 2.2, 2.3, 2.4_ - - - [x] 1.4 Implement `seed_default_quota_assignment()` function - - Write default assignment item with PK=`ASSIGNMENT#default-assignment`, SK=`METADATA`, type `default_tier`, priority 100, linked to `default` tier - - Check for existing item via `get_item` — skip if exists - - Return `SeedResult` - - _Requirements: 3.1, 3.2, 3.3, 3.4_ - - - [x] 1.5 Implement `seed_default_models()` function - - Seed Claude Haiku 4.5 (`us.anthropic.claude-haiku-4-5-20251001-v1:0`, `isDefault=True`) and Claude Sonnet 4.6 (`us.anthropic.claude-sonnet-4-6`, `isDefault=False`) - - Use `uuid5` with a fixed namespace for deterministic UUIDs from model IDs - - Query `GSI1PK = MODEL#{modelId}` to check existence — skip if exists - - Set `allowedAppRoles` and `availableToRoles` to empty lists - - Populate all pricing, token limit, modality, and caching fields per design - - Return `SeedResult` - - _Requirements: 4.1, 4.2, 4.3, 4.4, 4.5, 4.6_ - -- [x] 2. Checkpoint — Verify seed script runs locally - - Ensure all tests pass, ask the user if questions arise. - -- [x] 3. Create shell scripts in `scripts/stack-bootstrap/` - - [x] 3.1 Create `scripts/stack-bootstrap/install.sh` - - Use `set -euo pipefail` - - Install Python dependencies: `boto3`, `httpx` - - _Requirements: 6.2, 6.3_ - - - [x] 3.2 Create `scripts/stack-bootstrap/seed.sh` - - Use `set -euo pipefail` - - Source `scripts/common/load-env.sh` - - Resolve DynamoDB table names and Secrets Manager ARN from SSM using `aws ssm get-parameter` with `/${projectPrefix}/auth/auth-providers-table-name`, `/${projectPrefix}/auth/auth-provider-secrets-arn`, `/${projectPrefix}/quota/user-quotas-table-name`, `/${projectPrefix}/admin/managed-models-table-name` - - Export resolved values as environment variables and invoke `python backend/scripts/seed_bootstrap_data.py` - - _Requirements: 6.1, 6.3, 6.4, 6.5_ - -- [x] 4. Create GitHub Actions workflow - - [x] 4.1 Create `.github/workflows/bootstrap-data-seeding.yml` - - Define `workflow_dispatch` trigger with `environment` input - - Define `workflow_call` trigger for chaining after infrastructure deploys - - Read auth config from GitHub secrets (`SEED_AUTH_CLIENT_ID`, `SEED_AUTH_CLIENT_SECRET`) and variables (`SEED_AUTH_PROVIDER_ID`, `SEED_AUTH_DISPLAY_NAME`, `SEED_AUTH_ISSUER_URL`, `SEED_AUTH_BUTTON_COLOR`, `CDK_PROJECT_PREFIX`, `AWS_REGION`) - - Single job: checkout, configure AWS credentials, run `scripts/stack-bootstrap/install.sh`, run `scripts/stack-bootstrap/seed.sh` - - Pass all `SEED_AUTH_*` and `CDK_*` env vars to the seed step - - _Requirements: 5.1, 5.2, 5.3, 5.4, 5.5, 5.6_ - -- [x] 5. Checkpoint — Verify workflow and scripts are wired correctly - - Ensure all tests pass, ask the user if questions arise. - -- [ ] 6. Write tests - - [ ] 6.1 Create test file `backend/tests/scripts/test_seed_bootstrap_data.py` with pytest fixtures using `moto` to mock DynamoDB tables and Secrets Manager, and `respx` or `httpx` mock for OIDC discovery - - Create DynamoDB tables matching production schemas (auth-providers, user-quotas, managed-models with GSIs) - - Create Secrets Manager secret with empty JSON `{}` - - _Requirements: 7.1, 7.2, 7.3, 7.4_ - - - [ ] 6.2 Write unit tests for auth provider seeding - - Test successful auth provider creation with all fields present - - Test idempotent skip when provider already exists - - Test missing env vars triggers skip with warning - - Test OIDC discovery failure logs warning and continues - - Test secret storage adds provider key to existing JSON - - _Requirements: 1.1, 1.2, 1.3, 1.4, 1.5, 8.3_ - - - [ ] 6.3 Write unit tests for quota seeding - - Test default tier has $50 monthly limit, 80% soft limit, block action - - Test default assignment has `default_tier` type, priority 100, linked to `default` tier - - Test idempotent skip for both tier and assignment - - _Requirements: 2.1, 2.2, 2.3, 3.1, 3.2, 3.3_ - - - [ ] 6.4 Write unit tests for model seeding - - Test Haiku 4.5 is marked as default, Sonnet 4.6 is not - - Test both models use global inference profile IDs (`us.anthropic.*`) - - Test `allowedAppRoles` and `availableToRoles` are empty lists - - Test deterministic UUID generation is consistent across runs - - Test idempotent skip when models already exist - - _Requirements: 4.1, 4.2, 4.3, 4.4, 4.5, 4.6_ - - - [ ] 6.5 Write unit tests for summary reporting - - Test summary includes counts for all four categories - - Test exit code 0 when all items created or all skipped - - Test exit code 1 when any operation fails - - _Requirements: 8.1, 8.2, 8.4_ - - - [ ] 6.6 Write property test: Auth provider item schema correctness (Property 1) - - **Property 1: Auth provider item schema correctness** - - Generate random valid provider configs via Hypothesis, verify DynamoDB item has correct PK/SK pattern and all required fields - - **Validates: Requirements 1.1** - - - [ ] 6.7 Write property test: Secret storage round-trip (Property 2) - - **Property 2: Secret storage round-trip** - - Generate random provider IDs and secrets, verify round-trip through mocked Secrets Manager - - **Validates: Requirements 1.2** - - - [ ] 6.8 Write property test: OIDC discovery endpoint mapping (Property 3) - - **Property 3: OIDC discovery endpoint mapping** - - Generate random discovery response dicts, verify field name mapping to DynamoDB item fields - - **Validates: Requirements 1.3** - - - [ ] 6.9 Write property test: Seed idempotence (Property 4) - - **Property 4: Seed idempotence** - - Generate random valid seed configs, run seeder twice against mocked DynamoDB, verify identical state and second run has created=0 - - **Validates: Requirements 1.4, 2.3, 3.3, 4.4, 7.1, 7.2, 7.4** - - - [ ] 6.10 Write property test: Model registration field completeness (Property 5) - - **Property 5: Model registration field completeness** - - Verify all default models have every required field present - - **Validates: Requirements 4.2, 4.6** - - - [ ] 6.11 Write property test: Exactly one default model invariant (Property 6) - - **Property 6: Exactly one default model invariant** - - Run model seeder against mocked DynamoDB, count items with `isDefault=True`, assert exactly one - - **Validates: Requirements 4.3** - - - [ ] 6.12 Write property test: Summary accuracy (Property 7) - - **Property 7: Summary accuracy** - - Generate random pre-existing states, run seeder, verify `created + skipped + failed` equals total items attempted per category - - **Validates: Requirements 8.1, 8.4** - -- [ ] 7. Final checkpoint — Ensure all tests pass - - Ensure all tests pass, ask the user if questions arise. - -## Notes - -- Tasks marked with `*` are optional and can be skipped for faster MVP -- The design uses Python explicitly — all implementation code is Python 3.13+ with `boto3` and `httpx` -- Shell scripts follow `set -euo pipefail` and the Shell Scripts First philosophy -- Property tests use `hypothesis` with `@settings(max_examples=100)` and `moto` for AWS mocking -- Each task references specific requirements for traceability -- Checkpoints ensure incremental validation diff --git a/.kiro/specs/cognito-first-boot-auth/.config.kiro b/.kiro/specs/cognito-first-boot-auth/.config.kiro new file mode 100644 index 00000000..e127be15 --- /dev/null +++ b/.kiro/specs/cognito-first-boot-auth/.config.kiro @@ -0,0 +1 @@ +{"specId": "54b26117-d99e-4bd6-bc94-dec086d20473", "workflowType": "requirements-first", "specType": "feature"} \ No newline at end of file diff --git a/.kiro/specs/cognito-first-boot-auth/design.md b/.kiro/specs/cognito-first-boot-auth/design.md new file mode 100644 index 00000000..d36478bc --- /dev/null +++ b/.kiro/specs/cognito-first-boot-auth/design.md @@ -0,0 +1,888 @@ +# Design Document: Cognito First-Boot Authentication + +## Overview + +This design replaces the current multi-step authentication bootstrap (GitHub secrets → seed workflow → multi-runtime provisioning) with a WordPress-style first-boot experience powered by Amazon Cognito. The core insight: because Cognito issues its own JWTs regardless of which upstream provider authenticated the user, the entire system can use a **single AgentCore Runtime** with a **single Cognito JWT authorizer** — eliminating the multi-runtime architecture, the Runtime Provisioner Lambda, the Runtime Updater Lambda, and the auth provider bootstrap seed workflow. + +### What Changes + +| Component | Before | After | +|---|---|---| +| Identity Broker | Per-provider OIDC (direct) | Amazon Cognito User Pool | +| First User Setup | GitHub secrets + seed workflow | First-boot signup page | +| AgentCore Runtimes | One per auth provider (Lambda-managed) | Single runtime (CDK-managed) | +| JWT Validation | `GenericOIDCJWTValidator` (multi-issuer) | `CognitoJWTValidator` (single issuer) | +| Frontend Auth | Custom OIDC via App API routes | Cognito OAuth 2.0 endpoints | +| Federated IdPs | Stored in DynamoDB only | Registered in Cognito + DynamoDB | +| Runtime Provisioner Lambda | Required | Removed | +| Runtime Updater Lambda | Required | Removed | +| Auth seed workflow | Required | Removed (for auth; quota/model seeding retained) | + +### Key Design Decisions + +1. **Cognito as identity broker, not identity store**: Cognito federates to external IdPs (Entra ID, Okta, Google) and issues its own JWTs. The application never validates upstream provider tokens directly. +2. **CDK-managed User Pool**: The Cognito User Pool, App Client, and Domain are created in the Infrastructure Stack via CDK — no manual setup required. +3. **First-boot via backend API**: The frontend detects a fresh deployment via `GET /system/status`, shows a setup page, and the backend creates the admin user via Cognito Admin API + assigns the `system_admin` role. +4. **Admin CRUD maps to Cognito APIs**: When an admin adds/updates/deletes a federated provider in the UI, the App API calls Cognito `CreateIdentityProvider`/`UpdateIdentityProvider`/`DeleteIdentityProvider` and updates the App Client's supported providers list. +5. **Single runtime with Cognito discovery URL**: The InferenceApiStack configures one AgentCore Runtime with `discoveryUrl` pointing to `https://cognito-idp.{region}.amazonaws.com/{userPoolId}/.well-known/openid-configuration`. + +## Architecture + +### High-Level Flow + +```mermaid +flowchart TD + subgraph "Infrastructure Stack (CDK)" + CUP[Cognito User Pool] + CAC[Cognito App Client] + CD[Cognito Domain] + SSM_C[SSM Parameters
user-pool-id, app-client-id,
domain-url, issuer-url] + end + + subgraph "App API Stack" + FA[Fargate Service
App API] + FB[First-Boot Endpoint
POST /system/first-boot] + FP[Federated Provider CRUD
/admin/auth-providers] + SS[System Status
GET /system/status] + end + + subgraph "Inference API Stack" + RT[Single AgentCore Runtime
Cognito JWT Authorizer] + end + + subgraph "Frontend" + FE[Angular App] + FBP[First-Boot Page] + LP[Login Page] + end + + CUP --> SSM_C + SSM_C --> FA + SSM_C --> RT + + FE -->|first visit| SS + SS -->|not bootstrapped| FBP + FBP -->|POST /system/first-boot| FB + FB -->|AdminCreateUser| CUP + FB -->|assign system_admin| FA + + SS -->|bootstrapped| LP + LP -->|redirect| CD + CD -->|auth code| FE + FE -->|exchange code| FA + + FP -->|CreateIdentityProvider| CUP + FP -->|UpdateUserPoolClient| CAC + + FE -->|Cognito JWT| RT +``` + +### Authentication Flow (Post First-Boot) + +```mermaid +sequenceDiagram + participant U as User + participant FE as Frontend + participant CG as Cognito + participant IdP as External IdP + participant API as App API + participant RT as AgentCore Runtime + + U->>FE: Click "Login with Okta" + FE->>CG: GET /authorize?identity_provider=Okta&... + CG->>IdP: Redirect to Okta + IdP->>U: Authenticate + U->>IdP: Credentials + IdP->>CG: Authorization code + CG->>CG: Exchange code, map attributes + CG->>FE: Redirect with Cognito auth code + FE->>CG: POST /oauth2/token (code + PKCE verifier) + CG->>FE: Cognito ID token + access token + refresh token + FE->>API: API calls with Cognito access token + API->>API: Validate JWT against Cognito JWKS + FE->>RT: Invoke with Cognito access token + RT->>RT: Validate JWT against Cognito JWKS +``` + +### First-Boot Flow + +```mermaid +sequenceDiagram + participant U as First User + participant FE as Frontend + participant API as App API + participant CG as Cognito User Pool + participant DB as DynamoDB + + FE->>API: GET /system/status + API->>DB: Check SYSTEM_SETTINGS#first-boot + DB->>API: Not found (fresh deployment) + API->>FE: { first_boot_completed: false } + FE->>FE: Show first-boot setup page + + U->>FE: Enter username, email, password + FE->>API: POST /system/first-boot { username, email, password } + API->>DB: Check first-boot not already completed (atomic) + API->>CG: AdminCreateUser(username, email, temporary_password) + API->>CG: AdminSetUserPassword(username, password, permanent=true) + API->>DB: Create user record with system_admin role + API->>DB: Write SYSTEM_SETTINGS#first-boot { completed: true } + API->>CG: UpdateUserPoolClient(... remove ALLOW_USER_SRP_AUTH if needed) + API->>FE: { success: true, redirect_url: "/auth/callback" } + + FE->>CG: POST /oauth2/token (admin credentials via SRP or redirect) + CG->>FE: Cognito tokens + FE->>FE: Store tokens, redirect to admin dashboard +``` + +## Components and Interfaces + +### 1. Cognito User Pool (Infrastructure Stack) + +The Infrastructure Stack creates the Cognito User Pool with CDK's L2 construct `cognito.UserPool`. + +```typescript +// infrastructure/lib/infrastructure-stack.ts (new section) + +const userPool = new cognito.UserPool(this, 'CognitoUserPool', { + userPoolName: getResourceName(config, 'user-pool'), + selfSignUpEnabled: true, // Enabled initially for first-boot; disabled after + signInAliases: { username: true, email: true }, + autoVerify: { email: true }, + standardAttributes: { + email: { required: true, mutable: true }, + givenName: { mutable: true }, + familyName: { mutable: true }, + }, + customAttributes: { + 'provider_sub': new cognito.StringAttribute({ mutable: true }), + }, + passwordPolicy: { + minLength: 8, + requireUppercase: true, + requireLowercase: true, + requireDigits: true, + requireSymbols: true, + }, + accountRecovery: cognito.AccountRecovery.EMAIL_ONLY, + removalPolicy: getRemovalPolicy(config), +}); +``` + +**App Client** configuration: + +```typescript +const callbackUrls = config.domainName + ? [`https://${config.domainName}/auth/callback`] + : ['http://localhost:4200/auth/callback']; + +const logoutUrls = config.domainName + ? [`https://${config.domainName}`] + : ['http://localhost:4200']; + +const appClient = userPool.addClient('CognitoAppClient', { + userPoolClientName: getResourceName(config, 'app-client'), + generateSecret: false, // SPA — no client secret + authFlows: { + userSrp: true, // For username/password login + custom: true, // For custom auth challenges + }, + oAuth: { + flows: { authorizationCodeGrant: true }, + scopes: [ + cognito.OAuthScope.OPENID, + cognito.OAuthScope.PROFILE, + cognito.OAuthScope.EMAIL, + ], + callbackUrls, + logoutUrls, + }, + preventUserExistenceErrors: true, + supportedIdentityProviders: [ + cognito.UserPoolClientIdentityProvider.COGNITO, + ], +}); +``` + +**Cognito Domain**: + +```typescript +// Prefix-based domain using project prefix +const cognitoDomain = userPool.addDomain('CognitoDomain', { + cognitoDomain: { domainPrefix: config.projectPrefix }, +}); +``` + +**SSM Exports**: + +| Parameter Path | Value | +|---|---| +| `/${projectPrefix}/auth/cognito/user-pool-id` | User Pool ID | +| `/${projectPrefix}/auth/cognito/user-pool-arn` | User Pool ARN | +| `/${projectPrefix}/auth/cognito/app-client-id` | App Client ID | +| `/${projectPrefix}/auth/cognito/domain-url` | `https://{prefix}.auth.{region}.amazoncognito.com` | +| `/${projectPrefix}/auth/cognito/issuer-url` | `https://cognito-idp.{region}.amazonaws.com/{userPoolId}` | + +### 2. First-Boot API Endpoints (App API) + +New routes in `backend/src/apis/app_api/system/routes.py`: + +```python +# GET /system/status — public, no auth required +@router.get("/status") +async def get_system_status() -> SystemStatusResponse: + """Check if first-boot has been completed.""" + settings = await system_settings_repo.get_first_boot_status() + return SystemStatusResponse( + first_boot_completed=settings is not None and settings.completed, + ) + +# POST /system/first-boot — public, no auth required, one-time only +@router.post("/first-boot") +async def first_boot(request: FirstBootRequest) -> FirstBootResponse: + """Create the initial admin user. Rejects if already completed.""" + # 1. Atomic check: if first-boot already done, return 409 + # 2. Create user in Cognito via AdminCreateUser + AdminSetUserPassword + # 3. Create user record in Users table with system_admin role + # 4. Mark first-boot completed in DynamoDB (conditional write) + # 5. Optionally disable self-signup on the User Pool + ... +``` + +**Request/Response Models**: + +```python +class FirstBootRequest(BaseModel): + username: str = Field(..., min_length=3, max_length=128) + email: str = Field(..., pattern=r'^[^@]+@[^@]+\.[^@]+$') + password: str = Field(..., min_length=8) + +class FirstBootResponse(BaseModel): + success: bool + user_id: str + message: str + +class SystemStatusResponse(BaseModel): + first_boot_completed: bool +``` + +**Race Condition Protection**: The first-boot completion write uses a DynamoDB conditional expression `attribute_not_exists(PK)` to ensure only one concurrent request succeeds. If the condition fails, the endpoint returns 409. + +### 3. Federated Identity Provider Management (App API) + +The existing `/admin/auth-providers` CRUD endpoints are extended to call Cognito APIs alongside DynamoDB writes. + +**Create Provider Flow**: + +```python +async def create_provider(data: AuthProviderCreate) -> AuthProvider: + # 1. OIDC discovery (existing logic) + # 2. Register in Cognito + cognito_client.create_identity_provider( + UserPoolId=user_pool_id, + ProviderName=data.provider_id, # Must be unique within pool + ProviderType='OIDC', + ProviderDetails={ + 'client_id': data.client_id, + 'client_secret': data.client_secret, + 'authorize_scopes': data.scopes, + 'oidc_issuer': data.issuer_url, + # Cognito auto-discovers endpoints from issuer + 'attributes_request_method': 'GET', + }, + AttributeMapping={ + 'email': 'email', + 'name': 'name', + 'given_name': 'given_name', + 'family_name': 'family_name', + 'picture': 'picture', + 'custom:provider_sub': 'sub', + }, + ) + # 3. Update App Client to include new provider + cognito_client.update_user_pool_client( + UserPoolId=user_pool_id, + ClientId=app_client_id, + SupportedIdentityProviders=[...existing, data.provider_id], + # Preserve all other client settings + ) + # 4. Save to DynamoDB (existing logic) + # 5. Save client secret to Secrets Manager (existing logic) + return provider +``` + +**Update Provider Flow**: Calls `UpdateIdentityProvider` with changed fields, then updates DynamoDB. + +**Delete Provider Flow**: Calls `DeleteIdentityProvider`, removes from App Client's `SupportedIdentityProviders`, then deletes from DynamoDB and Secrets Manager. + +**Cognito IAM Permissions** (added to App API task role): + +```typescript +taskDefinition.taskRole.addToPrincipalPolicy( + new iam.PolicyStatement({ + sid: 'CognitoIdentityProviderManagement', + effect: iam.Effect.ALLOW, + actions: [ + 'cognito-idp:CreateIdentityProvider', + 'cognito-idp:UpdateIdentityProvider', + 'cognito-idp:DeleteIdentityProvider', + 'cognito-idp:DescribeIdentityProvider', + 'cognito-idp:ListIdentityProviders', + 'cognito-idp:UpdateUserPoolClient', + 'cognito-idp:DescribeUserPoolClient', + 'cognito-idp:AdminCreateUser', + 'cognito-idp:AdminSetUserPassword', + 'cognito-idp:AdminGetUser', + 'cognito-idp:UpdateUserPool', + ], + resources: [cognitoUserPoolArn], + }) +); +``` + +### 4. Single AgentCore Runtime with Cognito JWT Authorizer (Inference API Stack) + +The InferenceApiStack creates a single CDK-managed runtime (replacing the Lambda-managed per-provider runtimes): + +```typescript +// infrastructure/lib/inference-api-stack.ts + +// Import Cognito config from SSM +const cognitoUserPoolId = ssm.StringParameter.valueForStringParameter( + this, `/${config.projectPrefix}/auth/cognito/user-pool-id` +); +const cognitoAppClientId = ssm.StringParameter.valueForStringParameter( + this, `/${config.projectPrefix}/auth/cognito/app-client-id` +); + +// Construct Cognito OIDC discovery URL +const cognitoDiscoveryUrl = `https://cognito-idp.${config.awsRegion}.amazonaws.com/${cognitoUserPoolId}/.well-known/openid-configuration`; + +const runtime = new bedrock.CfnRuntime(this, 'AgentCoreRuntime', { + agentRuntimeName: getResourceName(config, 'agentcore_runtime').replace(/-/g, '_'), + agentRuntimeArtifact: { + containerConfiguration: { containerUri: containerImageUri }, + }, + authorizerConfiguration: { + customJwtAuthorizer: { + discoveryUrl: cognitoDiscoveryUrl, + allowedClients: [cognitoAppClientId], + }, + }, + roleArn: runtimeExecutionRole.roleArn, + networkConfiguration: { networkMode: 'PUBLIC' }, + environmentVariables: { /* ... */ }, +}); +``` + +This single runtime accepts JWTs from all users because Cognito is the sole issuer — whether the user logged in with username/password or via a federated IdP (Entra ID, Okta, Google), the JWT is always issued by Cognito. + +### 5. Backend JWT Validation Migration + +Replace `GenericOIDCJWTValidator` with `CognitoJWTValidator`: + +```python +# backend/src/apis/shared/auth/cognito_jwt_validator.py + +class CognitoJWTValidator: + """Validates JWT tokens against a single Cognito User Pool.""" + + def __init__(self, user_pool_id: str, app_client_id: str, region: str): + self._issuer = f"https://cognito-idp.{region}.amazonaws.com/{user_pool_id}" + self._app_client_id = app_client_id + jwks_url = f"{self._issuer}/.well-known/jwks.json" + self._jwks_client = PyJWKClient(jwks_url, cache_keys=True) + + def validate_token(self, token: str) -> User: + signing_key = self._jwks_client.get_signing_key_from_jwt(token) + # Note: Cognito access tokens use `client_id` (not `aud`) for the app client. + # PyJWT's `audience` param checks the `aud` claim, which is only present in + # Cognito access tokens when resource binding is configured. Instead, we + # verify `client_id` manually after decoding. + payload = jwt.decode( + token, + signing_key.key, + algorithms=["RS256"], + issuer=self._issuer, + options={"verify_exp": True, "verify_aud": False}, + ) + # Validate client_id for access tokens, aud for ID tokens + token_client_id = payload.get("client_id") or payload.get("aud") + if token_client_id != self._app_client_id: + raise jwt.InvalidTokenError( + f"Token client_id/aud '{token_client_id}' does not match expected '{self._app_client_id}'" + ) + return User( + user_id=payload["sub"], + email=payload.get("email", ""), + name=payload.get("name", payload.get("cognito:username", "")), + roles=payload.get("custom:roles", "").split(",") if payload.get("custom:roles") else [], + picture=payload.get("picture"), + ) +``` + +**Claim Mapping** (Cognito token claims): + +| Cognito Claim | Maps To | Source | +|---|---|---| +| `sub` | `user_id` | Cognito-generated UUID | +| `email` | `email` | From Cognito or federated IdP | +| `name` | `name` | From Cognito or federated IdP | +| `cognito:username` | `username` | Cognito username | +| `cognito:groups` | `roles` | Cognito User Pool Groups | +| `custom:provider_sub` | (stored) | Original IdP `sub` claim | +| `picture` | `picture` | From federated IdP | + +**Updated `get_current_user` dependency**: + +```python +async def get_current_user(credentials = Depends(security)) -> User: + if credentials is None: + raise HTTPException(status_code=401, detail="Authentication required.") + token = credentials.credentials + validator = _get_cognito_validator() + user = validator.validate_token(token) + user.raw_token = token + # Fire-and-forget sync to Users table + sync_service = _get_user_sync_service() + if sync_service and sync_service.enabled: + asyncio.create_task(_sync_user_background(sync_service, user)) + return user +``` + +### 6. Frontend Authentication Flow Migration + +The Angular `AuthService` is updated to use Cognito OAuth 2.0 endpoints directly: + +```typescript +// Key changes to auth.service.ts + +// Cognito endpoints derived from environment config +private cognitoDomain = environment.cognitoDomainUrl; +private cognitoClientId = environment.cognitoAppClientId; +private redirectUri = `${window.location.origin}/auth/callback`; + +async login(providerId?: string): Promise { + const state = this.generateRandomState(); + const codeVerifier = this.generateCodeVerifier(); + const codeChallenge = await this.generateCodeChallenge(codeVerifier); + + sessionStorage.setItem('auth_state', state); + sessionStorage.setItem('auth_code_verifier', codeVerifier); + + const params = new URLSearchParams({ + response_type: 'code', + client_id: this.cognitoClientId, + redirect_uri: this.redirectUri, + scope: 'openid profile email', + state, + code_challenge: codeChallenge, + code_challenge_method: 'S256', + }); + + // If a specific federated provider is selected, add identity_provider param + if (providerId) { + params.set('identity_provider', providerId); + } + + window.location.href = `${this.cognitoDomain}/oauth2/authorize?${params}`; +} + +async handleCallback(code: string, state: string): Promise { + // Verify state matches + const storedState = sessionStorage.getItem('auth_state'); + if (state !== storedState) throw new Error('State mismatch'); + + const codeVerifier = sessionStorage.getItem('auth_code_verifier'); + + // Exchange code for tokens directly with Cognito + const response = await fetch(`${this.cognitoDomain}/oauth2/token`, { + method: 'POST', + headers: { 'Content-Type': 'application/x-www-form-urlencoded' }, + body: new URLSearchParams({ + grant_type: 'authorization_code', + client_id: this.cognitoClientId, + code, + redirect_uri: this.redirectUri, + code_verifier: codeVerifier!, + }), + }); + + const tokens = await response.json(); + this.storeTokens(tokens); +} +``` + +**Login Page**: Displays a username/password form (for Cognito native users) plus buttons for each configured federated provider (fetched from `GET /auth/providers`). Clicking a federated provider button calls `login(providerId)` which redirects to Cognito with `identity_provider={providerId}`. + +### 7. Removal Plan + +#### Remove from App API Stack (`app-api-stack.ts`): +- Runtime Provisioner Lambda function and DynamoDB Stream trigger +- Runtime Updater Lambda function and EventBridge trigger +- SNS topic and CloudWatch alarms for runtime provisioning +- `GET /auth/runtime-endpoint` route + +#### Remove from Inference API Stack (`inference-api-stack.ts`): +- Nothing removed — the stack already creates shared resources. The single runtime is now CDK-managed here instead of Lambda-managed. + +#### Remove from Config (`config.ts`): +- `entraClientId`, `entraTenantId` from `AppConfig` +- `entraRedirectUri` from `AppApiConfig` +- All Entra ID loading in `loadConfig()` + +#### Remove from App API ECS environment: +- `ENTRA_CLIENT_ID`, `ENTRA_TENANT_ID`, `ENTRA_REDIRECT_URI` env vars +- `ENTRA_CLIENT_SECRET` secret + +#### Remove from GitHub workflows: +- `CDK_ENTRA_CLIENT_ID`, `CDK_ENTRA_TENANT_ID`, `CDK_APP_API_ENTRA_REDIRECT_URI` variables +- `CDK_ENTRA_CLIENT_SECRET` secret + +#### Remove from `scripts/common/load-env.sh`: +- Entra ID environment variable exports and context parameter generation + +#### Remove from stack deployment scripts: +- Entra ID context parameters from all `synth.sh` and `deploy.sh` files + +#### Remove from bootstrap seed workflow: +- Auth provider seeding job (`SEED_AUTH_*` variables/secrets) +- Auth provider seeding logic in `seed.sh` and `seed_bootstrap_data.py` +- Retain: quota tier, quota assignment, and model seeding + +#### Remove from backend: +- `GenericOIDCJWTValidator` class +- Multi-provider issuer resolution logic in `dependencies.py` +- `backend/lambda-functions/runtime-provisioner/` directory +- `backend/lambda-functions/runtime-updater/` directory + +#### Remove from frontend: +- Per-provider runtime endpoint resolution +- `getRuntimeEndpoint()` API call + + + +## Data Models + +### SSM Parameter Paths (New — Cognito) + +| Parameter Path | Created By | Consumed By | Value | +|---|---|---|---| +| `/${projectPrefix}/auth/cognito/user-pool-id` | InfrastructureStack | AppApiStack, InferenceApiStack | Cognito User Pool ID | +| `/${projectPrefix}/auth/cognito/user-pool-arn` | InfrastructureStack | AppApiStack | Cognito User Pool ARN | +| `/${projectPrefix}/auth/cognito/app-client-id` | InfrastructureStack | AppApiStack, InferenceApiStack, FrontendStack | Cognito App Client ID | +| `/${projectPrefix}/auth/cognito/domain-url` | InfrastructureStack | AppApiStack, FrontendStack | `https://{prefix}.auth.{region}.amazoncognito.com` | +| `/${projectPrefix}/auth/cognito/issuer-url` | InfrastructureStack | AppApiStack | `https://cognito-idp.{region}.amazonaws.com/{userPoolId}` | + +### DynamoDB: System Settings Item + +Stored in an existing table (e.g., the Users table or a dedicated settings table). Uses a single-item pattern: + +``` +PK: "SYSTEM_SETTINGS#first-boot" +SK: "SYSTEM_SETTINGS#first-boot" +Attributes: + completed: boolean (true) + completedAt: string (ISO 8601) + completedBy: string (admin user ID) + adminUsername: string + adminEmail: string +``` + +**Idempotency**: The `POST /system/first-boot` endpoint uses `attribute_not_exists(PK)` as a condition expression on the `put_item` call. If two requests race, exactly one succeeds and the other gets a `ConditionalCheckFailedException` → 409 Conflict. + +### DynamoDB: Auth Providers Table (Modified) + +The existing `AUTH_PROVIDER#{id}` items gain a new optional field: + +``` +cognitoProviderName: string # The name registered in Cognito (matches provider_id) +``` + +The `agentcore_runtime_*` fields are retained but deprecated — the App API stops writing to them for new providers. Existing values are left in place for reference during migration. + +### Cognito Attribute Mappings + +When registering a federated OIDC provider in Cognito, the following attribute mappings are configured: + +| Cognito Attribute | Provider Claim | Notes | +|---|---|---| +| `email` | `email` | Required; sign-in rejected if missing | +| `name` | `name` | Display name | +| `given_name` | `given_name` | First name | +| `family_name` | `family_name` | Last name | +| `picture` | `picture` | Profile picture URL | +| `custom:provider_sub` | `sub` | Original provider user ID | + +Admins can customize these mappings per provider via the admin UI. The App API passes the custom mappings to `CreateIdentityProvider`'s `AttributeMapping` parameter. + +### CDK Configuration Changes (`config.ts`) + +New `CognitoConfig` interface added to `AppConfig`: + +```typescript +export interface CognitoConfig { + domainPrefix?: string; // Custom Cognito domain prefix (defaults to projectPrefix) + callbackUrls?: string[]; // Additional callback URLs beyond auto-derived + logoutUrls?: string[]; // Additional logout URLs beyond auto-derived + passwordMinLength?: number; // Override default 8 +} + +export interface AppConfig { + // ... existing fields + cognito: CognitoConfig; + // REMOVED: entraClientId, entraTenantId +} + +export interface AppApiConfig { + // ... existing fields + // REMOVED: entraRedirectUri +} +``` + +Loading in `loadConfig()`: + +```typescript +cognito: { + domainPrefix: process.env.CDK_COGNITO_DOMAIN_PREFIX + || scope.node.tryGetContext('cognito')?.domainPrefix + || projectPrefix, + callbackUrls: process.env.CDK_COGNITO_CALLBACK_URLS?.split(',') + || scope.node.tryGetContext('cognito')?.callbackUrls, + logoutUrls: process.env.CDK_COGNITO_LOGOUT_URLS?.split(',') + || scope.node.tryGetContext('cognito')?.logoutUrls, + passwordMinLength: parseIntEnv(process.env.CDK_COGNITO_PASSWORD_MIN_LENGTH) + || scope.node.tryGetContext('cognito')?.passwordMinLength + || 8, +}, +``` + +### Frontend Environment Configuration + +New environment variables for the Angular app: + +```typescript +// frontend/ai.client/src/environments/environment.ts +export const environment = { + production: false, + appApiUrl: 'http://localhost:8000', + // Cognito configuration (injected at build time or fetched from /system/config) + cognitoDomainUrl: '', // e.g., https://myprefix.auth.us-east-1.amazoncognito.com + cognitoAppClientId: '', // e.g., 1abc2def3ghi4jkl5mno + cognitoRegion: 'us-east-1', + // Single runtime endpoint (replaces per-provider resolution) + inferenceApiUrl: 'http://localhost:8001', +}; +``` + +These values can be injected at deploy time by the frontend build script reading from SSM, or served by a `GET /system/config` endpoint from the App API. + + + +## Correctness Properties + +*A property is a characteristic or behavior that should hold true across all valid executions of a system — essentially, a formal statement about what the system should do. Properties serve as the bridge between human-readable specifications and machine-verifiable correctness guarantees.* + +### Property 1: Cognito SSM export path correctness + +*For any* valid project prefix, the Infrastructure Stack SHALL export Cognito resource identifiers to SSM parameters whose paths all begin with `/${projectPrefix}/auth/cognito/` and include at minimum: `user-pool-id`, `user-pool-arn`, `app-client-id`, `domain-url`, and `issuer-url`. + +**Validates: Requirements 1.4, 13.3** + +### Property 2: Callback URL derivation from domain configuration + +*For any* CDK configuration, if `domainName` is provided, the Cognito App Client callback URLs SHALL include `https://{domainName}/auth/callback`; if `domainName` is not provided, the callback URLs SHALL include `http://localhost:4200/auth/callback` as the default development fallback. + +**Validates: Requirements 1.7, 1.8** + +### Property 3: First-boot creates admin with correct role + +*For any* valid first-boot request (username, email, password), after the `POST /system/first-boot` endpoint succeeds, the Cognito User Pool SHALL contain a user with the given username and email, the Users DynamoDB table SHALL contain a record with the `system_admin` role, and the `SYSTEM_SETTINGS#first-boot` item SHALL exist in DynamoDB with `completed=true`. + +**Validates: Requirements 2.3, 2.4, 2.5** + +### Property 4: First-boot rejection after completion + +*For any* number of `POST /system/first-boot` requests after the first successful one, the App API SHALL return HTTP 409 Conflict and the system state SHALL remain unchanged from the first successful boot. + +**Validates: Requirements 2.7** + +### Property 5: First-boot disables self-signup + +*For any* successful first-boot completion, the App API SHALL call Cognito's `UpdateUserPool` API to set `AdminCreateUserConfig.AllowAdminCreateUserOnly` to `true`, preventing further self-signup. + +**Validates: Requirements 2.6** + +### Property 6: Cognito JWT validation rejects invalid tokens + +*For any* JWT token, the `CognitoJWTValidator` SHALL accept the token if and only if: (a) the signature is valid against the Cognito JWKS, (b) the issuer matches `https://cognito-idp.{region}.amazonaws.com/{userPoolId}`, (c) the `client_id` claim (for access tokens) or `aud` claim (for ID tokens) matches the Cognito App Client ID, and (d) the token is not expired. + +**Validates: Requirements 3.4, 10.1, 10.2, 10.3** + +### Property 7: Cognito claim extraction correctness + +*For any* valid Cognito JWT payload containing `sub`, `email`, `name`, and `cognito:groups` claims, the `CognitoJWTValidator.validate_token()` SHALL return a `User` object where `user_id` equals the `sub` claim, `email` equals the `email` claim, `name` equals the `name` claim (falling back to `cognito:username`), and `roles` equals the `cognito:groups` list. + +**Validates: Requirements 3.6, 10.4** + +### Property 8: Provider creation registers in Cognito with correct attribute mappings + +*For any* valid auth provider configuration with custom attribute mappings, the `create_provider` function SHALL call Cognito `CreateIdentityProvider` with `ProviderDetails` containing the issuer URL and client ID, and `AttributeMapping` containing at minimum `email→email` and `custom:provider_sub→sub`, plus any admin-specified custom mappings. + +**Validates: Requirements 4.1, 4.3, 9.1, 9.2, 9.4** + +### Property 9: Provider creation stores configuration in DynamoDB and Secrets Manager + +*For any* valid auth provider creation request, the provider configuration SHALL be stored in the Auth Providers DynamoDB table with PK `AUTH_PROVIDER#{providerId}`, and the client secret SHALL be stored in Secrets Manager under the provider ID key. + +**Validates: Requirements 4.2** + +### Property 10: Provider creation updates App Client supported providers + +*For any* successful provider creation, the App API SHALL call `UpdateUserPoolClient` with `SupportedIdentityProviders` containing the new provider name in addition to all previously supported providers (including `COGNITO`). + +**Validates: Requirements 4.4** + +### Property 11: Provider update syncs to Cognito + +*For any* valid provider update that changes OIDC configuration (issuer URL, client ID, or attribute mappings), the App API SHALL call `UpdateIdentityProvider` with the updated `ProviderDetails` and/or `AttributeMapping`. + +**Validates: Requirements 4.5** + +### Property 12: Provider deletion removes from Cognito and App Client + +*For any* provider deletion, the App API SHALL call `DeleteIdentityProvider` to remove the provider from the Cognito User Pool AND call `UpdateUserPoolClient` to remove the provider from `SupportedIdentityProviders`, AND delete the provider from DynamoDB and its secret from Secrets Manager. + +**Validates: Requirements 4.6** + +### Property 13: Cognito discovery URL construction + +*For any* valid AWS region string and Cognito User Pool ID, the discovery URL SHALL be constructed as `https://cognito-idp.{region}.amazonaws.com/{userPoolId}/.well-known/openid-configuration`. + +**Validates: Requirements 5.6** + +### Property 14: New providers do not write deprecated runtime fields + +*For any* new auth provider created after the Cognito migration, the DynamoDB item SHALL NOT contain non-null values for `agentcoreRuntimeArn`, `agentcoreRuntimeId`, or `agentcoreRuntimeEndpointUrl`. + +**Validates: Requirements 6.4** + +### Property 15: System status round-trip + +*For any* DynamoDB state, the `GET /system/status` endpoint SHALL return `first_boot_completed=true` if and only if the `SYSTEM_SETTINGS#first-boot` item exists in DynamoDB with `completed=true`; otherwise it SHALL return `first_boot_completed=false`. + +**Validates: Requirements 12.1, 12.2** + +### Property 16: Concurrent first-boot safety + +*For any* number of concurrent `POST /system/first-boot` requests on a fresh deployment, exactly one SHALL succeed (HTTP 200) and all others SHALL fail (HTTP 409), and the DynamoDB table SHALL contain exactly one `SYSTEM_SETTINGS#first-boot` item and exactly one admin user. + +**Validates: Requirements 12.4** + +### Property 17: CDK config loading with environment variable overrides + +*For any* CDK configuration where both an environment variable (`CDK_COGNITO_DOMAIN_PREFIX`) and a CDK context value (`cognito.domainPrefix`) are set, the environment variable SHALL take precedence over the context value. + +**Validates: Requirements 13.2** + +## Error Handling + +| Scenario | Behavior | HTTP Status | +|---|---|---| +| First-boot attempted after completion | Return error, no state change | 409 Conflict | +| First-boot with invalid password (doesn't meet policy) | Return Cognito error details | 400 Bad Request | +| First-boot with duplicate username in Cognito | Return error, no state change | 409 Conflict | +| First-boot Cognito API failure (AdminCreateUser) | Return error, do NOT mark first-boot complete | 500 Internal Server Error | +| First-boot DynamoDB conditional write failure (race) | Return conflict error | 409 Conflict | +| Cognito CreateIdentityProvider failure (duplicate name) | Return Cognito error details, no DynamoDB write | 400 Bad Request | +| Cognito CreateIdentityProvider failure (invalid issuer) | Return Cognito error details, no DynamoDB write | 400 Bad Request | +| Cognito UpdateIdentityProvider failure | Return error, DynamoDB not updated | 500 Internal Server Error | +| Cognito DeleteIdentityProvider failure (not found) | Log warning, continue with DynamoDB deletion | 200 (idempotent) | +| Cognito UpdateUserPoolClient failure | Return error, roll back CreateIdentityProvider if during creation | 500 Internal Server Error | +| JWT validation: invalid signature | Reject request | 401 Unauthorized | +| JWT validation: expired token | Reject with "Token expired" message | 401 Unauthorized | +| JWT validation: wrong issuer | Reject request | 401 Unauthorized | +| JWT validation: wrong audience | Reject request | 401 Unauthorized | +| JWT validation: Cognito JWKS endpoint unreachable | Reject with "Authentication service unavailable" | 503 Service Unavailable | +| System status endpoint: DynamoDB read failure | Return `first_boot_completed: false` (safe default) | 200 OK | +| Federated provider missing required email attribute | Cognito rejects sign-in; frontend shows descriptive error | N/A (Cognito-side) | +| OIDC discovery failure during provider creation | Return error with discovery failure details | 400 Bad Request | + +### Rollback Strategy for Provider Creation + +Provider creation involves multiple steps (Cognito + DynamoDB + Secrets Manager). If any step fails after a previous step succeeded: + +1. **Cognito CreateIdentityProvider succeeds, UpdateUserPoolClient fails**: Delete the identity provider from Cognito (rollback), return error. +2. **Cognito succeeds, DynamoDB write fails**: Delete identity provider from Cognito, return error. +3. **Cognito + DynamoDB succeed, Secrets Manager fails**: Delete from DynamoDB, delete identity provider from Cognito, return error. + +Each rollback step is wrapped in try/except to avoid masking the original error. + +## Testing Strategy + +### Dual Testing Approach + +This feature requires both unit tests and property-based tests: + +- **Unit tests** (pytest): Specific examples, edge cases, error conditions, CDK template assertions +- **Property-based tests** (pytest + Hypothesis): Universal properties across randomized inputs + +Both are complementary — unit tests catch concrete bugs with known inputs, property tests verify general correctness across the input space. + +### Property-Based Testing Configuration + +- **Library**: `hypothesis` (Python) — already used in the project (see `backend/.hypothesis/`) +- **Minimum iterations**: 100 per property test (`@settings(max_examples=100)`) +- **Tag format**: `Feature: cognito-first-boot-auth, Property {N}: {title}` +- **Each correctness property is implemented by a single property-based test** +- **Mock infrastructure**: `moto` for DynamoDB, Secrets Manager, and Cognito; `unittest.mock` for Cognito API calls where moto coverage is insufficient + +### Unit Tests + +Focus on specific examples and edge cases: + +- CDK template assertions: Cognito User Pool has correct password policy, App Client has correct OAuth config, SSM parameters exist with correct paths +- First-boot with valid credentials creates admin user (happy path) +- First-boot with weak password returns 400 +- First-boot after completion returns 409 +- Provider creation with OIDC discovery populates endpoints +- Provider deletion cleans up Cognito + DynamoDB + Secrets Manager +- `CognitoJWTValidator` rejects tokens with wrong issuer +- `CognitoJWTValidator` rejects expired tokens +- System status returns false on fresh deployment +- System status returns true after first-boot +- Config loading: `CDK_COGNITO_DOMAIN_PREFIX` env var overrides context + +### Property-Based Tests + +Each correctness property maps to one Hypothesis test: + +- **Feature: cognito-first-boot-auth, Property 1: Cognito SSM export path correctness** — Generate random valid project prefixes, verify SSM parameter paths follow convention +- **Feature: cognito-first-boot-auth, Property 2: Callback URL derivation** — Generate random domain names (or None), verify callback URLs are derived correctly +- **Feature: cognito-first-boot-auth, Property 3: First-boot creates admin** — Generate random valid usernames/emails/passwords, run first-boot against mocked Cognito+DynamoDB, verify admin user and settings +- **Feature: cognito-first-boot-auth, Property 4: First-boot rejection** — Generate random valid first-boot requests, run first-boot twice, verify second returns 409 +- **Feature: cognito-first-boot-auth, Property 5: First-boot disables self-signup** — Generate random first-boot requests, verify UpdateUserPool is called with AllowAdminCreateUserOnly=true +- **Feature: cognito-first-boot-auth, Property 6: JWT validation** — Generate random JWT payloads with valid/invalid issuers/audiences, verify accept/reject behavior +- **Feature: cognito-first-boot-auth, Property 7: Claim extraction** — Generate random Cognito-style JWT payloads, verify User object fields match claims +- **Feature: cognito-first-boot-auth, Property 8: Provider creation Cognito registration** — Generate random provider configs with custom attribute mappings, verify CreateIdentityProvider call parameters +- **Feature: cognito-first-boot-auth, Property 9: Provider creation DynamoDB + Secrets Manager** — Generate random provider configs, verify DynamoDB item and Secrets Manager write +- **Feature: cognito-first-boot-auth, Property 10: Provider creation App Client update** — Generate random sequences of provider creations, verify SupportedIdentityProviders grows correctly +- **Feature: cognito-first-boot-auth, Property 11: Provider update Cognito sync** — Generate random provider updates, verify UpdateIdentityProvider is called with correct params +- **Feature: cognito-first-boot-auth, Property 12: Provider deletion cleanup** — Generate random provider creation+deletion sequences, verify all resources are cleaned up +- **Feature: cognito-first-boot-auth, Property 13: Discovery URL construction** — Generate random region strings and User Pool IDs, verify URL format +- **Feature: cognito-first-boot-auth, Property 14: No deprecated runtime fields** — Generate random new provider configs, verify DynamoDB items lack runtime fields +- **Feature: cognito-first-boot-auth, Property 15: System status round-trip** — Generate random DynamoDB states (with/without first-boot item), verify endpoint response matches +- **Feature: cognito-first-boot-auth, Property 16: Concurrent first-boot safety** — Generate random concurrent first-boot requests, verify exactly one succeeds +- **Feature: cognito-first-boot-auth, Property 17: Config env var override** — Generate random env var and context values, verify env var wins + +### Test Infrastructure + +- `moto` for mocking AWS services (DynamoDB, Secrets Manager, Cognito) +- `httpx` or `responses` for mocking OIDC discovery HTTP calls +- `PyJWT` for generating test JWT tokens with known signing keys +- `hypothesis` strategies for generating valid usernames, emails, passwords, provider configs, JWT payloads +- Tests located at: + - `backend/tests/apis/shared/auth/test_cognito_jwt_validator.py` + - `backend/tests/apis/app_api/system/test_first_boot.py` + - `backend/tests/apis/app_api/admin/test_auth_providers_cognito.py` + - `infrastructure/test/cognito-infrastructure.test.ts` (CDK assertions) diff --git a/.kiro/specs/cognito-first-boot-auth/requirements.md b/.kiro/specs/cognito-first-boot-auth/requirements.md new file mode 100644 index 00000000..38498756 --- /dev/null +++ b/.kiro/specs/cognito-first-boot-auth/requirements.md @@ -0,0 +1,201 @@ +# Requirements Document + +## Introduction + +This feature replaces the current multi-step, error-prone authentication bootstrap process with a WordPress-style first-boot experience powered by Amazon Cognito. Today, deploying the application requires manually configuring GitHub variables/secrets with OIDC provider details (issuer URL, client ID, client secret, etc.), deploying all stacks, then running a separate bootstrap seed workflow. If any value is mistyped, authentication breaks silently. + +The new approach deploys a Cognito User Pool as the central identity broker during infrastructure provisioning. The first person to access the deployment signs up with username/password and becomes the system admin. That admin can then configure additional federated identity providers (Entra ID, Okta, Google, etc.) through the admin UI, which wires them into Cognito as federated identity providers. Because Cognito issues its own JWTs regardless of which upstream provider authenticated the user, the entire system can use a single AgentCore Runtime with a single Cognito JWT authorizer — eliminating the multi-runtime architecture, the Runtime Provisioner Lambda, and the bootstrap seed workflow for auth. + +## Glossary + +- **Cognito_User_Pool**: The Amazon Cognito User Pool deployed as part of the infrastructure stack, serving as the central identity broker for all authentication +- **Cognito_App_Client**: The Cognito User Pool App Client configured for the frontend application, enabling OAuth 2.0 / OIDC flows +- **Cognito_Domain**: The Cognito hosted UI domain (custom or prefix-based) used for OAuth 2.0 endpoints +- **First_Boot_Flow**: The initial setup experience where the first user to access a fresh deployment creates an admin account via Cognito username/password signup +- **Admin_User**: The first user who completes the First_Boot_Flow, automatically assigned the system admin role +- **Federated_Identity_Provider**: An external OIDC identity provider (Entra ID, Okta, Google, etc.) configured as a Cognito User Pool Identity Provider +- **App_API**: The FastAPI backend service running on Fargate that handles application logic, auth flows, and admin operations +- **Inference_Runtime**: The single AWS Bedrock AgentCore Runtime configured with a Cognito JWT authorizer +- **Auth_Providers_Table**: The DynamoDB table storing authentication provider configurations (PK: `AUTH_PROVIDER#{id}`) +- **System_Settings_Table**: The DynamoDB table (or item within an existing table) storing system-level configuration such as first-boot completion status +- **Frontend**: The Angular application served via CloudFront +- **Admin_UI**: The admin section of the Frontend used for managing authentication providers and system configuration +- **Bootstrap_Seed_Workflow**: The existing GitHub Actions workflow (`bootstrap-data-seeding.yml`) that seeds auth provider config from GitHub variables/secrets (being replaced for auth seeding) +- **Runtime_Provisioner_Lambda**: The existing Lambda function that provisions per-provider AgentCore Runtimes via DynamoDB Streams (being removed) +- **Runtime_Updater_Lambda**: The existing Lambda function that updates all provider runtimes when container images change (being removed) + +## Requirements + +### Requirement 1: Cognito User Pool Infrastructure + +**User Story:** As a platform operator, I want a Cognito User Pool deployed automatically with the infrastructure stack, so that authentication is available immediately after deployment without manual configuration. + +#### Acceptance Criteria + +1. THE Infrastructure_Stack SHALL create a Cognito_User_Pool with username/password sign-in enabled and email as a required attribute +2. THE Infrastructure_Stack SHALL create a Cognito_App_Client configured with the authorization code grant flow, PKCE support, and scopes `openid`, `profile`, and `email` +3. THE Infrastructure_Stack SHALL create a Cognito_Domain (prefix-based using the project prefix, or custom domain when `domainName` is configured) +4. THE Infrastructure_Stack SHALL export the Cognito_User_Pool ID, Cognito_App_Client ID, Cognito_Domain URL, and Cognito issuer URL to SSM Parameter Store under `/${projectPrefix}/auth/cognito/...` paths +5. THE Infrastructure_Stack SHALL configure the Cognito_User_Pool with a password policy requiring a minimum of 8 characters, at least one uppercase letter, one lowercase letter, one number, and one special character +6. THE Infrastructure_Stack SHALL configure the Cognito_User_Pool with self-signup enabled for the first-boot flow, with admin-only signup enforced after first-boot completion +7. IF the `domainName` configuration is provided, THEN THE Infrastructure_Stack SHALL configure the Cognito_App_Client callback and logout URLs using that domain +8. IF the `domainName` configuration is not provided, THEN THE Infrastructure_Stack SHALL configure the Cognito_App_Client callback and logout URLs using the CloudFront distribution URL + +### Requirement 2: First-Boot Admin Registration + +**User Story:** As the first person to access a fresh deployment, I want to sign up with a username and password and become the system admin, so that I can configure the platform without needing pre-configured GitHub secrets. + +#### Acceptance Criteria + +1. WHEN a user accesses the Frontend for the first time on a fresh deployment, THE Frontend SHALL detect that first-boot has not been completed and display a first-boot setup page +2. THE First_Boot_Flow setup page SHALL collect a username, email address, and password from the user +3. WHEN the user submits the first-boot registration form, THE App_API SHALL create the user in the Cognito_User_Pool using the Cognito admin API +4. WHEN the user is successfully created in the Cognito_User_Pool, THE App_API SHALL assign the `system_admin` role to that user in the application's RBAC system +5. WHEN the admin user is created and assigned the admin role, THE App_API SHALL mark first-boot as completed in the System_Settings_Table +6. AFTER first-boot is marked as completed, THE App_API SHALL disable self-signup on the Cognito_User_Pool so that only federated identity providers or admin-created users can register +7. IF a second user attempts to access the first-boot registration endpoint after first-boot is completed, THEN THE App_API SHALL reject the request with a 409 Conflict status +8. THE First_Boot_Flow SHALL authenticate the newly created admin user and redirect to the admin dashboard upon successful registration + +### Requirement 3: Cognito-Based Authentication Flow + +**User Story:** As a user, I want to authenticate through Cognito using either username/password or my organization's identity provider, so that I have a consistent login experience regardless of authentication method. + +#### Acceptance Criteria + +1. THE App_API SHALL implement OAuth 2.0 authorization code flow with PKCE using Cognito as the authorization server +2. WHEN a user initiates login, THE Frontend SHALL redirect to the Cognito hosted UI or directly to the configured identity provider's authorization endpoint via Cognito +3. WHEN Cognito returns an authorization code, THE App_API SHALL exchange the code for Cognito-issued JWT tokens (ID token, access token, refresh token) +4. THE App_API SHALL validate all incoming JWT tokens against the Cognito_User_Pool's JWKS endpoint +5. WHEN a user authenticates via a Federated_Identity_Provider, THE Cognito_User_Pool SHALL issue its own JWT tokens containing the federated user's mapped attributes +6. THE App_API SHALL extract user identity (user ID, email, name, roles) from Cognito JWT token claims using configurable claim mappings +7. THE Frontend SHALL store Cognito tokens and include the access token in all authenticated API requests +8. WHEN a Cognito access token expires, THE Frontend SHALL use the refresh token to obtain new tokens from the Cognito token endpoint + +### Requirement 4: Federated Identity Provider Management + +**User Story:** As a system admin, I want to add, update, and remove external identity providers (Entra ID, Okta, Google) through the admin UI, so that users from different organizations can authenticate without infrastructure redeployment. + +#### Acceptance Criteria + +1. WHEN an admin creates a new auth provider via the Admin_UI, THE App_API SHALL register the provider as a Federated_Identity_Provider in the Cognito_User_Pool using the Cognito `CreateIdentityProvider` API +2. WHEN an admin creates a new auth provider, THE App_API SHALL store the provider configuration in the Auth_Providers_Table and store the client secret in Secrets Manager +3. WHEN an admin creates a new OIDC-type Federated_Identity_Provider, THE App_API SHALL configure the Cognito identity provider with the issuer URL, client ID, client secret, and attribute mappings +4. WHEN a Federated_Identity_Provider is created, THE App_API SHALL update the Cognito_App_Client to include the new provider in its list of supported identity providers +5. WHEN an admin updates a Federated_Identity_Provider's configuration, THE App_API SHALL update the corresponding Cognito identity provider using the `UpdateIdentityProvider` API +6. WHEN an admin deletes a Federated_Identity_Provider, THE App_API SHALL remove the provider from the Cognito_User_Pool using the `DeleteIdentityProvider` API and remove it from the Cognito_App_Client's supported providers list +7. IF the Cognito API call to create, update, or delete a Federated_Identity_Provider fails, THEN THE App_API SHALL return the error details to the Admin_UI and log the failure +8. THE App_API SHALL support OIDC-type federated providers with configurable attribute mappings for email, name, and sub claims +9. WHEN the `--discover` flag is enabled during provider creation, THE App_API SHALL fetch OIDC endpoints from the issuer URL's `.well-known/openid-configuration` endpoint to auto-populate the Cognito identity provider configuration + +### Requirement 5: Single AgentCore Runtime with Cognito JWT Authorizer + +**User Story:** As a platform operator, I want a single AgentCore Runtime that authenticates all users via Cognito JWTs, so that I do not need per-provider runtimes and the associated operational complexity. + +#### Acceptance Criteria + +1. THE Inference_API_Stack SHALL create exactly one AgentCore Runtime configured with a JWT authorizer pointing to the Cognito_User_Pool's OIDC discovery URL +2. THE Inference_Runtime JWT authorizer SHALL accept tokens issued by the Cognito_User_Pool regardless of which upstream identity provider the user authenticated with +3. THE Inference_Runtime JWT authorizer SHALL validate the `client_id` claim against the Cognito_App_Client ID (using `allowedClients`, not `allowedAudience`, because Cognito access tokens place the App Client ID in the `client_id` claim rather than the `aud` claim) +4. THE Frontend SHALL send the Cognito-issued access token when invoking the Inference_Runtime, using the single runtime endpoint for all users +5. THE Inference_API_Stack SHALL read the Cognito_User_Pool ID and Cognito_App_Client ID from SSM Parameter Store (exported by the Infrastructure_Stack) +6. THE Inference_API_Stack SHALL construct the Cognito OIDC discovery URL as `https://cognito-idp.{region}.amazonaws.com/{userPoolId}/.well-known/openid-configuration` + +### Requirement 6: Remove Multi-Runtime Architecture + +**User Story:** As a platform operator, I want the per-provider runtime provisioning system removed, so that the infrastructure is simpler and cheaper to operate. + +#### Acceptance Criteria + +1. THE App_API_Stack SHALL remove the Runtime_Provisioner_Lambda and its DynamoDB Stream trigger from the Auth_Providers_Table +2. THE App_API_Stack SHALL remove the Runtime_Updater_Lambda and its EventBridge trigger +3. THE App_API_Stack SHALL remove the SNS topic and CloudWatch alarms associated with runtime provisioning +4. THE Auth_Providers_Table schema SHALL retain the `agentcore_runtime_*` fields as deprecated but THE App_API SHALL stop writing to those fields for new providers +5. THE Frontend SHALL stop fetching per-provider runtime endpoint URLs and instead use the single Cognito-authorized runtime endpoint +6. THE App_API SHALL remove the `GET /auth/runtime-endpoint` endpoint that resolved per-provider runtime URLs + +### Requirement 7: Remove Hardcoded Entra ID Configuration + +**User Story:** As a platform operator, I want all hardcoded Entra ID configuration removed from the codebase, so that authentication is fully dynamic and provider-agnostic. + +#### Acceptance Criteria + +1. THE CDK configuration (`config.ts`) SHALL remove the `entraClientId`, `entraTenantId`, and `entraRedirectUri` properties from all interfaces and the `loadConfig` function +2. THE App_API_Stack SHALL remove Entra ID environment variables (`ENTRA_CLIENT_ID`, `ENTRA_TENANT_ID`, `ENTRA_REDIRECT_URI`) and secrets (`ENTRA_CLIENT_SECRET`) from the ECS task definition +3. THE GitHub Actions workflow files SHALL remove all Entra ID-specific variables (`CDK_ENTRA_CLIENT_ID`, `CDK_ENTRA_TENANT_ID`, `CDK_APP_API_ENTRA_REDIRECT_URI`) and secrets (`CDK_ENTRA_CLIENT_SECRET`) +4. THE `scripts/common/load-env.sh` SHALL remove Entra ID environment variable exports and context parameter generation +5. THE stack deployment scripts (`synth.sh`, `deploy.sh`) SHALL remove Entra ID context parameters +6. THE Backend test files SHALL replace Entra ID-specific test fixtures with generic OIDC provider fixtures + +### Requirement 8: Remove Auth Bootstrap Seed Workflow for Auth Providers + +**User Story:** As a platform operator, I want the GitHub Actions auth provider seeding workflow eliminated for authentication, so that I do not need to configure GitHub secrets for auth providers before deployment. + +#### Acceptance Criteria + +1. THE Bootstrap_Seed_Workflow SHALL remove the auth provider seeding job and all associated GitHub variables (`SEED_AUTH_PROVIDER_ID`, `SEED_AUTH_DISPLAY_NAME`, `SEED_AUTH_ISSUER_URL`, `SEED_AUTH_CLIENT_ID`, `SEED_AUTH_BUTTON_COLOR`) and secrets (`SEED_AUTH_CLIENT_SECRET`) +2. THE Bootstrap_Seed_Workflow SHALL retain seeding for non-auth data (quota tiers, quota assignments, Bedrock models) as those remain valid +3. THE `scripts/stack-bootstrap/seed.sh` and the Python seed script SHALL remove the auth provider seeding logic +4. THE deployment documentation SHALL be updated to describe the first-boot flow instead of GitHub variable configuration for authentication + +### Requirement 9: Cognito Attribute Mapping for Federated Users + +**User Story:** As a system admin, I want federated user attributes (email, name, groups) mapped correctly into Cognito, so that the application can identify and authorize federated users consistently. + +#### Acceptance Criteria + +1. WHEN configuring a Federated_Identity_Provider, THE App_API SHALL set up Cognito attribute mappings from the provider's claims to Cognito standard attributes (email, name, given_name, family_name, picture) +2. THE App_API SHALL map the federated provider's `sub` claim to a Cognito custom attribute to preserve the original provider user ID +3. WHEN a federated user signs in for the first time, THE Cognito_User_Pool SHALL create a linked user profile with the mapped attributes +4. THE App_API SHALL support configurable claim mappings per provider, allowing admins to specify which provider claims map to which Cognito attributes +5. IF a federated provider does not supply a required attribute (email), THEN THE Cognito_User_Pool SHALL reject the sign-in and THE App_API SHALL return a descriptive error to the user + +### Requirement 10: Backend JWT Validation Migration + +**User Story:** As a developer, I want the backend JWT validation simplified to validate only Cognito-issued tokens, so that the authentication code is easier to maintain and reason about. + +#### Acceptance Criteria + +1. THE shared auth module (`apis/shared/auth`) SHALL validate JWT tokens exclusively against the Cognito_User_Pool's JWKS endpoint +2. THE JWT validator SHALL verify the token issuer matches the Cognito_User_Pool issuer URL (`https://cognito-idp.{region}.amazonaws.com/{userPoolId}`) +3. THE JWT validator SHALL verify the token's `client_id` claim (for access tokens) or `aud` claim (for ID tokens) matches the Cognito_App_Client ID +4. THE JWT validator SHALL extract user identity from Cognito token claims: `sub` for user ID, `email` for email, `cognito:username` for username, and `custom:roles` or Cognito groups for roles +5. THE App_API SHALL remove the `GenericOIDCJWTValidator` class and its multi-provider issuer resolution logic, replacing it with a single-issuer Cognito validator +6. THE App_API SHALL remove the dependency on the Auth_Providers_Table for JWT validation (provider config is no longer needed at token validation time since Cognito is the sole issuer) + +### Requirement 11: Frontend Authentication Flow Migration + +**User Story:** As a developer, I want the frontend authentication flow updated to use Cognito, so that login works with both local username/password and federated providers through a single flow. + +#### Acceptance Criteria + +1. THE Frontend auth service SHALL use the Cognito OAuth 2.0 endpoints (authorize, token, logout) for all authentication flows +2. THE Frontend login page SHALL display a username/password form for Cognito native login alongside buttons for each configured Federated_Identity_Provider +3. WHEN a user clicks a federated provider button, THE Frontend SHALL redirect to the Cognito authorize endpoint with the `identity_provider` parameter set to the selected provider's Cognito name +4. THE Frontend SHALL fetch the list of available federated providers from the App_API's existing `GET /auth/providers` endpoint +5. THE Frontend SHALL use a single runtime endpoint URL (from environment configuration or SSM) for all Inference_Runtime invocations, removing the per-provider endpoint resolution +6. THE Frontend callback handler SHALL exchange the Cognito authorization code for tokens using the Cognito token endpoint + +### Requirement 12: System Settings and First-Boot State + +**User Story:** As a platform operator, I want the system to reliably track whether first-boot has been completed, so that the first-boot flow is only available once and subsequent deployments skip it. + +#### Acceptance Criteria + +1. THE App_API SHALL store a `SYSTEM_SETTINGS#first-boot` item in DynamoDB to track first-boot completion status +2. THE App_API SHALL expose a `GET /system/status` public endpoint that returns whether first-boot has been completed (without requiring authentication) +3. WHEN the Frontend loads, THE Frontend SHALL call the `GET /system/status` endpoint to determine whether to show the first-boot page or the login page +4. THE first-boot status check SHALL be idempotent and safe to call from multiple concurrent requests +5. IF the DynamoDB table does not contain the first-boot settings item, THEN THE App_API SHALL treat the system as not yet bootstrapped + +### Requirement 13: Cognito User Pool Configuration for CDK + +**User Story:** As a platform operator, I want Cognito configuration to follow the existing CDK context and SSM patterns, so that it integrates cleanly with the deployment pipeline. + +#### Acceptance Criteria + +1. THE CDK configuration (`config.ts`) SHALL add a `cognito` section to the `AppConfig` interface with properties for custom domain, callback URLs, and password policy overrides +2. THE Cognito_User_Pool configuration SHALL use CDK context values with environment variable overrides following the existing `CDK_` prefix convention +3. THE Infrastructure_Stack SHALL export Cognito resource identifiers to SSM using the `/${projectPrefix}/auth/cognito/` parameter path prefix +4. THE App_API_Stack SHALL import Cognito configuration from SSM parameters (not cross-stack references) following the existing SSM-based integration pattern +5. THE Inference_API_Stack SHALL import the Cognito User Pool ID and App Client ID from SSM to configure the runtime JWT authorizer +6. THE GitHub Actions workflows SHALL pass Cognito-related CDK context values following the existing variable/secret pattern (no Cognito secrets required since the User Pool is CDK-managed) diff --git a/.kiro/specs/cognito-first-boot-auth/tasks.md b/.kiro/specs/cognito-first-boot-auth/tasks.md new file mode 100644 index 00000000..481418ce --- /dev/null +++ b/.kiro/specs/cognito-first-boot-auth/tasks.md @@ -0,0 +1,297 @@ +# Implementation Plan: Cognito First-Boot Authentication + +## Overview + +Replace the multi-step auth bootstrap (GitHub secrets → seed workflow → multi-runtime provisioning) with a WordPress-style first-boot experience powered by Amazon Cognito. Implementation proceeds bottom-up: CDK infrastructure first, then backend APIs, then frontend migration, then removal of legacy components. Each task builds on the previous, with property-based tests validating correctness properties from the design. + +## Tasks + +- [x] 1. CDK Configuration and Cognito User Pool Infrastructure + - [x] 1.1 Add CognitoConfig to CDK configuration + - Add `CognitoConfig` interface to `infrastructure/lib/config.ts` with `domainPrefix`, `callbackUrls`, `logoutUrls`, `passwordMinLength` properties + - Add `cognito: CognitoConfig` to `AppConfig` interface + - Implement `loadConfig()` loading with `CDK_COGNITO_*` environment variable overrides and CDK context fallbacks + - _Requirements: 13.1, 13.2_ + + - [ ]* 1.2 Write property test for CDK config loading with env var overrides + - **Property 17: CDK config loading with environment variable overrides** + - Generate random env var and context values with Hypothesis, verify env var takes precedence over context value + - **Validates: Requirements 13.2** + + - [x] 1.3 Create Cognito User Pool, App Client, and Domain in Infrastructure Stack + - Add Cognito User Pool with `cognito.UserPool` L2 construct in `infrastructure/lib/infrastructure-stack.ts` + - Configure password policy (min 8 chars, uppercase, lowercase, digit, symbol), self-signup enabled, email required + - Create App Client with authorization code grant, PKCE, scopes `openid profile email`, no client secret (SPA) + - Derive callback/logout URLs from `domainName` config (HTTPS) or fallback to `localhost:4200` + - Create Cognito Domain with prefix-based domain using `projectPrefix` + - Export User Pool ID, ARN, App Client ID, Domain URL, and Issuer URL to SSM under `/${projectPrefix}/auth/cognito/` paths + - _Requirements: 1.1, 1.2, 1.3, 1.4, 1.5, 1.6, 1.7, 1.8, 13.3_ + + - [ ]* 1.4 Write property test for SSM export path correctness + - **Property 1: Cognito SSM export path correctness** + - Generate random valid project prefixes, verify SSM parameter paths begin with `/${projectPrefix}/auth/cognito/` and include all 5 required keys + - **Validates: Requirements 1.4, 13.3** + + - [ ]* 1.5 Write property test for callback URL derivation + - **Property 2: Callback URL derivation from domain configuration** + - Generate random domain names (or None), verify callback URLs use `https://{domainName}/auth/callback` when domain provided, `http://localhost:4200/auth/callback` otherwise + - **Validates: Requirements 1.7, 1.8** + +- [x] 2. Checkpoint - Verify CDK infrastructure compiles and synthesizes + - Ensure `npm run build` and `npx cdk synth` succeed in `infrastructure/` + - Ensure all property tests pass, ask the user if questions arise. + +- [x] 3. System Settings and First-Boot Backend + - [x] 3.1 Create system settings repository and models + - Create `backend/src/apis/app_api/system/` module with `models.py` defining `FirstBootRequest`, `FirstBootResponse`, `SystemStatusResponse` Pydantic models + - Create `repository.py` with DynamoDB operations for `SYSTEM_SETTINGS#first-boot` item using `attribute_not_exists(PK)` conditional writes for race condition protection + - _Requirements: 12.1, 12.4, 12.5_ + + - [x] 3.2 Implement system status endpoint + - Add `GET /system/status` public endpoint (no auth required) in `backend/src/apis/app_api/system/routes.py` + - Return `first_boot_completed: true` if `SYSTEM_SETTINGS#first-boot` item exists with `completed=true`, else `false` + - Return `first_boot_completed: false` as safe default on DynamoDB read failure + - Register router in App API main.py + - _Requirements: 12.2, 12.3, 12.5_ + + - [ ]* 3.3 Write property test for system status round-trip + - **Property 15: System status round-trip** + - Generate random DynamoDB states (with/without first-boot item), verify endpoint response matches expected boolean + - **Validates: Requirements 12.1, 12.2** + + - [x] 3.4 Implement first-boot endpoint + - Add `POST /system/first-boot` public endpoint (no auth required) in `routes.py` + - Atomic check: if first-boot already completed, return 409 Conflict + - Create user in Cognito via `AdminCreateUser` + `AdminSetUserPassword` (permanent) + - Create user record in Users DynamoDB table with `system_admin` role + - Mark first-boot completed in DynamoDB with conditional write + - Disable self-signup via `UpdateUserPool` setting `AllowAdminCreateUserOnly=true` + - Return 400 for invalid password (Cognito policy violation), 409 for race conditions + - _Requirements: 2.3, 2.4, 2.5, 2.6, 2.7, 2.8_ + + - [ ]* 3.5 Write property test for first-boot creates admin + - **Property 3: First-boot creates admin with correct role** + - Generate random valid usernames/emails/passwords, run first-boot against mocked Cognito+DynamoDB, verify admin user exists with `system_admin` role and first-boot item is `completed=true` + - **Validates: Requirements 2.3, 2.4, 2.5** + + - [ ]* 3.6 Write property test for first-boot rejection after completion + - **Property 4: First-boot rejection after completion** + - Generate random valid first-boot requests, run first-boot twice, verify second returns 409 and system state unchanged + - **Validates: Requirements 2.7** + + - [ ]* 3.7 Write property test for first-boot disables self-signup + - **Property 5: First-boot disables self-signup** + - Generate random first-boot requests, verify `UpdateUserPool` is called with `AllowAdminCreateUserOnly=true` after success + - **Validates: Requirements 2.6** + + - [ ]* 3.8 Write property test for concurrent first-boot safety + - **Property 16: Concurrent first-boot safety** + - Generate random concurrent first-boot requests, verify exactly one succeeds (200) and all others fail (409), and exactly one admin user and one first-boot item exist + - **Validates: Requirements 12.4** + +- [x] 4. Checkpoint - Verify first-boot backend works + - Ensure all tests pass, ask the user if questions arise. + +- [x] 5. Backend JWT Validation Migration + - [x] 5.1 Implement CognitoJWTValidator + - Create `backend/src/apis/shared/auth/cognito_jwt_validator.py` with `CognitoJWTValidator` class + - Validate JWT signature against Cognito JWKS endpoint, verify issuer matches `https://cognito-idp.{region}.amazonaws.com/{userPoolId}`, verify `client_id` claim (access tokens) or `aud` claim (ID tokens) matches App Client ID, verify expiration + - Extract user identity: `sub` → `user_id`, `email` → `email`, `name` (fallback `cognito:username`) → `name`, `cognito:groups` → `roles`, `picture` → `picture` + - _Requirements: 10.1, 10.2, 10.3, 10.4_ + + - [x] 5.2 Update get_current_user dependency to use CognitoJWTValidator + - Update `backend/src/apis/shared/auth/dependencies.py` to instantiate `CognitoJWTValidator` using Cognito User Pool ID, App Client ID, and region from environment variables + - Remove `GenericOIDCJWTValidator` instantiation and multi-provider issuer resolution logic + - Remove dependency on Auth_Providers_Table for JWT validation + - _Requirements: 10.5, 10.6_ + + - [ ]* 5.3 Write property test for JWT validation + - **Property 6: Cognito JWT validation rejects invalid tokens** + - Generate random JWT payloads with valid/invalid issuers, audiences, and expiration, verify accept/reject behavior + - **Validates: Requirements 3.4, 10.1, 10.2, 10.3** + + - [ ]* 5.4 Write property test for claim extraction + - **Property 7: Cognito claim extraction correctness** + - Generate random Cognito-style JWT payloads with `sub`, `email`, `name`, `cognito:groups`, verify User object fields match claims correctly + - **Validates: Requirements 3.6, 10.4** + +- [x] 6. Federated Identity Provider Management + - [x] 6.1 Extend auth provider create to register in Cognito + - Update the existing auth provider creation logic in `backend/src/apis/app_api/admin/` to call Cognito `CreateIdentityProvider` with OIDC provider details (issuer URL, client ID, client secret, attribute mappings) + - Call `UpdateUserPoolClient` to add new provider to `SupportedIdentityProviders` + - Implement rollback: if `UpdateUserPoolClient` fails, delete the identity provider from Cognito; if DynamoDB write fails, delete from Cognito + - Store `cognitoProviderName` field in Auth_Providers_Table DynamoDB item + - _Requirements: 4.1, 4.2, 4.3, 4.4, 4.7, 9.1, 9.2_ + + - [x] 6.2 Extend auth provider update to sync to Cognito + - Update existing auth provider update logic to call Cognito `UpdateIdentityProvider` with changed OIDC configuration and attribute mappings + - _Requirements: 4.5_ + + - [x] 6.3 Extend auth provider delete to remove from Cognito + - Update existing auth provider deletion logic to call `DeleteIdentityProvider` and remove provider from App Client's `SupportedIdentityProviders` via `UpdateUserPoolClient` + - Delete from DynamoDB and Secrets Manager (existing logic) + - Handle "not found" from Cognito gracefully (idempotent delete) + - _Requirements: 4.6_ + + - [x] 6.4 Add configurable attribute mappings and OIDC discovery + - Support admin-specified custom attribute mappings per provider (email, name, given_name, family_name, picture, custom:provider_sub) + - When `--discover` flag is enabled, fetch `.well-known/openid-configuration` from issuer URL to auto-populate Cognito identity provider configuration + - _Requirements: 4.8, 4.9, 9.4_ + + - [x] 6.5 Add Cognito IAM permissions to App API task role + - Add IAM policy statement to App API ECS task role in `infrastructure/lib/app-api-stack.ts` granting `cognito-idp:CreateIdentityProvider`, `UpdateIdentityProvider`, `DeleteIdentityProvider`, `DescribeIdentityProvider`, `ListIdentityProviders`, `UpdateUserPoolClient`, `DescribeUserPoolClient`, `AdminCreateUser`, `AdminSetUserPassword`, `AdminGetUser`, `UpdateUserPool` on the Cognito User Pool ARN + - Import Cognito User Pool ARN from SSM parameter + - _Requirements: 4.1, 13.4_ + + - [ ]* 6.6 Write property test for provider creation Cognito registration + - **Property 8: Provider creation registers in Cognito with correct attribute mappings** + - Generate random provider configs with custom attribute mappings, verify `CreateIdentityProvider` call includes correct `ProviderDetails` and `AttributeMapping` + - **Validates: Requirements 4.1, 4.3, 9.1, 9.2, 9.4** + + - [ ]* 6.7 Write property test for provider creation DynamoDB + Secrets Manager + - **Property 9: Provider creation stores configuration in DynamoDB and Secrets Manager** + - Generate random provider configs, verify DynamoDB item with PK `AUTH_PROVIDER#{providerId}` and Secrets Manager write + - **Validates: Requirements 4.2** + + - [ ]* 6.8 Write property test for provider creation App Client update + - **Property 10: Provider creation updates App Client supported providers** + - Generate random sequences of provider creations, verify `SupportedIdentityProviders` grows correctly and always includes `COGNITO` + - **Validates: Requirements 4.4** + + - [ ]* 6.9 Write property test for provider update Cognito sync + - **Property 11: Provider update syncs to Cognito** + - Generate random provider updates, verify `UpdateIdentityProvider` is called with correct params + - **Validates: Requirements 4.5** + + - [ ]* 6.10 Write property test for provider deletion cleanup + - **Property 12: Provider deletion removes from Cognito and App Client** + - Generate random provider creation+deletion sequences, verify all resources cleaned up from Cognito, DynamoDB, and Secrets Manager + - **Validates: Requirements 4.6** + +- [x] 7. Checkpoint - Verify federated provider management works + - Ensure all tests pass, ask the user if questions arise. + +- [x] 8. Single AgentCore Runtime with Cognito JWT Authorizer + - [x] 8.1 Update Inference API Stack for single Cognito-authorized runtime + - Modify `infrastructure/lib/inference-api-stack.ts` to create a single CDK-managed `bedrock.CfnRuntime` with `customJwtAuthorizer` pointing to Cognito OIDC discovery URL + - Import Cognito User Pool ID and App Client ID from SSM parameters + - Construct discovery URL as `https://cognito-idp.{region}.amazonaws.com/{userPoolId}/.well-known/openid-configuration` + - Set `allowedClients` to the Cognito App Client ID (not `allowedAudience`, because Cognito access tokens use the `client_id` claim for the App Client ID) + - _Requirements: 5.1, 5.2, 5.3, 5.5, 5.6, 13.5_ + + - [ ]* 8.2 Write property test for Cognito discovery URL construction + - **Property 13: Cognito discovery URL construction** + - Generate random valid AWS region strings and User Pool IDs, verify URL format matches `https://cognito-idp.{region}.amazonaws.com/{userPoolId}/.well-known/openid-configuration` + - **Validates: Requirements 5.6** + +- [x] 9. Remove Multi-Runtime Architecture + - [x] 9.1 Remove Runtime Provisioner Lambda and Runtime Updater Lambda + - Delete `backend/lambda-functions/runtime-provisioner/` directory + - Delete `backend/lambda-functions/runtime-updater/` directory + - Remove Runtime Provisioner Lambda, DynamoDB Stream trigger, SNS topic, and CloudWatch alarms from `infrastructure/lib/app-api-stack.ts` + - Remove Runtime Updater Lambda and EventBridge trigger from `infrastructure/lib/app-api-stack.ts` + - _Requirements: 6.1, 6.2, 6.3_ + + - [x] 9.2 Remove per-provider runtime endpoint resolution + - Remove `GET /auth/runtime-endpoint` endpoint from App API backend + - Stop writing `agentcore_runtime_*` fields for new providers in Auth_Providers_Table + - _Requirements: 6.4, 6.6_ + + - [ ]* 9.3 Write property test for no deprecated runtime fields on new providers + - **Property 14: New providers do not write deprecated runtime fields** + - Generate random new provider configs, verify DynamoDB items do not contain non-null `agentcoreRuntimeArn`, `agentcoreRuntimeId`, or `agentcoreRuntimeEndpointUrl` + - **Validates: Requirements 6.4** + +- [x] 10. Remove Hardcoded Entra ID Configuration + - [x] 10.1 Remove Entra ID from CDK config and stacks + - Remove `entraClientId`, `entraTenantId` from `AppConfig` interface and `entraRedirectUri` from `AppApiConfig` in `infrastructure/lib/config.ts` + - Remove all Entra ID loading logic from `loadConfig()` + - Remove `ENTRA_CLIENT_ID`, `ENTRA_TENANT_ID`, `ENTRA_REDIRECT_URI` env vars and `ENTRA_CLIENT_SECRET` secret from App API ECS task definition in `app-api-stack.ts` + - _Requirements: 7.1, 7.2_ + + - [x] 10.2 Remove Entra ID from scripts and GitHub workflows + - Remove `CDK_ENTRA_CLIENT_ID`, `CDK_ENTRA_TENANT_ID`, `CDK_APP_API_ENTRA_REDIRECT_URI` variables and `CDK_ENTRA_CLIENT_SECRET` secret references from GitHub Actions workflow files + - Remove Entra ID environment variable exports and context parameter generation from `scripts/common/load-env.sh` + - Remove Entra ID context parameters from `scripts/stack-infrastructure/synth.sh`, `scripts/stack-infrastructure/deploy.sh`, and other stack deployment scripts + - _Requirements: 7.3, 7.4, 7.5_ + + - [x] 10.3 Remove GenericOIDCJWTValidator and multi-provider auth logic + - Delete `GenericOIDCJWTValidator` class and its multi-provider issuer resolution logic from `backend/src/apis/shared/auth/` + - Update any backend test files that use Entra ID-specific fixtures to use generic OIDC provider fixtures + - _Requirements: 7.6, 10.5_ + +- [x] 11. Remove Auth Bootstrap Seed Workflow + - [x] 11.1 Remove auth provider seeding from bootstrap workflow + - Remove auth provider seeding job and all `SEED_AUTH_*` variables/secrets from `bootstrap-data-seeding.yml` GitHub Actions workflow + - Remove auth provider seeding logic from `scripts/stack-bootstrap/seed.sh` and the Python seed script (`seed_bootstrap_data.py`) + - Retain quota tier, quota assignment, and Bedrock model seeding + - _Requirements: 8.1, 8.2, 8.3_ + +- [x] 12. Checkpoint - Verify all removals compile cleanly + - Ensure CDK `npm run build` succeeds after all removals + - Ensure backend tests pass after removing GenericOIDCJWTValidator and lambda functions + - Ensure all property tests pass, ask the user if questions arise. + +- [x] 13. Frontend Authentication Flow Migration + - [x] 13.1 Update Angular AuthService for Cognito OAuth 2.0 + - Update `frontend/ai.client/src/app/auth/auth.service.ts` to use Cognito OAuth 2.0 endpoints (authorize, token, logout) + - Implement PKCE flow: generate code verifier, code challenge, state parameter + - Add `login(providerId?: string)` method that redirects to Cognito authorize endpoint, with optional `identity_provider` parameter for federated providers + - Add `handleCallback(code, state)` method that exchanges authorization code for Cognito tokens via the Cognito token endpoint + - Implement token storage and refresh token flow + - _Requirements: 3.1, 3.2, 3.3, 3.7, 3.8, 11.1, 11.6_ + + - [x] 13.2 Update login page for Cognito native + federated login + - Update login component to display username/password form for Cognito native login + - Add federated provider buttons fetched from `GET /auth/providers` endpoint + - Clicking a federated provider button calls `login(providerId)` to redirect to Cognito with `identity_provider` parameter + - _Requirements: 11.2, 11.3, 11.4_ + + - [x] 13.3 Update frontend to use single runtime endpoint + - Remove per-provider runtime endpoint resolution and `getRuntimeEndpoint()` API call + - Update all Inference Runtime invocations to use a single endpoint URL from environment configuration + - Send Cognito-issued access token for all runtime invocations + - _Requirements: 5.4, 6.5, 11.5_ + + - [x] 13.4 Add first-boot page to frontend + - Create first-boot setup component that collects username, email, and password + - On app load, call `GET /system/status` to determine whether to show first-boot page or login page + - On form submit, call `POST /system/first-boot`, then authenticate the admin user and redirect to admin dashboard + - _Requirements: 2.1, 2.2, 2.8, 12.3_ + + - [x] 13.5 Update frontend environment configuration + - Add `cognitoDomainUrl`, `cognitoAppClientId`, `cognitoRegion` to environment files (`environment.ts`, `environment.development.ts`, `environment.production.ts`) + - Update frontend build/deploy scripts to inject Cognito values from SSM parameters + - _Requirements: 11.1, 13.6_ + +- [x] 14. Checkpoint - Verify frontend builds and all tests pass + - Ensure `npm run build` succeeds in `frontend/ai.client/` + - Ensure all backend and property tests pass + - Ask the user if questions arise. + +- [x] 15. Integration Wiring and SSM Parameter Consumption + - [x] 15.1 Wire App API Stack to consume Cognito SSM parameters + - Update `infrastructure/lib/app-api-stack.ts` to import Cognito User Pool ID, App Client ID, Issuer URL, and Domain URL from SSM parameters + - Pass Cognito configuration as environment variables to the App API ECS task definition (`COGNITO_USER_POOL_ID`, `COGNITO_APP_CLIENT_ID`, `COGNITO_ISSUER_URL`, `COGNITO_DOMAIN_URL`, `COGNITO_REGION`) + - _Requirements: 13.4_ + + - [x] 15.2 Update GitHub Actions workflows for Cognito context values + - Add `CDK_COGNITO_DOMAIN_PREFIX` and any other Cognito-related CDK context variables to GitHub Actions workflow files following the existing `CDK_` prefix convention + - No Cognito secrets required since the User Pool is CDK-managed + - _Requirements: 13.6_ + +- [x] 16. Final Checkpoint - Ensure all tests pass + - Ensure all property-based tests pass (17 properties) + - Ensure all unit tests pass + - Ensure CDK synthesizes cleanly + - Ensure frontend builds successfully + - Ask the user if questions arise. + +## Notes + +- Tasks marked with `*` are optional and can be skipped for faster MVP +- Each task references specific requirements for traceability +- Checkpoints ensure incremental validation after each major phase +- Property tests validate universal correctness properties from the design document using Hypothesis +- Unit tests validate specific examples and edge cases using pytest +- The implementation order ensures no orphaned code: infrastructure → backend APIs → frontend → removals → wiring diff --git a/.kiro/specs/config-cleanup-audit/.config.kiro b/.kiro/specs/config-cleanup-audit/.config.kiro deleted file mode 100644 index 68e612e3..00000000 --- a/.kiro/specs/config-cleanup-audit/.config.kiro +++ /dev/null @@ -1 +0,0 @@ -{"specId": "c35590f8-b01e-4ac4-b7b6-83a038b22707", "workflowType": "requirements-first", "specType": "feature"} \ No newline at end of file diff --git a/.kiro/specs/config-cleanup-audit/design.md b/.kiro/specs/config-cleanup-audit/design.md deleted file mode 100644 index 64dc3380..00000000 --- a/.kiro/specs/config-cleanup-audit/design.md +++ /dev/null @@ -1,333 +0,0 @@ -# Design Document: Config Cleanup Audit - -## Overview - -This feature performs a comprehensive audit and cleanup of configuration across the AgentCore Public Stack. Configuration is spread across five layers: CDK TypeScript interfaces (`config.ts`), CDK context defaults (`cdk.context.json`), shell environment loader (`load-env.sh`), backend environment templates (`.env.example`), frontend environment files, and GitHub Actions workflows. Over time, dead config has accumulated — RDS fields hardcoded to disabled, CORS origins duplicated four times, GPU flags no stack consumes, and auth toggles for an app that cannot function without auth. - -The cleanup is organized into three categories: - -1. **Dead code removal** (Reqs 1, 2, 4, 5, 10, 11, 14, 15, 18): Remove fields, interfaces, functions, and plumbing that nothing consumes. -2. **Consolidation and normalization** (Reqs 3, 6, 7, 8, 13, 16, 17): Deduplicate CORS, enforce the config default hierarchy, synchronize files, migrate GitHub Secrets to Variables. -3. **Validation and documentation** (Reqs 9, 12): Add startup validation rules and produce a CONFIG_INVENTORY.md. - -All changes are purely configuration-level — no new features, no new runtime behavior, no new AWS resources. The application's functional behavior is unchanged; the configuration surface shrinks. - -## Architecture - -The configuration system follows a layered architecture with a strict precedence hierarchy: - -``` -Environment Variables > CDK Context (cdk.context.json) > (no hardcoded defaults) -``` - -```mermaid -graph TD - subgraph "GitHub Actions" - GH_SECRETS["GitHub Secrets
(sensitive: AWS keys, API keys)"] - GH_VARS["GitHub Variables
(non-sensitive: account ID, ARNs, bucket names)"] - end - - subgraph "Shell Layer" - LOAD_ENV["load-env.sh
Exports env vars with context fallback"] - end - - subgraph "CDK Layer" - CONTEXT["cdk.context.json
Single source of truth for defaults"] - CONFIG_TS["config.ts
loadConfig() — reads env then context
validateConfig() — catches missing fields"] - end - - subgraph "CDK Stacks" - INFRA["InfrastructureStack"] - APP_API["AppApiStack"] - INF_API["InferenceApiStack"] - FRONTEND["FrontendStack"] - GATEWAY["GatewayStack"] - RAG["RagIngestionStack"] - end - - subgraph "Frontend Runtime" - CONFIG_JSON["config.json
(generated by FrontendStack)"] - CONFIG_SVC["ConfigService
Loads config.json at startup"] - ENV_TS["environment.ts
Fallback only"] - end - - subgraph "Backend Runtime" - ENV_FILE[".env / os.getenv()
Runtime env vars"] - end - - GH_SECRETS --> LOAD_ENV - GH_VARS --> LOAD_ENV - LOAD_ENV --> CONFIG_TS - CONTEXT --> CONFIG_TS - CONFIG_TS --> INFRA - CONFIG_TS --> APP_API - CONFIG_TS --> INF_API - CONFIG_TS --> FRONTEND - CONFIG_TS --> GATEWAY - CONFIG_TS --> RAG - FRONTEND --> CONFIG_JSON - CONFIG_JSON --> CONFIG_SVC - ENV_TS -.->|fallback| CONFIG_SVC - ENV_FILE --> APP_API -``` - -After cleanup, the architecture remains identical — only the set of fields flowing through each layer shrinks. - -## Components and Interfaces - -### CDK Config Layer (`infrastructure/lib/config.ts`) - -#### Removed Interfaces/Fields - -| Interface | Removed Fields | Reason | -|-----------|---------------|--------| -| `AppApiConfig` | `enableRds`, `rdsInstanceClass`, `rdsEngine`, `rdsDatabaseName`, `databaseType` | Hardcoded to disabled/none, never consumed by any stack (Reqs 1, 5) | -| `InferenceApiConfig` | `enableGpu`, `uploadDir`, `outputDir`, `generatedImagesDir`, `apiUrl`, `frontendUrl`, `enableAuthentication`, `oauthCallbackUrl` | GPU never provisioned; dirs are container-internal; apiUrl/frontendUrl are dead; auth always on; OAuth URL derived at runtime (Reqs 2, 4, 14, 15, 18) | -| `FrontendConfig` | `enableRoute53` | Derived from `config.domainName` being set (Req 10) | - -#### Added Fields - -| Interface | New Field | Reason | -|-----------|----------|--------| -| `AppConfig` | `corsOrigins: string` | Top-level shared CORS origins, replacing four duplicated per-section values (Req 3) | - -#### Modified `loadConfig()` - -- All hardcoded fallback defaults (e.g., `parseBooleanEnv(..., true)`, `|| 365`, `|| 10240`) are removed. Each field reads env var first, then `scope.node.tryGetContext()`. Defaults live exclusively in `cdk.context.json` (Req 17). -- Exception: Empty-string fallbacks (`|| ''`) for `imageTag` and `ragIngestion.corsOrigins` are retained as "not set" sentinels (Req 17.5). - -#### Modified `validateConfig()` - -New validation rules (Req 9): -- When `gateway.enabled` is true, verify `gateway.apiType` is `'REST'` or `'HTTP'`. -- When `fileUpload.enabled` is true, verify CORS origins are available (top-level or section-level). -- When any stack is enabled, verify its required fields are populated. Throw a descriptive error identifying the missing field and which stack requires it. - -### CDK Context (`cdk.context.json`) - -After cleanup, the context file becomes the single source of truth for all defaults. Key changes: - -- Remove: `enableRds`, `rdsInstanceClass`, `rdsEngine`, `rdsDatabaseName`, `databaseType`, `enableGpu`, `uploadDir`, `outputDir`, `generatedImagesDir`, `apiUrl`, `frontendUrl`, `enableAuthentication` (inferenceApi), `oauthCallbackUrl`, `enableRoute53`, `entraClientId`, `entraTenantId` -- Add top-level: `corsOrigins`, `production`, `retainDataOnDelete` (set to `false` per Req 16) -- Add to sections: all defaults previously hardcoded in `loadConfig()` (e.g., `fileUpload.maxFileSizeBytes: 4194304`, `ragIngestion.lambdaMemorySize: 10240`, etc.) -- Consolidate: single top-level `corsOrigins` replaces duplicated values in `fileUpload`, `assistants`, `ragIngestion` - -### Shell Layer (`scripts/common/load-env.sh`) - -- Remove exports and context params for all deleted fields (GPU, dirs, auth toggle, oauthCallbackUrl, enableRoute53, etc.) -- Remove hardcoded bash defaults (`:-true`, `:-http://localhost:4200`, `:-10`). Each variable falls back to `get_json_value` from the context file. -- Remove `CDK_ENABLE_AUTHENTICATION` export and validation. - -### Frontend Config (`ConfigService`, `environment.ts`) - -- Remove `inferenceApiUrl` from `RuntimeConfig` interface, computed signal, `encodeUrlPath` helper, and all fallback logic (Req 15). -- Remove `enableAuthentication` from `RuntimeConfig` interface, computed signal, and all conditional bypass paths in guards/interceptors/services (Req 14). -- Remove `inferenceApiUrl` and `enableAuthentication` from `environment.ts` and `environment.production.ts`. -- Remove dead `environment` import from `error.interceptor.ts` (Req 7). -- Update `preview-chat.service.ts` to resolve runtime endpoint dynamically via `authApiService.getRuntimeEndpoint()` instead of static `config.inferenceApiUrl()` (Req 15). - -### Frontend Stack (`infrastructure/lib/frontend-stack.ts`) - -- Remove `enableAuthentication` from generated `config.json` (always true, no longer configurable). -- Change Route53 condition from `config.frontend.enableRoute53 && config.domainName` to just `config.domainName` (Req 10). - -### Backend Auth (`backend/src/apis/shared/auth/dependencies.py`) - -- Remove `ENABLE_AUTHENTICATION` env var check, `_check_auth_bypass()`, `_create_anonymous_dev_user()`. -- Remove all `bypass_user = _check_auth_bypass()` calls from `get_current_user` and `get_current_user_trusted`. -- Authentication is always enforced. - -### GitHub Actions Workflows - -- Migrate `CDK_AWS_ACCOUNT`, `CDK_FRONTEND_CERTIFICATE_ARN`, `CDK_FRONTEND_BUCKET_NAME`, `SEED_AUTH_CLIENT_ID` from `secrets.*` to `vars.*` (Req 13). -- Remove env entries for all deleted config fields across all workflow files. -- Update `ACTIONS-REFERENCE.md` and `README-ACTIONS.md` accordingly. - -### Documentation - -- Create `docs/CONFIG_INVENTORY.md` listing every config variable, its source, and consuming module (Req 12). -- Update `backend/src/apis/shared/auth/README.md` to remove ENABLE_AUTHENTICATION docs (Req 14). - -### Resource Tagging (`config.ts`, `cdk.context.json`) - -Current state: `loadConfig()` hardcodes `Project: projectPrefix` and `ManagedBy: 'CDK'` in the `tags` object, then merges `...scope.node.tryGetContext('tags')` on top. The context file has `Environment: 'dev'`, `Project: 'AgentCore'`, `ManagedBy: 'CDK'`. This creates conflicts — `Project` is set twice with different values, and `Environment: 'dev'` is baked in regardless of actual deployment target. - -After cleanup: -- `loadConfig()` loads tags entirely from context: `tags: scope.node.tryGetContext('tags') || {}` -- No hardcoded tag literals in `config.ts` -- The context file `tags` section becomes the single source of truth for default tags -- `Project` tag uses the `projectPrefix` value — since CDK context can't interpolate, `applyStandardTags()` will inject `Project: config.projectPrefix` alongside the context tags, ensuring it always matches the actual prefix -- `Environment` tag is removed from context defaults (or set to a meaningful placeholder) since it doesn't reflect actual deployment environment -- Review `@aws-cdk/core:checksumAssetForResourceTags` flag for unexpected tag injection - -## Data Models - -No new data models are introduced. This feature only modifies configuration interfaces (TypeScript types) and removes fields. The key interface changes are: - -### Before → After: `AppConfig` - -```typescript -// ADDED -corsOrigins: string; // Top-level shared CORS origins - -// UNCHANGED (all other fields) -``` - -### Before → After: `AppApiConfig` - -```typescript -// REMOVED: enableRds, rdsInstanceClass, rdsEngine, rdsDatabaseName, databaseType -// REMAINING: -enabled: boolean; -cpu: number; -memory: number; -desiredCount: number; -maxCapacity: number; -imageTag: string; -``` - -### Before → After: `InferenceApiConfig` - -```typescript -// REMOVED: enableGpu, uploadDir, outputDir, generatedImagesDir, apiUrl, frontendUrl, -// enableAuthentication, oauthCallbackUrl -// REMAINING: -enabled: boolean; -cpu: number; -memory: number; -desiredCount: number; -maxCapacity: number; -imageTag: string; -logLevel: string; -corsOrigins: string; -tavilyApiKey: string; -novaActApiKey: string; -``` - -### Before → After: `FrontendConfig` - -```typescript -// REMOVED: enableRoute53 -// REMAINING: -certificateArn?: string; -enabled: boolean; -bucketName?: string; -cloudFrontPriceClass: string; -``` - -### Before → After: `RuntimeConfig` (Frontend) - -```typescript -// REMOVED: inferenceApiUrl, enableAuthentication -// REMAINING: -appApiUrl: string; -environment: string; -``` - - -## Correctness Properties - -*A property is a characteristic or behavior that should hold true across all valid executions of a system — essentially, a formal statement about what the system should do. Properties serve as the bridge between human-readable specifications and machine-verifiable correctness guarantees.* - -### Property 1: Removed config fields do not exist on loaded config - -*For any* field in the removed-fields set (`enableRds`, `rdsInstanceClass`, `rdsEngine`, `rdsDatabaseName`, `databaseType`, `enableGpu`, `uploadDir`, `outputDir`, `generatedImagesDir`, `apiUrl`, `frontendUrl`, `enableAuthentication` on InferenceApiConfig, `oauthCallbackUrl`, `enableRoute53`), loading the CDK config shall produce an object where that field is absent from its parent interface. - -**Validates: Requirements 1.1, 2.1, 4.1, 5.1, 10.1, 15.9, 18.1** - -### Property 2: Removed context keys do not exist in cdk.context.json - -*For any* key in the removed-context-keys set (`enableRds`, `rdsInstanceClass`, `rdsEngine`, `rdsDatabaseName`, `databaseType`, `enableGpu`, `uploadDir`, `outputDir`, `generatedImagesDir`, `apiUrl`, `frontendUrl`, `enableAuthentication` under inferenceApi, `oauthCallbackUrl`, `enableRoute53`, `entraClientId`, `entraTenantId`), parsing `cdk.context.json` shall not find that key in its expected section. - -**Validates: Requirements 1.2, 2.2, 4.2, 5.2, 8.5, 10.2, 11.4, 18.4** - -### Property 3: CORS origins fallback chain - -*For any* config section that consumes CORS origins (`fileUpload`, `assistants`, `ragIngestion`), the effective CORS value shall equal the per-section override if one is set, otherwise the top-level `corsOrigins` value from `AppConfig`. - -**Validates: Requirements 3.2, 3.3, 3.5** - -### Property 4: .env.example ↔ Python source synchronization - -*For any* environment variable name, it appears as an entry in `.env.example` if and only if at least one Python source file under `backend/src/` references it via `os.getenv` or `os.environ`. - -**Validates: Requirements 6.1, 6.3, 6.4** - -### Property 5: Context file ↔ config.ts synchronization - -*For any* context key read by `loadConfig()` via `scope.node.tryGetContext()`, `cdk.context.json` shall contain a corresponding key at the matching path. Conversely, for any non-framework key in `cdk.context.json`, `loadConfig()` shall read it. - -**Validates: Requirements 8.1, 8.2, 8.5** - -### Property 6: validateConfig rejects missing required fields for enabled stacks - -*For any* stack section where `enabled` is true, if a required configuration field for that stack is missing or empty, `validateConfig()` shall throw an error whose message contains both the field name and the stack name. Specifically: when `gateway.enabled` is true, `apiType` must be `'REST'` or `'HTTP'`; when `fileUpload.enabled` is true, CORS origins must be available. - -**Validates: Requirements 9.1, 9.2, 9.3, 9.4** - -### Property 7: GitHub workflow values use correct source type - -*For any* configuration value referenced in GitHub Actions workflow files, it shall use `vars.*` if it is in the non-sensitive set (`CDK_AWS_ACCOUNT`, `CDK_FRONTEND_CERTIFICATE_ARN`, `CDK_FRONTEND_BUCKET_NAME`, `SEED_AUTH_CLIENT_ID`) and `secrets.*` if it is in the sensitive set (`AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`, `AWS_ROLE_ARN`, `ENV_INFERENCE_API_TAVILY_API_KEY`, `ENV_INFERENCE_API_NOVA_ACT_API_KEY`, `SEED_AUTH_CLIENT_SECRET`). - -**Validates: Requirements 13.1, 13.2** - -### Property 8: No ENABLE_AUTHENTICATION references remain in executable code - -*For any* source file (TypeScript or Python) in the codebase, the string `ENABLE_AUTHENTICATION` or `enableAuthentication` shall not appear in executable code (imports, variable declarations, function calls, conditionals). Occurrences in comments, documentation files, and git history are excluded. - -**Validates: Requirements 14.8, 14.9, 14.10** - -### Property 9: No hardcoded defaults in loadConfig except empty-string sentinels - -*For any* configuration field in `loadConfig()`, the loading expression shall not contain a hardcoded literal fallback (e.g., `|| 365`, `parseBooleanEnv(..., true)`) except for empty-string sentinels (`|| ''`) on fields designated as "not set" indicators (`imageTag`, `ragIngestion.corsOrigins`). - -**Validates: Requirements 17.1, 17.2, 17.5** - -### Property 10: No hardcoded bash defaults in load-env.sh - -*For any* CDK configuration variable exported in `load-env.sh`, the export statement shall not contain a bash default value (e.g., `:-true`, `:-10`). Each variable shall fall back to `get_json_value` from the context file or be left unset. - -**Validates: Requirements 17.3, 17.4** - -### Property 11: Route53 record creation derived from domainName - -*For any* CDK synth of the FrontendStack, a Route53 A record shall be created if and only if `config.domainName` is set (non-empty). The `enableRoute53` flag shall not exist or be consulted. - -**Validates: Requirements 10.3, 10.4** - -## Error Handling - -### CDK Synth Time - -- `validateConfig()` throws descriptive errors for missing required fields, identifying the field name and the stack that requires it. -- TypeScript compiler catches references to removed interface fields at build time. -- `parseBooleanEnv()` throws on invalid boolean strings (not `true`/`false`/`1`/`0`). - -### Frontend Runtime - -- `ConfigService.loadConfig()` falls back to `environment.ts` values if `/config.json` fetch fails. After cleanup, the fallback config only contains `appApiUrl` and `environment`. -- `ConfigService.validateConfig()` rejects configs missing `appApiUrl` or `environment`. -- `preview-chat.service.ts` handles the case where `authApiService.getRuntimeEndpoint()` fails by surfacing an error to the user. - -### Backend Runtime - -- `get_current_user()` always enforces authentication. Missing or invalid tokens return 401. No auth providers configured returns 500. -- No silent auth bypass path exists after cleanup. - -### Shell Scripts - -- `load-env.sh` validates required variables (`CDK_PROJECT_PREFIX`, `CDK_AWS_ACCOUNT`, `CDK_AWS_REGION`) and exits with descriptive errors if missing. -- Variables without env var or context file values are left unset (not silently defaulted). - -## Testing Strategy - -This is a config cleanup — once dead fields are removed, there's nothing persistent to test. The strategy is: verify the cleanup is correct, then discard the test artifacts. - -### Verification Approach - -1. **TypeScript compilation**: Run `tsc --noEmit` after all config changes. If removed fields are still referenced anywhere, the compiler catches it. -2. **CDK synth**: Run `cdk synth` with only context defaults (no env vars). If the cleaned-up `cdk.context.json` is incomplete or mismatched, synth fails. -3. **Existing test suites**: Run the existing CDK tests (`npm test` in `infrastructure/`), frontend tests (`npm test` in `frontend/ai.client/`), and backend tests (`pytest` in `backend/`) to confirm nothing breaks. -4. **Grep-based spot checks**: Quick grep for removed field names (`enableRds`, `enableGpu`, `databaseType`, `ENABLE_AUTHENTICATION`, `inferenceApiUrl`, `enableRoute53`, `oauthCallbackUrl`) across the codebase to confirm no stale references remain. - -No new permanent test files are created. The existing test suites (updated to remove references to deleted fields) serve as the regression safety net. diff --git a/.kiro/specs/config-cleanup-audit/requirements.md b/.kiro/specs/config-cleanup-audit/requirements.md deleted file mode 100644 index 616e35fa..00000000 --- a/.kiro/specs/config-cleanup-audit/requirements.md +++ /dev/null @@ -1,277 +0,0 @@ -# Requirements Document - -## Introduction - -Audit and clean up redundant, unused, or unnecessary configuration variables across the entire AgentCore Public Stack codebase. Configuration is spread across backend environment variables (.env), frontend environment files, CDK infrastructure config (config.ts, cdk.context.json), and Docker/script files. Over time, dead config has accumulated — RDS fields that are hardcoded to disabled, CORS origins duplicated across four config sections, inference API fields that exist in CDK config but are never passed to containers, and GPU flags that are defined but never consumed by any stack. This feature removes the dead weight, consolidates duplicates, and ensures every remaining config variable is actually used and documented. - -## Glossary - -- **CDK_Config**: The infrastructure configuration system in `infrastructure/lib/config.ts` that loads values from environment variables and CDK context (`cdk.context.json`) -- **Env_File**: The backend `.env` file (template at `backend/src/.env.example`) containing runtime environment variables for the App API and Inference API -- **Frontend_Env**: The Angular environment files at `frontend/ai.client/src/environments/` that provide compile-time and fallback runtime configuration -- **Context_File**: The `infrastructure/cdk.context.json` file containing CDK context values used as defaults for infrastructure configuration -- **Audit_Report**: A structured inventory of every configuration variable with its usage status (used, unused, redundant, or deprecated) -- **CORS_Config**: Cross-Origin Resource Sharing origin lists, currently duplicated across `inferenceApi`, `fileUpload`, `assistants`, and `ragIngestion` config sections - -## Requirements - -### Requirement 1: Identify and Remove Unused RDS Configuration - -**User Story:** As a developer, I want dead RDS configuration removed from the codebase, so that the config interfaces are not cluttered with fields that are hardcoded to disabled and never consumed by any stack. - -#### Acceptance Criteria - -1. WHEN the CDK_Config is loaded, THE CDK_Config SHALL NOT contain the `enableRds`, `rdsInstanceClass`, `rdsEngine`, or `rdsDatabaseName` fields in the `AppApiConfig` interface -2. WHEN the Context_File is loaded, THE Context_File SHALL NOT contain `enableRds`, `rdsInstanceClass`, `rdsEngine`, or `rdsDatabaseName` keys in the `appApi` section -3. IF any infrastructure stack references removed RDS fields, THEN THE CDK_Config SHALL produce a compilation error at build time - -### Requirement 2: Identify and Remove Unused GPU Configuration - -**User Story:** As a developer, I want the unused `enableGpu` flag removed, so that the inference API config does not advertise a capability that no infrastructure stack actually provisions. - -#### Acceptance Criteria - -1. WHEN the CDK_Config is loaded, THE CDK_Config SHALL NOT contain the `enableGpu` field in the `InferenceApiConfig` interface -2. WHEN the Context_File is loaded, THE Context_File SHALL NOT contain the `enableGpu` key in the `inferenceApi` section -3. IF any infrastructure stack references the removed `enableGpu` field, THEN THE CDK_Config SHALL produce a compilation error at build time - -### Requirement 3: Consolidate Duplicated CORS Origins Configuration - -**User Story:** As a developer, I want CORS origins defined in one place instead of four separate config sections, so that I do not have to update the same value in `inferenceApi`, `fileUpload`, `assistants`, and `ragIngestion` every time a domain changes. - -#### Acceptance Criteria - -1. THE CDK_Config SHALL define a single top-level `corsOrigins` field in the `AppConfig` interface for shared CORS origin values -2. WHEN a stack requires CORS origins, THE CDK_Config SHALL provide the top-level `corsOrigins` value as the default -3. WHERE a stack requires stack-specific CORS origins that differ from the default, THE CDK_Config SHALL allow an optional per-section `corsOrigins` override -4. WHEN the Context_File is updated, THE Context_File SHALL contain a single top-level `corsOrigins` value instead of duplicated values across `fileUpload`, `assistants`, and `ragIngestion` sections -5. THE CDK_Config SHALL maintain backward compatibility by falling back to per-section `corsOrigins` values if the top-level value is not set - -### Requirement 4: Remove Inference API Directory Config from CDK - -**User Story:** As a developer, I want the `uploadDir`, `outputDir`, and `generatedImagesDir` fields removed from the CDK infrastructure config, so that container-internal directory paths are not managed as infrastructure-level configuration when they are never injected into deployed containers and serve no purpose in the CDK config. - -#### Acceptance Criteria - -1. WHEN the CDK_Config is loaded, THE CDK_Config SHALL NOT contain `uploadDir`, `outputDir`, or `generatedImagesDir` fields in the `InferenceApiConfig` interface -2. WHEN the Context_File is loaded, THE Context_File SHALL NOT contain `uploadDir`, `outputDir`, or `generatedImagesDir` keys in the `inferenceApi` section -3. THE CDK infrastructure tests SHALL NOT reference `uploadDir`, `outputDir`, or `generatedImagesDir` in test context setup -4. THE Env_File SHALL continue to define `UPLOAD_DIR`, `OUTPUT_DIR`, and `GENERATED_IMAGES_DIR` as local-development-only configuration, with comments clarifying that in deployed cloud environments these values are unused because the Dockerfiles create the directories at build time and the Python code falls back to hardcoded defaults - -### Requirement 5: Remove Hardcoded databaseType Configuration - -**User Story:** As a developer, I want the `databaseType` field removed from `AppApiConfig`, so that a config field hardcoded to `'none'` in the loader does not mislead developers into thinking it is configurable. - -#### Acceptance Criteria - -1. WHEN the CDK_Config is loaded, THE CDK_Config SHALL NOT contain the `databaseType` field in the `AppApiConfig` interface -2. WHEN the Context_File is loaded, THE Context_File SHALL NOT contain a `databaseType` key in the `appApi` section -3. IF any infrastructure stack references the removed `databaseType` field, THEN THE CDK_Config SHALL produce a compilation error at build time - -### Requirement 6: Synchronize .env.example with Actual Usage - -**User Story:** As a developer, I want the `.env.example` file to accurately reflect which environment variables are actually consumed by the codebase, so that new developers do not waste time configuring variables that nothing reads. - -#### Acceptance Criteria - -1. THE Env_File SHALL document only environment variables that are referenced by at least one Python module via `os.environ` or `os.getenv` -2. WHEN an environment variable is loaded via `os.getenv` or `os.environ`, THE loaded value SHALL be verified to have meaningful downstream usage (e.g., passed to a function, used in a condition, or assigned to a consumed field) — if the value is loaded but never meaningfully used, all remnants of it (the `os.getenv` call, any associated variable, and the `.env.example` entry) SHALL be removed -3. WHEN an environment variable is removed from all Python source files, THE Env_File SHALL remove the corresponding entry from `.env.example` -4. WHEN a new environment variable is added to a Python source file, THE Env_File SHALL include a corresponding documented entry in `.env.example` -5. THE Env_File SHALL group related variables under clearly labeled section headers - -### Requirement 7: Remove Dead Frontend Environment Imports - -**User Story:** As a developer, I want dead imports of the `environment` object removed from Angular source files that do not actually use it, so that the codebase does not give the false impression that environment files are consumed outside of `ConfigService`. - -#### Acceptance Criteria - -1. IF an Angular source file imports from `environments/environment` but does not reference the imported symbol in its executable code, THEN the import SHALL be removed -2. THE `ConfigService` SHALL remain the only Angular service that imports from `environments/environment` - -### Requirement 8: Synchronize cdk.context.json with config.ts - -**User Story:** As a developer, I want `cdk.context.json` to be a complete and accurate mirror of the context fallbacks defined in `loadConfig()`, so that every context-backed field has a sensible default and no stale or orphaned keys remain. - -#### Acceptance Criteria - -1. FOR every field in `loadConfig()` that reads from `scope.node.tryGetContext()`, THE Context_File SHALL contain a corresponding key with a sensible non-sensitive default value -2. THE Context_File SHALL NOT contain keys that are not read by `loadConfig()` or by CDK framework internals (e.g., `availability-zones:*`, `@aws-cdk/*`, `acknowledged-issue-numbers`) -3. WHERE `loadConfig()` reads a context key from a different path than where it exists in the Context_File (e.g., `domainName` read from top-level but defined under `frontend`), THE Context_File SHALL move the key to match the path that `loadConfig()` actually reads -4. THE Context_File SHALL NOT contain sensitive values (API keys, secrets, account IDs) — these SHALL be empty strings or placeholder values -5. WHEN other requirements in this spec remove fields from config interfaces (RDS, GPU, directory paths, databaseType), THE Context_File SHALL also remove the corresponding context keys - -### Requirement 9: Validate Configuration Completeness at Startup - -**User Story:** As a developer, I want the CDK config validation to catch missing or contradictory configuration at synth time, so that deployment failures caused by incomplete config are caught early. - -#### Acceptance Criteria - -1. WHEN `validateConfig()` runs, THE CDK_Config SHALL verify that all enabled stacks have their required configuration fields populated -2. WHEN `gateway.enabled` is true, THE CDK_Config SHALL verify that `gateway.apiType` is either `'REST'` or `'HTTP'` -3. WHEN `fileUpload.enabled` is true, THE CDK_Config SHALL verify that CORS origins are available (either from top-level or section-level config) -4. IF a required field is missing for an enabled stack, THEN THE CDK_Config SHALL throw a descriptive error identifying the missing field and which stack requires it - -### Requirement 10: Remove enableRoute53 Flag and Derive Route53 from domainName - -**User Story:** As a developer, I want the `enableRoute53` flag removed from the frontend config, so that Route53 DNS record creation is automatically derived from whether `domainName` is set — matching the same pattern the infrastructure stack uses for the ALB Route53 record. - -#### Acceptance Criteria - -1. THE CDK_Config SHALL remove the `enableRoute53` field from the `FrontendConfig` interface -2. THE Context_File SHALL remove the `enableRoute53` key from the `frontend` section -3. THE frontend stack SHALL create a Route53 A record when `config.domainName` is set (instead of checking `config.frontend.enableRoute53 && config.domainName`) -4. THE `loadConfig()` function SHALL NOT load `CDK_FRONTEND_ENABLE_ROUTE53` from environment or context -5. THE CDK infrastructure tests SHALL be updated to remove `enableRoute53` from test context setup -6. THE GitHub Actions reference docs SHALL remove the `CDK_FRONTEND_ENABLE_ROUTE53` variable entry - -### Requirement 11: Remove Stale Entra ID Configuration Remnants - -**User Story:** As a developer, I want the legacy Entra-specific configuration variables removed from CDK tests and GitHub Actions documentation, so that the codebase reflects the current generic OIDC provider model and does not mislead developers into configuring Entra-specific CDK variables that nothing reads. - -#### Acceptance Criteria - -1. THE CDK infrastructure tests SHALL NOT set `entraClientId`, `entraTenantId`, or `entraRedirectUri` in test context setup, since `loadConfig()` does not read these values -2. THE GitHub Actions reference at `.github/ACTIONS-REFERENCE.md` SHALL remove the `CDK_ENTRA_CLIENT_ID`, `CDK_ENTRA_TENANT_ID`, and `CDK_APP_API_ENTRA_REDIRECT_URI` entries -3. THE GitHub Actions quick-start guide at `.github/README-ACTIONS.md` SHALL replace the Entra-specific authentication guidance with a reference to the generic OIDC provider seeding workflow (`SEED_AUTH_*` variables) -4. THE Context_File SHALL NOT contain `entraClientId` or `entraTenantId` keys if they are present - -### Requirement 12: Document Configuration Variable Inventory - -**User Story:** As a developer, I want a single reference document listing every configuration variable, where it is defined, and where it is consumed, so that future audits are straightforward. - -#### Acceptance Criteria - -1. THE Audit_Report SHALL list every environment variable from `.env.example` with its consuming Python module path -2. THE Audit_Report SHALL list every CDK context key from `cdk.context.json` with its consuming config.ts field -3. THE Audit_Report SHALL list every frontend environment field with its consuming Angular service -4. THE Audit_Report SHALL flag any variable that is defined but not consumed as "unused" -5. THE Audit_Report SHALL be stored in `docs/CONFIG_INVENTORY.md` -6. THE GitHub Actions configuration reference at `.github/ACTIONS-REFERENCE.md` SHALL be updated to remove entries for any configuration variables deleted by this spec (e.g., `CDK_INFERENCE_API_ENABLE_GPU`, `ENV_INFERENCE_API_UPLOAD_DIR`, `ENV_INFERENCE_API_OUTPUT_DIR`, `ENV_INFERENCE_API_GENERATED_IMAGES_DIR`) and to reflect any renamed or consolidated variables (e.g., CORS origins consolidation) -7. THE GitHub Actions quick-start guide at `.github/README-ACTIONS.md` SHALL be updated if any removed or renamed variables are referenced in its examples or next-steps section - -### Requirement 13: Migrate Non-Sensitive GitHub Secrets to Variables - -**User Story:** As a developer, I want non-sensitive configuration values moved from GitHub Secrets to GitHub Variables, so that secrets are reserved for genuinely sensitive data and non-sensitive values are easier to inspect and manage. - -#### Acceptance Criteria - -1. THE following values SHALL be changed from `secrets.*` to `vars.*` in all workflow files where they appear: - - `CDK_AWS_ACCOUNT` — AWS account IDs are not credentials and appear in every ARN - - `CDK_FRONTEND_CERTIFICATE_ARN` — a resource ARN, not a credential - - `CDK_FRONTEND_BUCKET_NAME` — a bucket name, not a credential - - `SEED_AUTH_CLIENT_ID` — OAuth client IDs are public identifiers (the secret is `CLIENT_SECRET`) -2. THE following values SHALL remain as `secrets.*` because they are genuinely sensitive: - - `AWS_ACCESS_KEY_ID` — AWS credential - - `AWS_SECRET_ACCESS_KEY` — AWS credential - - `AWS_ROLE_ARN` — IAM role ARN (allows assuming a role) - - `ENV_INFERENCE_API_TAVILY_API_KEY` — third-party API key - - `ENV_INFERENCE_API_NOVA_ACT_API_KEY` — third-party API key - - `SEED_AUTH_CLIENT_SECRET` — OAuth client secret -3. THE `.github/ACTIONS-REFERENCE.md` SHALL update the Type column for each migrated value from "Secret" to "Variable" -4. THE `.github/README-ACTIONS.md` SHALL update any references to migrated values to reflect their new type - -### Requirement 14: Remove Authentication Enable/Disable Configuration - -**User Story:** As a developer, I want the `ENABLE_AUTHENTICATION` toggle and all its variants removed from the configuration surface, so that authentication is always enabled and there is no risk of accidentally deploying with auth disabled. The application requires authentication to function correctly in any deployed environment. - -#### Acceptance Criteria - -1. THE backend `dependencies.py` SHALL remove the `ENABLE_AUTHENTICATION` environment variable check and the `_check_auth_bypass()` function — authentication SHALL always be enforced -2. THE backend `dependencies.py` SHALL remove the `_create_anonymous_dev_user()` function since auth bypass is no longer supported -3. THE backend `jwt_validator.py` SHALL remove the `ENABLE_AUTHENTICATION` environment variable check -4. THE backend `inference_api/main.py` SHALL remove the `ENABLE_AUTHENTICATION` log line since the value is no longer configurable -5. THE Env_File SHALL remove the `ENABLE_AUTHENTICATION` entry from `.env.example` -6. THE frontend `ConfigService` SHALL remove `enableAuthentication` from the `RuntimeConfig` interface and all computed signals, defaulting all auth checks to `true` -7. THE frontend `environment.ts` and `environment.production.ts` SHALL remove the `enableAuthentication` field -8. THE frontend components that check `config.enableAuthentication()` (auth guard, admin guard, auth interceptor, auth service, user service, chat-http service) SHALL be updated to remove the conditional bypass paths -9. THE CDK config SHALL remove `CDK_ENABLE_AUTHENTICATION` from all GitHub Actions workflow files, `load-env.sh`, and `ACTIONS-REFERENCE.md` -10. THE CDK config SHALL remove `ENV_INFERENCE_API_ENABLE_AUTHENTICATION` from all GitHub Actions workflow files, `config.ts` `InferenceApiConfig` interface, and `ACTIONS-REFERENCE.md` -11. THE frontend build script (`scripts/stack-frontend/build.sh`) SHALL remove the `ENABLE_AUTHENTICATION` sed replacement logic -12. THE backend auth README at `backend/src/apis/shared/auth/README.md` SHALL be updated to remove documentation about the `ENABLE_AUTHENTICATION` toggle and the stale Entra-specific environment variable references - -### Requirement 15: Remove Static inferenceApiUrl Configuration - -**User Story:** As a developer, I want the static `inferenceApiUrl` configuration removed from the frontend and CDK config, because AgentCore Runtimes are provisioned dynamically per auth provider and there is no default or static inference API endpoint. The frontend already resolves the runtime endpoint dynamically via the App API based on the authenticated user's provider. - -#### Acceptance Criteria - -1. THE frontend `RuntimeConfig` interface in `ConfigService` SHALL remove the `inferenceApiUrl` field -2. THE frontend `ConfigService` SHALL remove the `inferenceApiUrl` computed signal and the `encodeUrlPath` helper method -3. THE frontend `environment.ts` SHALL remove the `inferenceApiUrl` field (the `http://localhost:8001` fallback is meaningless) -4. THE frontend `environment.production.ts` SHALL remove the `inferenceApiUrl` field -5. THE frontend `config.service.spec.ts` SHALL be updated to remove all `inferenceApiUrl` test cases -6. THE frontend `chat-http.service.ts` SHALL remove the static `inferenceApiUrl` fallback branch (the `!config.enableAuthentication()` path is already removed by Requirement 14; the only remaining path is the dynamic `getRuntimeEndpointUrl()` via `authApiService`) -7. THE frontend `preview-chat.service.ts` SHALL be updated to resolve the runtime endpoint dynamically via `authApiService.getRuntimeEndpoint()` instead of using the static `config.inferenceApiUrl()` -8. THE CDK frontend stack SHALL stop generating `inferenceApiUrl` in the runtime `config.json` if it currently does so -9. THE CDK `InferenceApiConfig` interface SHALL remove any fields related to a static inference API URL (e.g., `apiUrl`, `frontendUrl`) that are not consumed by any deployed resource -10. THE `.env.example` SHALL remove any inference API URL entries that are no longer consumed -11. THE `ACTIONS-REFERENCE.md` SHALL remove `ENV_INFERENCE_API_API_URL` and `ENV_INFERENCE_API_FRONTEND_URL` entries if they are no longer consumed by any stack - -### Requirement 16: Change retainDataOnDelete Default to False - -**User Story:** As a developer, I want `retainDataOnDelete` to default to `false`, so that development and test stacks clean up their resources on deletion by default instead of retaining orphaned DynamoDB tables and S3 buckets that accumulate cost. - -#### Acceptance Criteria - -1. THE Context_File SHALL set the `retainDataOnDelete` value to `false` — `cdk.context.json` is the single source of truth for default values per the configuration hierarchy (`Environment Variables > CDK Context > Defaults`) -2. THE `loadConfig()` function in `config.ts` SHALL NOT define a hardcoded default for `retainDataOnDelete` — it SHALL read from the environment variable and fall back to CDK context, which provides the default via `cdk.context.json` -3. THE `load-env.sh` script SHALL NOT define a hardcoded default for `CDK_RETAIN_DATA_ON_DELETE` — it SHALL read from the environment variable and fall back to the context file value (removing the `:-true` bash default) -4. THE `ACTIONS-REFERENCE.md` SHALL update the default value for `CDK_RETAIN_DATA_ON_DELETE` from `true` to `false` -5. THE `README-ACTIONS.md` SHALL note the default change if `CDK_RETAIN_DATA_ON_DELETE` is referenced in its guidance - -### Requirement 17: Enforce Configuration Default Hierarchy — Defaults in CDK Context Only - -**User Story:** As a developer, I want all configuration default values to live exclusively in `cdk.context.json`, so that the configuration hierarchy (`Environment Variables > CDK Context > Defaults`) is enforced consistently and there is exactly one place to look up or change any default. - -#### Acceptance Criteria - -1. THE `loadConfig()` function in `config.ts` SHALL NOT contain hardcoded fallback values for any configuration field — each field SHALL read from its environment variable first, then fall back to `scope.node.tryGetContext()`, with no trailing `|| ` or second argument to `parseBooleanEnv()` / `parseIntEnv()` that acts as a default -2. THE following hardcoded defaults in `loadConfig()` SHALL be removed and their values moved to corresponding keys in the Context_File: - - `production: parseBooleanEnv(..., true)` → context key `production` set to `true` - - `retainDataOnDelete: parseBooleanEnv(..., true)` → context key `retainDataOnDelete` set to `false` (per Requirement 16) - - `fileUpload.enabled: ... ?? true` → context key `fileUpload.enabled` set to `true` - - `fileUpload.maxFileSizeBytes: ... || 4 * 1024 * 1024` → context key `fileUpload.maxFileSizeBytes` set to `4194304` - - `fileUpload.maxFilesPerMessage: ... || 5` → context key `fileUpload.maxFilesPerMessage` set to `5` - - `fileUpload.userQuotaBytes: ... || 1024 * 1024 * 1024` → context key `fileUpload.userQuotaBytes` set to `1073741824` - - `fileUpload.retentionDays: ... || 365` → context key `fileUpload.retentionDays` set to `365` - - `assistants.enabled: ... ?? true` → context key `assistants.enabled` set to `true` - - `ragIngestion.enabled: ... ?? true` → context key `ragIngestion.enabled` set to `true` - - `ragIngestion.lambdaMemorySize: ... || 10240` → context key `ragIngestion.lambdaMemorySize` set to `10240` - - `ragIngestion.lambdaTimeout: ... || 900` → context key `ragIngestion.lambdaTimeout` set to `900` - - `ragIngestion.embeddingModel: ... || 'amazon.titan-embed-text-v2'` → context key `ragIngestion.embeddingModel` set to `"amazon.titan-embed-text-v2"` - - `ragIngestion.vectorDimension: ... || 1024` → context key `ragIngestion.vectorDimension` set to `1024` - - `ragIngestion.vectorDistanceMetric: ... || 'cosine'` → context key `ragIngestion.vectorDistanceMetric` set to `"cosine"` -3. THE `load-env.sh` script SHALL NOT contain hardcoded bash defaults (e.g., `:-true`, `:-10`) for any CDK configuration variable — it SHALL read from the environment variable first, then fall back to the context file via `get_json_value`, matching the hierarchy -4. THE following hardcoded defaults in `load-env.sh` SHALL be removed: - - `CDK_FILE_UPLOAD_CORS_ORIGINS` `:-http://localhost:4200` → fall back to context file value - - `CDK_FILE_UPLOAD_MAX_SIZE_MB` `:-10` → fall back to context file value -5. EXCEPTION: Empty-string fallbacks (`|| ''`) in `config.ts` for fields like `imageTag`, `oauthCallbackUrl`, and `ragIngestion.corsOrigins` are acceptable — these represent "not set" sentinels rather than meaningful defaults and SHALL be retained as-is -6. THE Context_File SHALL contain a complete set of default values for every field enumerated in criterion 2, ensuring that a fresh clone with no environment variables set can synthesize successfully using only context defaults - -### Requirement 18: Remove Dead oauthCallbackUrl from Inference API Config - -**User Story:** As a developer, I want the `oauthCallbackUrl` field removed from the `InferenceApiConfig` interface and all its upstream plumbing, because the OAuth callback URL is already derived from `domainName` or the ALB URL in `InfrastructureStack`, written to SSM, and injected into containers by the runtime provisioner Lambda — making the CDK config field dead code that nothing consumes. - -#### Acceptance Criteria - -1. THE `InferenceApiConfig` interface in `config.ts` SHALL remove the `oauthCallbackUrl` field -2. THE `loadConfig()` function SHALL remove the `oauthCallbackUrl` line that reads from `ENV_INFERENCE_API_OAUTH_CALLBACK_URL` -3. THE `load-env.sh` script SHALL remove the `ENV_INFERENCE_API_OAUTH_CALLBACK_URL` export and its context parameter block -4. THE Context_File SHALL remove the `oauthCallbackUrl` key from the `inferenceApi` section if present -5. THE GitHub Actions workflow `inference-api.yml` SHALL remove `ENV_INFERENCE_API_OAUTH_CALLBACK_URL` from its `env:` sections -6. THE `ACTIONS-REFERENCE.md` SHALL remove the `ENV_INFERENCE_API_OAUTH_CALLBACK_URL` entry -7. THE Requirement 17 empty-string exception list SHALL be updated to remove `oauthCallbackUrl` since the field no longer exists - -### Requirement 19: Audit and Clean Up CloudFormation Resource Tagging - -**User Story:** As a developer, I want resource tags to be predictable, minimal, and fully driven by `cdk.context.json`, so that I do not see unexpected tags on deployed resources and every tag has a clear origin. - -#### Acceptance Criteria - -1. THE `tags` object in `loadConfig()` SHALL be loaded entirely from `scope.node.tryGetContext('tags')` — the hardcoded `Project: projectPrefix` and `ManagedBy: 'CDK'` literals SHALL be removed from `config.ts` and moved to the `tags` section in `cdk.context.json` as the defaults -2. THE Context_File `tags` section SHALL contain only intentional, documented tags — remove any stale or unexpected tags (e.g., `Environment: 'dev'` should not be hardcoded if it does not reflect the actual deployment environment) -3. THE `applyStandardTags()` function SHALL apply only the tags from `config.tags` — no additional tags SHALL be injected by application code -4. THE `@aws-cdk/core:checksumAssetForResourceTags` context flag SHALL be reviewed — if it causes CDK to inject unexpected hash-based tags on resources, it SHALL be set to `false` or removed -5. THE CDK infrastructure tests SHALL be updated to reflect the cleaned-up tag set -6. THE `tags` section in `cdk.context.json` SHALL use `projectPrefix` value interpolation or a clear placeholder so that the `Project` tag matches the actual project prefix at deploy time, not a hardcoded string like `"AgentCore"` diff --git a/.kiro/specs/config-cleanup-audit/tasks.md b/.kiro/specs/config-cleanup-audit/tasks.md deleted file mode 100644 index a6d93b2e..00000000 --- a/.kiro/specs/config-cleanup-audit/tasks.md +++ /dev/null @@ -1,309 +0,0 @@ -# Implementation Plan: Config Cleanup Audit - -## Overview - -Systematic removal of dead configuration, consolidation of duplicates, enforcement of the config default hierarchy, and documentation of the final state. Changes are organized to minimize merge conflicts: structural changes to config.ts first, then dead code removal across layers, then consolidation, then validation and docs. - -All runtime commands must execute inside the Docker container (`docker compose exec dev `). - -## Tasks - -- [x] 1. Enforce config default hierarchy — move all hardcoded defaults to cdk.context.json - - [x] 1.1 Remove hardcoded fallback defaults from `loadConfig()` in `infrastructure/lib/config.ts` - - Remove trailing `|| ` and second arguments to `parseBooleanEnv()` / `parseIntEnv()` that act as defaults - - Retain empty-string fallbacks (`|| ''`) for `imageTag` and `ragIngestion.corsOrigins` as "not set" sentinels - - Each field reads env var first, then `scope.node.tryGetContext()`, with no hardcoded default - - _Requirements: 17.1, 17.2, 17.5_ - - - [x] 1.2 Add all default values to `cdk.context.json` - - Add `production: true`, `retainDataOnDelete: false` at top level - - Add `fileUpload.enabled: true`, `fileUpload.maxFileSizeBytes: 4194304`, `fileUpload.maxFilesPerMessage: 5`, `fileUpload.userQuotaBytes: 1073741824`, `fileUpload.retentionDays: 365` - - Add `assistants.enabled: true` - - Add `ragIngestion.enabled: true`, `ragIngestion.lambdaMemorySize: 10240`, `ragIngestion.lambdaTimeout: 900`, `ragIngestion.embeddingModel: "amazon.titan-embed-text-v2"`, `ragIngestion.vectorDimension: 1024`, `ragIngestion.vectorDistanceMetric: "cosine"` - - _Requirements: 16.1, 17.2, 17.6_ - - - [x] 1.3 Remove hardcoded bash defaults from `scripts/common/load-env.sh` - - Remove `:-true`, `:-http://localhost:4200`, `:-10` and similar bash defaults - - Each variable falls back to `get_json_value` from the context file - - _Requirements: 17.3, 17.4_ - -- [x] 2. Remove dead config fields from CDK interfaces and context - - [x] 2.1 Remove RDS fields from `AppApiConfig` interface and `loadConfig()` in `config.ts` - - Remove `enableRds`, `rdsInstanceClass`, `rdsEngine`, `rdsDatabaseName` from interface and loader - - _Requirements: 1.1, 1.3_ - - - [x] 2.2 Remove `databaseType` from `AppApiConfig` interface and `loadConfig()` in `config.ts` - - _Requirements: 5.1, 5.3_ - - - [x] 2.3 Remove GPU field from `InferenceApiConfig` interface and `loadConfig()` in `config.ts` - - Remove `enableGpu` from interface and loader - - _Requirements: 2.1, 2.3_ - - - [x] 2.4 Remove directory fields from `InferenceApiConfig` interface and `loadConfig()` in `config.ts` - - Remove `uploadDir`, `outputDir`, `generatedImagesDir` from interface and loader - - _Requirements: 4.1_ - - - [x] 2.5 Remove `oauthCallbackUrl` from `InferenceApiConfig` interface and `loadConfig()` in `config.ts` - - _Requirements: 18.1, 18.2_ - - - [x] 2.6 Remove `enableRoute53` from `FrontendConfig` interface and `loadConfig()` in `config.ts` - - _Requirements: 10.1, 10.4_ - - - [x] 2.7 Remove all corresponding dead keys from `cdk.context.json` - - Remove RDS keys (`enableRds`, `rdsInstanceClass`, `rdsEngine`, `rdsDatabaseName`) from `appApi` section - - Remove `databaseType` from `appApi` section - - Remove `enableGpu`, `uploadDir`, `outputDir`, `generatedImagesDir`, `oauthCallbackUrl` from `inferenceApi` section - - Remove `enableRoute53` from `frontend` section - - Remove `entraClientId`, `entraTenantId` if present - - _Requirements: 1.2, 2.2, 4.2, 5.2, 8.5, 10.2, 11.4, 18.4_ - - - [x] 2.8 Remove dead field exports from `scripts/common/load-env.sh` - - Remove exports and context param blocks for: GPU, directory fields, oauthCallbackUrl, enableRoute53, databaseType, RDS fields - - _Requirements: 10.4, 18.3_ - -- [x] 3. Remove ENABLE_AUTHENTICATION toggle entirely - - [x] 3.1 Remove auth bypass from backend `dependencies.py` - - Remove `ENABLE_AUTHENTICATION` env var check, `_check_auth_bypass()`, `_create_anonymous_dev_user()` - - Remove `bypass_user = _check_auth_bypass()` calls from `get_current_user` and `get_current_user_trusted` - - Authentication is always enforced - - _Requirements: 14.1, 14.2_ - - - [x] 3.2 Remove `ENABLE_AUTHENTICATION` from backend `jwt_validator.py` - - Remove the env var check - - _Requirements: 14.3_ - - - [x] 3.3 Remove `ENABLE_AUTHENTICATION` log line from `inference_api/main.py` - - _Requirements: 14.4_ - - - [x] 3.4 Remove `ENABLE_AUTHENTICATION` from `.env.example` - - _Requirements: 14.5_ - - - [x] 3.5 Remove `enableAuthentication` from frontend `ConfigService`, `RuntimeConfig`, and computed signals - - _Requirements: 14.6_ - - - [x] 3.6 Remove `enableAuthentication` from `environment.ts` and `environment.production.ts` - - _Requirements: 14.7_ - - - [x] 3.7 Update frontend components to remove auth conditional bypass paths - - Update auth guard, admin guard, auth interceptor, auth service, user service, chat-http service - - Remove `config.enableAuthentication()` checks — auth is always on - - _Requirements: 14.8_ - - - [x] 3.8 Remove `CDK_ENABLE_AUTHENTICATION` and `ENV_INFERENCE_API_ENABLE_AUTHENTICATION` from GitHub Actions workflows, `load-env.sh`, `config.ts` InferenceApiConfig, and `ACTIONS-REFERENCE.md` - - _Requirements: 14.9, 14.10_ - - - [x] 3.9 Remove `ENABLE_AUTHENTICATION` sed replacement from `scripts/stack-frontend/build.sh` - - _Requirements: 14.11_ - - - [x] 3.10 Update `backend/src/apis/shared/auth/README.md` to remove ENABLE_AUTHENTICATION docs and stale Entra env var references - - _Requirements: 14.12_ - -- [x] 4. Remove static inferenceApiUrl configuration - - [x] 4.1 Remove `inferenceApiUrl` from frontend `RuntimeConfig` interface, computed signal, and `encodeUrlPath` helper in `ConfigService` - - _Requirements: 15.1, 15.2_ - - - [x] 4.2 Remove `inferenceApiUrl` from `environment.ts` and `environment.production.ts` - - _Requirements: 15.3, 15.4_ - - - [x] 4.3 Update `config.service.spec.ts` to remove `inferenceApiUrl` test cases - - _Requirements: 15.5_ - - - [x] 4.4 Remove static `inferenceApiUrl` fallback from `chat-http.service.ts` - - The `!config.enableAuthentication()` path is already removed by task 3.7; remove any remaining static fallback - - _Requirements: 15.6_ - - - [x] 4.5 Update `preview-chat.service.ts` to resolve runtime endpoint dynamically via `authApiService.getRuntimeEndpoint()` - - _Requirements: 15.7_ - - - [x] 4.6 Remove `inferenceApiUrl` from CDK frontend stack `config.json` generation if present - - _Requirements: 15.8_ - - - [x] 4.7 Remove dead `apiUrl` and `frontendUrl` fields from `InferenceApiConfig` in `config.ts` and `cdk.context.json` - - _Requirements: 15.9_ - - - [x] 4.8 Remove inference API URL entries from `.env.example` and `ACTIONS-REFERENCE.md` - - _Requirements: 15.10, 15.11_ - -- [x] 5. Checkpoint — compile and verify after major removals - - Ensure TypeScript compiles cleanly: `docker compose exec dev bash -c "cd /workspace/bsu-org/agentcore-public-stack/infrastructure && npx tsc --noEmit"` - - Ensure CDK synth works: `docker compose exec dev bash -c "cd /workspace/bsu-org/agentcore-public-stack/infrastructure && npx cdk synth --quiet"` - - Ensure all tests pass, ask the user if questions arise. - -- [x] 6. Consolidate CORS origins to a single top-level field - - [x] 6.1 Add `corsOrigins` field to `AppConfig` interface in `config.ts` - - Define a single top-level `corsOrigins` in the `AppConfig` interface - - Load from env var / context with fallback chain - - _Requirements: 3.1_ - - - [x] 6.2 Update stacks to use top-level `corsOrigins` as default, with per-section override - - Each section that consumes CORS falls back to `config.corsOrigins` if its own `corsOrigins` is not set - - _Requirements: 3.2, 3.3, 3.5_ - - - [x] 6.3 Update `cdk.context.json` with single top-level `corsOrigins` and remove duplicated per-section values - - Remove `corsOrigins` from `fileUpload`, `assistants`, `ragIngestion` sections (keep `inferenceApi.corsOrigins` if it differs) - - Add top-level `corsOrigins` - - _Requirements: 3.4_ - - - [x] 6.4 Update `load-env.sh` to export a single `CDK_CORS_ORIGINS` and remove per-section CORS exports where redundant - - _Requirements: 3.4_ - -- [x] 7. Update frontend stack for Route53 derivation - - [x] 7.1 Change Route53 condition in frontend stack from `config.frontend.enableRoute53 && config.domainName` to `config.domainName` - - _Requirements: 10.3_ - - - [x] 7.2 Update CDK infrastructure tests to remove `enableRoute53` from test context setup - - _Requirements: 10.5_ - -- [x] 8. Synchronize .env.example with actual usage - - [x] 8.1 Audit all `os.getenv` / `os.environ` calls in `backend/src/` and cross-reference with `.env.example` - - Remove entries from `.env.example` that are not referenced by any Python module - - Verify loaded values have meaningful downstream usage; remove dead loads - - _Requirements: 6.1, 6.2, 6.3_ - - - [x] 8.2 Add section headers and comments to `.env.example` for clarity - - Group related variables under labeled sections - - Add comments for `UPLOAD_DIR`, `OUTPUT_DIR`, `GENERATED_IMAGES_DIR` clarifying they are local-dev-only - - _Requirements: 4.4, 6.5_ - -- [x] 9. Remove dead frontend environment imports - - [x] 9.1 Find and remove unused `environment` imports from Angular source files - - Only `ConfigService` should import from `environments/environment` - - _Requirements: 7.1, 7.2_ - -- [x] 10. Remove stale Entra ID configuration remnants - - [x] 10.1 Remove `entraClientId`, `entraTenantId`, `entraRedirectUri` from CDK infrastructure test context setup - - _Requirements: 11.1_ - - - [x] 10.2 Update `.github/ACTIONS-REFERENCE.md` to remove Entra-specific entries - - Remove `CDK_ENTRA_CLIENT_ID`, `CDK_ENTRA_TENANT_ID`, `CDK_APP_API_ENTRA_REDIRECT_URI` - - _Requirements: 11.2_ - - - [x] 10.3 Update `.github/README-ACTIONS.md` to replace Entra-specific auth guidance with generic OIDC reference - - _Requirements: 11.3_ - -- [x] 11. Migrate non-sensitive GitHub Secrets to Variables - - [x] 11.1 Change `secrets.CDK_AWS_ACCOUNT`, `secrets.CDK_FRONTEND_CERTIFICATE_ARN`, `secrets.CDK_FRONTEND_BUCKET_NAME`, `secrets.SEED_AUTH_CLIENT_ID` to `vars.*` in all workflow files - - _Requirements: 13.1_ - - - [x] 11.2 Update `ACTIONS-REFERENCE.md` Type column for migrated values from "Secret" to "Variable" - - _Requirements: 13.3_ - - - [x] 11.3 Update `README-ACTIONS.md` references for migrated values - - _Requirements: 13.4_ - -- [x] 12. Add validateConfig rules for enabled stacks - - [x] 12.1 Add validation in `validateConfig()` for `gateway.apiType` when `gateway.enabled` is true - - Verify `apiType` is `'REST'` or `'HTTP'`, throw descriptive error if not - - _Requirements: 9.2_ - - - [x] 12.2 Add validation in `validateConfig()` for CORS origins when `fileUpload.enabled` is true - - Verify CORS origins available from top-level or section-level config - - _Requirements: 9.3_ - - - [x] 12.3 Add validation in `validateConfig()` for required fields on all enabled stacks - - Throw descriptive error identifying missing field and which stack requires it - - _Requirements: 9.1, 9.4_ - -- [x] 13. Synchronize cdk.context.json with config.ts - - [x] 13.1 Ensure every `tryGetContext()` call in `loadConfig()` has a matching key in `cdk.context.json` - - _Requirements: 8.1_ - - - [x] 13.2 Remove orphaned non-framework keys from `cdk.context.json` that `loadConfig()` does not read - - Preserve CDK framework keys (`availability-zones:*`, `@aws-cdk/*`, `acknowledged-issue-numbers`) - - _Requirements: 8.2_ - - - [x] 13.3 Fix any path mismatches between context keys and `tryGetContext()` read paths - - E.g., if `domainName` is read from top-level but defined under `frontend`, move it - - _Requirements: 8.3_ - - - [x] 13.4 Ensure no sensitive values in `cdk.context.json` — use empty strings or placeholders - - _Requirements: 8.4_ - -- [x] 14. Update retainDataOnDelete default - - [x] 14.1 Set `retainDataOnDelete` to `false` in `cdk.context.json` - - _Requirements: 16.1_ - - - [x] 14.2 Remove hardcoded default for `retainDataOnDelete` from `config.ts` (already done in task 1.1, verify) - - _Requirements: 16.2_ - - - [x] 14.3 Remove `:-true` bash default for `CDK_RETAIN_DATA_ON_DELETE` from `load-env.sh` (already done in task 1.3, verify) - - _Requirements: 16.3_ - - - [x] 14.4 Update `ACTIONS-REFERENCE.md` default value for `CDK_RETAIN_DATA_ON_DELETE` from `true` to `false` - - _Requirements: 16.4_ - - - [x] 14.5 Update `README-ACTIONS.md` if `CDK_RETAIN_DATA_ON_DELETE` is referenced - - _Requirements: 16.5_ - -- [x] 15. Update GitHub Actions workflow files for all removed config - - [x] 15.1 Remove env entries for deleted fields from all `.github/workflows/*.yml` files - - Remove: `ENV_INFERENCE_API_ENABLE_AUTHENTICATION`, `ENV_INFERENCE_API_OAUTH_CALLBACK_URL`, `CDK_ENABLE_AUTHENTICATION`, `CDK_FRONTEND_ENABLE_ROUTE53`, `CDK_INFERENCE_API_ENABLE_GPU`, `ENV_INFERENCE_API_UPLOAD_DIR`, `ENV_INFERENCE_API_OUTPUT_DIR`, `ENV_INFERENCE_API_GENERATED_IMAGES_DIR`, `ENV_INFERENCE_API_API_URL`, `ENV_INFERENCE_API_FRONTEND_URL` - - _Requirements: 10.6, 12.6, 18.5_ - - - [x] 15.2 Update `ACTIONS-REFERENCE.md` to remove entries for all deleted config variables - - _Requirements: 10.6, 12.6, 18.6_ - - - [x] 15.3 Update `README-ACTIONS.md` to remove references to deleted variables - - _Requirements: 12.7_ - -- [x] 16. Checkpoint — full verification after all config changes - - Run TypeScript compilation: `docker compose exec dev bash -c "cd /workspace/bsu-org/agentcore-public-stack/infrastructure && npx tsc --noEmit"` - - Run CDK synth with context defaults only: `docker compose exec dev bash -c "cd /workspace/bsu-org/agentcore-public-stack/infrastructure && npx cdk synth --quiet"` - - Run CDK tests: `docker compose exec dev bash -c "cd /workspace/bsu-org/agentcore-public-stack/infrastructure && npm test"` - - Run frontend tests: `docker compose exec dev bash -c "cd /workspace/bsu-org/agentcore-public-stack/frontend/ai.client && npm test"` - - Run backend tests: `docker compose exec dev bash -c "cd /workspace/bsu-org/agentcore-public-stack/backend && python -m pytest tests/ -v"` - - Grep for stale references: `docker compose exec dev grep -r "enableRds\|enableGpu\|databaseType\|ENABLE_AUTHENTICATION\|enableAuthentication\|inferenceApiUrl\|enableRoute53\|oauthCallbackUrl" --include="*.ts" --include="*.py" --include="*.sh" --include="*.yml" /workspace/bsu-org/agentcore-public-stack/ -l` - - Ensure all tests pass, ask the user if questions arise. - -- [x] 17. Audit and clean up CloudFormation resource tagging - - [x] 17.1 Remove hardcoded tag literals from `loadConfig()` in `config.ts` - - Remove `Project: projectPrefix` and `ManagedBy: 'CDK'` from the `tags` object - - Load tags entirely from `scope.node.tryGetContext('tags') || {}` - - Update `applyStandardTags()` to inject `Project: config.projectPrefix` dynamically (since context can't interpolate) alongside context tags - - _Requirements: 19.1, 19.3_ - - - [x] 17.2 Clean up `tags` section in `cdk.context.json` - - Remove `Environment: 'dev'` (doesn't reflect actual deployment) - - Keep `ManagedBy: 'CDK'` as a context default - - Remove `Project: 'AgentCore'` (will be injected dynamically from `projectPrefix`) - - _Requirements: 19.2, 19.6_ - - - [x] 17.3 Review `@aws-cdk/core:checksumAssetForResourceTags` context flag - - Determine if it causes unexpected hash-based tags on resources - - Set to `false` or remove if it does - - _Requirements: 19.4_ - - - [x] 17.4 Update CDK infrastructure tests for cleaned-up tag set - - _Requirements: 19.5_ - -- [x] 18. Document configuration variable inventory - - [x] 17.1 Create `docs/CONFIG_INVENTORY.md` with complete variable inventory - - List every `.env.example` variable with consuming Python module path - - List every `cdk.context.json` key with consuming `config.ts` field - - List every frontend environment field with consuming Angular service - - Flag any variable defined but not consumed as "unused" - - _Requirements: 12.1, 12.2, 12.3, 12.4, 12.5_ - - - [x] 17.2 Final update to `ACTIONS-REFERENCE.md` for consolidated CORS and all remaining changes - - Ensure all deleted variables are removed, renamed/consolidated variables are reflected - - _Requirements: 12.6_ - - - [x] 17.3 Final update to `README-ACTIONS.md` for any remaining references - - _Requirements: 12.7_ - -- [x] 19. Final checkpoint — end-to-end verification - - Run TypeScript compilation: `docker compose exec dev bash -c "cd /workspace/bsu-org/agentcore-public-stack/infrastructure && npx tsc --noEmit"` - - Run CDK synth: `docker compose exec dev bash -c "cd /workspace/bsu-org/agentcore-public-stack/infrastructure && npx cdk synth --quiet"` - - Run all test suites (CDK, frontend, backend) - - Final grep for all removed field names to confirm zero stale references - - Ensure all tests pass, ask the user if questions arise. - -## Notes - -- All runtime commands must use `docker compose exec dev ` — never run directly on the host -- No new permanent test files are created; existing tests are updated to remove references to deleted fields -- Tasks are ordered so that structural changes (default hierarchy, interface removals) happen first, reducing merge conflicts -- Req 15 (remove inferenceApiUrl) depends on Req 14 (remove auth toggle) being done first — task ordering reflects this -- Req 8 (sync context) and Req 12 (documentation) are near the end since they inventory the final state -- Checkpoints at tasks 5, 16, and 18 ensure incremental verification -- Each task references specific requirement clauses for traceability diff --git a/.kiro/specs/environment-agnostic-refactor/design.md b/.kiro/specs/environment-agnostic-refactor/design.md deleted file mode 100644 index 51912017..00000000 --- a/.kiro/specs/environment-agnostic-refactor/design.md +++ /dev/null @@ -1,1172 +0,0 @@ -# Design Document: Environment-Agnostic Refactoring - -## Overview - -This design describes the refactoring of the AgentCore Public Stack from an environment-aware architecture to a fully configuration-driven, environment-agnostic system. The refactoring eliminates hardcoded environment logic (dev/test/prod conditionals) throughout the codebase and replaces it with explicit configuration parameters that can be set externally. - -The design maintains backward compatibility during migration and supports both single-environment deployments (typical for open-source users) and multi-environment deployments (for the internal development team using GitHub Environments). - -## Architecture - -### Current Architecture (Environment-Aware) - -``` -┌─────────────────────────────────────────────────────────────┐ -│ CDK Configuration (config.ts) │ -│ ┌─────────────────────────────────────────────────────────┐ │ -│ │ environment: 'prod' | 'dev' | 'test' │ │ -│ │ │ │ -│ │ getResourceName(config, 'vpc') │ │ -│ │ → if environment === 'prod': "prefix-vpc" │ │ -│ │ → else: "prefix-{env}-vpc" │ │ -│ │ │ │ -│ │ removalPolicy: environment === 'prod' ? RETAIN : DESTROY│ │ -│ │ corsOrigins: environment === 'prod' ? [...] : [...] │ │ -│ └─────────────────────────────────────────────────────────┘ │ -└─────────────────────────────────────────────────────────────┘ - ↓ -┌─────────────────────────────────────────────────────────────┐ -│ Deployment Scripts │ -│ DEPLOY_ENVIRONMENT=prod → cdk deploy --context env=prod │ -└─────────────────────────────────────────────────────────────┘ -``` - -**Problems:** -- Code makes decisions based on environment names -- Users cannot control behavior without modifying code -- Environment logic scattered across ~15 locations -- Implicit behavior based on environment string - -### Target Architecture (Configuration-Driven) - -``` -┌─────────────────────────────────────────────────────────────┐ -│ External Configuration (GitHub Variables / Env Vars) │ -│ ┌─────────────────────────────────────────────────────────┐ │ -│ │ CDK_PROJECT_PREFIX: "myproject-prod" │ │ -│ │ CDK_RETAIN_DATA_ON_DELETE: "true" │ │ -│ │ CDK_FILE_UPLOAD_CORS_ORIGINS: "https://app.example.com" │ │ -│ │ CDK_AWS_ACCOUNT: "123456789012" │ │ -│ │ CDK_AWS_REGION: "us-west-2" │ │ -│ └─────────────────────────────────────────────────────────┘ │ -└─────────────────────────────────────────────────────────────┘ - ↓ -┌─────────────────────────────────────────────────────────────┐ -│ CDK Configuration (config.ts) │ -│ ┌─────────────────────────────────────────────────────────┐ │ -│ │ projectPrefix: string │ │ -│ │ retainDataOnDelete: boolean │ │ -│ │ fileUpload.corsOrigins: string │ │ -│ │ │ │ -│ │ getResourceName(config, 'vpc') │ │ -│ │ → "{projectPrefix}-vpc" │ │ -│ │ │ │ -│ │ removalPolicy: retainDataOnDelete ? RETAIN : DESTROY │ │ -│ │ corsOrigins: config.fileUpload.corsOrigins.split(',') │ │ -│ └─────────────────────────────────────────────────────────┘ │ -└─────────────────────────────────────────────────────────────┘ - ↓ -┌─────────────────────────────────────────────────────────────┐ -│ Deployment Scripts │ -│ cdk deploy (reads from environment variables) │ -└─────────────────────────────────────────────────────────────┘ -``` - -**Benefits:** -- Code has zero knowledge of environments -- All behavior controlled by explicit configuration -- Users have full control without code changes -- Configuration is visible and documented - -## Components and Interfaces - -### 1. CDK Configuration Module (`infrastructure/lib/config.ts`) - -#### Current Interface - -```typescript -export interface AppConfig { - environment: 'prod' | 'dev' | 'test'; // ❌ Remove this - projectPrefix: string; - awsAccount: string; - awsRegion: string; - // ... other fields -} - -export function getResourceName(config: AppConfig, ...parts: string[]): string { - const envSuffix = config.environment === 'prod' ? '' : `-${config.environment}`; - return [config.projectPrefix + envSuffix, ...parts].join('-'); -} -``` - -#### New Interface - -```typescript -export interface AppConfig { - // Core identification - projectPrefix: string; - awsAccount: string; - awsRegion: string; - - // Behavior flags - retainDataOnDelete: boolean; // ✅ New: Controls removal policies - - // Feature configuration - fileUpload: { - corsOrigins: string; // Comma-separated list - maxFileSizeMb: number; - }; - - appApi: { - desiredCount: number; - maxCapacity: number; - cpu: number; - memory: number; - }; - - inferenceApi: { - desiredCount: number; - maxCapacity: number; - cpu: number; - memory: number; - }; - - // Optional features - enableAuthentication: boolean; -} - -export function getResourceName(config: AppConfig, ...parts: string[]): string { - // Simple concatenation - no environment logic - return [config.projectPrefix, ...parts].join('-'); -} - -export function parseBooleanEnv(value: string | undefined, defaultValue: boolean = false): boolean { - if (value === undefined) return defaultValue; - return value.toLowerCase() === 'true' || value === '1'; -} - -export function loadConfig(scope: Construct): AppConfig { - // Load from environment variables - const projectPrefix = process.env.CDK_PROJECT_PREFIX; - const awsAccount = process.env.CDK_AWS_ACCOUNT; - const awsRegion = process.env.CDK_AWS_REGION; - - // Validate required fields - if (!projectPrefix) throw new Error('CDK_PROJECT_PREFIX is required'); - if (!awsAccount) throw new Error('CDK_AWS_ACCOUNT is required'); - if (!awsRegion) throw new Error('CDK_AWS_REGION is required'); - - // Load behavior flags with defaults - const retainDataOnDelete = parseBooleanEnv( - process.env.CDK_RETAIN_DATA_ON_DELETE, - true // Default to retaining data for safety - ); - - // Load feature configuration - const corsOrigins = process.env.CDK_FILE_UPLOAD_CORS_ORIGINS || 'http://localhost:4200'; - - const config: AppConfig = { - projectPrefix, - awsAccount, - awsRegion, - retainDataOnDelete, - fileUpload: { - corsOrigins, - maxFileSizeMb: parseInt(process.env.CDK_FILE_UPLOAD_MAX_SIZE_MB || '10'), - }, - appApi: { - desiredCount: parseInt(process.env.CDK_APP_API_DESIRED_COUNT || '2'), - maxCapacity: parseInt(process.env.CDK_APP_API_MAX_CAPACITY || '10'), - cpu: parseInt(process.env.CDK_APP_API_CPU || '1024'), - memory: parseInt(process.env.CDK_APP_API_MEMORY || '2048'), - }, - inferenceApi: { - desiredCount: parseInt(process.env.CDK_INFERENCE_API_DESIRED_COUNT || '2'), - maxCapacity: parseInt(process.env.CDK_INFERENCE_API_MAX_CAPACITY || '10'), - cpu: parseInt(process.env.CDK_INFERENCE_API_CPU || '1024'), - memory: parseInt(process.env.CDK_INFERENCE_API_MEMORY || '2048'), - }, - enableAuthentication: parseBooleanEnv( - process.env.CDK_ENABLE_AUTHENTICATION, - true - ), - }; - - // Log configuration for debugging - console.log('📋 Loaded CDK Configuration:'); - console.log(` Project Prefix: ${config.projectPrefix}`); - console.log(` AWS Account: ${config.awsAccount}`); - console.log(` AWS Region: ${config.awsRegion}`); - console.log(` Retain Data on Delete: ${config.retainDataOnDelete}`); - console.log(` CORS Origins: ${config.fileUpload.corsOrigins}`); - - return config; -} -``` - -### 2. Removal Policy Helper - -```typescript -export function getRemovalPolicy(config: AppConfig): cdk.RemovalPolicy { - return config.retainDataOnDelete - ? cdk.RemovalPolicy.RETAIN - : cdk.RemovalPolicy.DESTROY; -} - -export function getAutoDeleteObjects(config: AppConfig): boolean { - return !config.retainDataOnDelete; -} -``` - -### 3. Stack Updates - -#### DynamoDB Tables (15 instances across stacks) - -**Before:** -```typescript -const userQuotaTable = new dynamodb.Table(this, 'UserQuotaTable', { - tableName: getResourceName(config, 'user-quotas'), - removalPolicy: config.environment === 'prod' - ? cdk.RemovalPolicy.RETAIN - : cdk.RemovalPolicy.DESTROY, - // ... -}); -``` - -**After:** -```typescript -const userQuotaTable = new dynamodb.Table(this, 'UserQuotaTable', { - tableName: getResourceName(config, 'user-quotas'), - removalPolicy: getRemovalPolicy(config), - // ... -}); -``` - -#### S3 Buckets - -**Before:** -```typescript -const userFilesBucket = new s3.Bucket(this, 'UserFilesBucket', { - bucketName: getResourceName(config, 'user-files'), - removalPolicy: config.environment === 'prod' - ? cdk.RemovalPolicy.RETAIN - : cdk.RemovalPolicy.DESTROY, - autoDeleteObjects: config.environment !== 'prod', - // ... -}); -``` - -**After:** -```typescript -const userFilesBucket = new s3.Bucket(this, 'UserFilesBucket', { - bucketName: getResourceName(config, 'user-files'), - removalPolicy: getRemovalPolicy(config), - autoDeleteObjects: getAutoDeleteObjects(config), - // ... -}); -``` - -#### CORS Configuration - -**Before:** -```typescript -const fileUploadCorsOrigins = config.fileUpload?.corsOrigins - ? config.fileUpload.corsOrigins.split(",").map((o) => o.trim()) - : config.environment === "prod" - ? ["https://boisestate.ai", "https://*.boisestate.ai"] - : ["http://localhost:4200", "http://localhost:8000"]; -``` - -**After:** -```typescript -const fileUploadCorsOrigins = config.fileUpload.corsOrigins - .split(",") - .map((o) => o.trim()); -``` - -### 4. Deployment Scripts - -#### `scripts/common/load-env.sh` - -**Before:** -```bash -#!/bin/bash -export DEPLOY_ENVIRONMENT="${DEPLOY_ENVIRONMENT:-prod}" -export CDK_PROJECT_PREFIX="${CDK_PROJECT_PREFIX}" -export CDK_AWS_ACCOUNT="${CDK_AWS_ACCOUNT}" -export CDK_AWS_REGION="${CDK_AWS_REGION}" -``` - -**After:** -```bash -#!/bin/bash -# Load configuration from environment variables -# All CDK_* variables should be set in GitHub Environment or .env file - -# Required variables -: "${CDK_PROJECT_PREFIX:?CDK_PROJECT_PREFIX is required}" -: "${CDK_AWS_ACCOUNT:?CDK_AWS_ACCOUNT is required}" -: "${CDK_AWS_REGION:?CDK_AWS_REGION is required}" - -# Optional variables with defaults -export CDK_RETAIN_DATA_ON_DELETE="${CDK_RETAIN_DATA_ON_DELETE:-true}" -export CDK_FILE_UPLOAD_CORS_ORIGINS="${CDK_FILE_UPLOAD_CORS_ORIGINS:-http://localhost:4200}" -export CDK_ENABLE_AUTHENTICATION="${CDK_ENABLE_AUTHENTICATION:-true}" - -echo "📋 Configuration loaded:" -echo " Project Prefix: ${CDK_PROJECT_PREFIX}" -echo " AWS Region: ${CDK_AWS_REGION}" -echo " Retain Data: ${CDK_RETAIN_DATA_ON_DELETE}" -``` - -#### CDK Deployment Commands - -**Before:** -```bash -cdk synth InfrastructureStack \ - --context environment="${DEPLOY_ENVIRONMENT}" \ - --context projectPrefix="${CDK_PROJECT_PREFIX}" \ - # ... -``` - -**After:** -```bash -# No context parameters needed - config loaded from environment variables -cdk synth InfrastructureStack -``` - -### 5. Frontend Configuration - -#### Current Approach (Multiple Files) - -``` -src/environments/ -├── environment.ts # Default (localhost) -├── environment.development.ts # Dev (hardcoded URLs) -└── environment.production.ts # Prod (hardcoded URLs) -``` - -#### New Approach (Single Template + Injection) - -``` -src/environments/ -└── environment.ts # Single file with placeholders -``` - -**environment.ts (template):** -```typescript -export const environment = { - production: ${PRODUCTION}, - appApiUrl: '${APP_API_URL}', - inferenceApiUrl: '${INFERENCE_API_URL}', - enableAuthentication: ${ENABLE_AUTHENTICATION} -}; -``` - -**Build script (`scripts/stack-frontend/build.sh`):** -```bash -#!/bin/bash - -# Default values for local development -export PRODUCTION="${PRODUCTION:-false}" -export APP_API_URL="${APP_API_URL:-http://localhost:8000}" -export INFERENCE_API_URL="${INFERENCE_API_URL:-http://localhost:8001}" -export ENABLE_AUTHENTICATION="${ENABLE_AUTHENTICATION:-true}" - -# Substitute environment variables -envsubst < src/environments/environment.ts.template > src/environments/environment.ts - -# Build Angular app -ng build --configuration production -``` - -### 6. GitHub Environments Configuration - -#### Environment Structure - -``` -GitHub Repository Settings → Environments -├── development -│ ├── Variables: -│ │ ├── CDK_PROJECT_PREFIX: "agentcore-dev" -│ │ ├── CDK_AWS_REGION: "us-west-2" -│ │ ├── CDK_RETAIN_DATA_ON_DELETE: "false" -│ │ ├── CDK_APP_API_DESIRED_COUNT: "1" -│ │ ├── CDK_FILE_UPLOAD_CORS_ORIGINS: "http://localhost:4200,https://dev.example.com" -│ │ ├── APP_API_URL: "https://dev-api.example.com" -│ │ └── INFERENCE_API_URL: "https://dev-inference.example.com" -│ └── Secrets: -│ ├── AWS_ROLE_ARN: "arn:aws:iam::111111111111:role/dev-deploy" -│ └── CDK_AWS_ACCOUNT: "111111111111" -│ -├── staging -│ ├── Variables: (similar structure with staging values) -│ └── Secrets: (staging AWS account) -│ -└── production - ├── Variables: - │ ├── CDK_PROJECT_PREFIX: "agentcore-prod" - │ ├── CDK_RETAIN_DATA_ON_DELETE: "true" - │ ├── CDK_APP_API_DESIRED_COUNT: "3" - │ └── ... (production values) - ├── Secrets: (production AWS account) - └── Protection Rules: - ├── Required reviewers: 2 - └── Wait timer: 5 minutes -``` - -#### Workflow Updates - -**`.github/workflows/infrastructure.yml`:** - -```yaml -name: Deploy Infrastructure - -on: - push: - branches: [main, develop] - workflow_dispatch: - inputs: - environment: - description: 'Deployment environment' - required: true - type: choice - options: [development, staging, production] - -jobs: - deploy: - runs-on: ubuntu-latest - - # Select environment based on trigger - environment: ${{ - github.event.inputs.environment || - (github.ref == 'refs/heads/main' && 'production' || 'development') - }} - - steps: - - uses: actions/checkout@v4 - - - name: Configure AWS Credentials - uses: aws-actions/configure-aws-credentials@v4 - with: - role-to-assume: ${{ secrets.AWS_ROLE_ARN }} - aws-region: ${{ vars.CDK_AWS_REGION }} - - - name: Setup Node.js - uses: actions/setup-node@v4 - with: - node-version: '20' - - - name: Install dependencies - run: | - cd infrastructure - npm install - - - name: Deploy Infrastructure - run: | - cd infrastructure - npx cdk deploy InfrastructureStack --require-approval never - env: - # All configuration comes from GitHub Environment - CDK_PROJECT_PREFIX: ${{ vars.CDK_PROJECT_PREFIX }} - CDK_AWS_ACCOUNT: ${{ secrets.CDK_AWS_ACCOUNT }} - CDK_AWS_REGION: ${{ vars.CDK_AWS_REGION }} - CDK_RETAIN_DATA_ON_DELETE: ${{ vars.CDK_RETAIN_DATA_ON_DELETE }} - CDK_FILE_UPLOAD_CORS_ORIGINS: ${{ vars.CDK_FILE_UPLOAD_CORS_ORIGINS }} - CDK_APP_API_DESIRED_COUNT: ${{ vars.CDK_APP_API_DESIRED_COUNT }} - CDK_APP_API_MAX_CAPACITY: ${{ vars.CDK_APP_API_MAX_CAPACITY }} -``` - -## Data Models - -### Configuration Schema - -```typescript -interface AppConfig { - // Identity - projectPrefix: string; // e.g., "agentcore-prod", "mycompany-dev" - awsAccount: string; // 12-digit AWS account ID - awsRegion: string; // AWS region code - - // Behavior - retainDataOnDelete: boolean; // true = RETAIN, false = DESTROY - - // Features - fileUpload: { - corsOrigins: string; // Comma-separated URLs - maxFileSizeMb: number; // Max file size in MB - }; - - appApi: { - desiredCount: number; // ECS task count - maxCapacity: number; // Auto-scaling max - cpu: number; // CPU units (1024 = 1 vCPU) - memory: number; // Memory in MB - }; - - inferenceApi: { - desiredCount: number; - maxCapacity: number; - cpu: number; - memory: number; - }; - - enableAuthentication: boolean; // Enable/disable auth - - // Deprecated - environment?: string; // For backward compatibility -} -``` - -### Environment Variable Mapping - -| Environment Variable | Type | Default | Description | -|---------------------|------|---------|-------------| -| `CDK_PROJECT_PREFIX` | string | (required) | Resource name prefix | -| `CDK_AWS_ACCOUNT` | string | (required) | AWS account ID | -| `CDK_AWS_REGION` | string | (required) | AWS region | -| `CDK_RETAIN_DATA_ON_DELETE` | boolean | `true` | Retain data on stack deletion | -| `CDK_FILE_UPLOAD_CORS_ORIGINS` | string | `http://localhost:4200` | Allowed CORS origins | -| `CDK_FILE_UPLOAD_MAX_SIZE_MB` | number | `10` | Max file upload size | -| `CDK_APP_API_DESIRED_COUNT` | number | `2` | App API task count | -| `CDK_APP_API_MAX_CAPACITY` | number | `10` | App API max tasks | -| `CDK_APP_API_CPU` | number | `1024` | App API CPU units | -| `CDK_APP_API_MEMORY` | number | `2048` | App API memory MB | -| `CDK_INFERENCE_API_DESIRED_COUNT` | number | `2` | Inference API task count | -| `CDK_INFERENCE_API_MAX_CAPACITY` | number | `10` | Inference API max tasks | -| `CDK_INFERENCE_API_CPU` | number | `1024` | Inference API CPU units | -| `CDK_INFERENCE_API_MEMORY` | number | `2048` | Inference API memory MB | -| `CDK_ENABLE_AUTHENTICATION` | boolean | `true` | Enable authentication | -| `APP_API_URL` | string | `http://localhost:8000` | Frontend: App API URL | -| `INFERENCE_API_URL` | string | `http://localhost:8001` | Frontend: Inference API URL | -| `PRODUCTION` | boolean | `false` | Frontend: Production mode | -| `ENABLE_AUTHENTICATION` | boolean | `true` | Frontend: Enable auth | - -## Correctness Properties - -*A property is a characteristic or behavior that should hold true across all valid executions of a system—essentially, a formal statement about what the system should do. Properties serve as the bridge between human-readable specifications and machine-verifiable correctness guarantees.* - - -### Prework Analysis Summary - -After analyzing all acceptance criteria, the following are testable as properties or examples: - -**Properties (universal rules):** -- Resource naming behavior (2.1-2.3) -- Removal policy mapping (3.2-3.3) -- CORS configuration loading (4.1, 4.4) -- Environment variable substitution (6.1, 6.3) -- Configuration loading from CDK_* variables (7.1, 7.3, 7.4) -- Validation behavior (11.1-11.5) -- Frontend runtime validation (14.5) - -**Examples (specific cases):** -- Interface structure checks (1.1, 1.4, 3.1, 6.2, 6.4, 7.2, 14.1) -- Static analysis checks (1.1, 3.4, 4.3, 5.1, 5.2, 5.4, 6.5, 10.1-10.6, 13.1) -- Default value checks (4.2) - -**Not testable:** -- Documentation requirements (8.*, 12.*) -- GitHub Actions workflow configuration (9.*) -- Logging behavior (7.5) -- Script execution behavior (5.3, 13.2, 13.4, 13.5, 14.4) - -### Property 1: Resource Naming is Environment-Agnostic - -*For any* project prefix and resource name parts, the generated resource name should be the project prefix concatenated with the resource parts using hyphens, with no automatic environment suffixes (`-dev`, `-test`, `-prod`) added. - -**Validates: Requirements 2.1, 2.2, 2.3** - -### Property 2: Removal Policy Follows Retention Flag - -*For any* configuration with a `retainDataOnDelete` flag, when the flag is true, data resources (DynamoDB tables, S3 buckets) should have removal policy RETAIN, and when the flag is false, they should have removal policy DESTROY with `autoDeleteObjects` enabled for S3 buckets. - -**Validates: Requirements 3.2, 3.3** - -### Property 3: CORS Origins are Configuration-Driven - -*For any* CORS configuration value, the system should parse it as a comma-separated list and use those origins without hardcoded environment-specific defaults. - -**Validates: Requirements 4.1, 4.4** - -### Property 4: Environment Variable Substitution Works Correctly - -*For any* template file with placeholder variables and corresponding environment variables, the build process should replace all placeholders with the environment variable values. - -**Validates: Requirements 6.1, 6.3** - -### Property 5: Configuration Loads from CDK_* Variables - -*For any* environment variable with `CDK_` prefix, the configuration loader should read and use that value, and when a variable is not set, it should use the documented default value. - -**Validates: Requirements 7.1, 7.3** - -### Property 6: Required Configuration Validation - -*For any* missing required configuration variable (projectPrefix, awsAccount, awsRegion), the system should throw an error before deployment that includes the variable name in the error message. - -**Validates: Requirements 7.4, 11.1, 11.2** - -### Property 7: Configuration Value Validation - -*For any* configuration value that has format requirements (boolean flags, AWS account IDs, AWS regions), the system should validate the format and reject invalid values with descriptive errors. - -**Validates: Requirements 11.3, 11.4, 11.5** - -### Property 8: Frontend Runtime Validation - -*For any* required frontend configuration value (appApiUrl, inferenceApiUrl), when the value is missing or invalid at runtime, the frontend should detect and report the configuration error. - -**Validates: Requirements 14.5** - -### Property 9: No Environment Conditionals in Codebase - -*For all* CDK stack files (infrastructure-stack.ts, app-api-stack.ts, inference-api-stack.ts, frontend-stack.ts, gateway-stack.ts), the code should contain zero references to `config.environment` property or `environment === 'prod'` conditionals. - -**Validates: Requirements 3.4, 10.1, 10.2, 10.3, 10.4, 10.5, 10.6** - -## Error Handling - -### Configuration Loading Errors - -**Missing Required Variables:** -```typescript -if (!projectPrefix) { - throw new Error( - 'CDK_PROJECT_PREFIX is required. ' + - 'Set this environment variable to your desired resource name prefix ' + - '(e.g., "mycompany-agentcore" or "mycompany-agentcore-prod")' - ); -} -``` - -**Invalid Boolean Values:** -```typescript -function parseBooleanEnv(value: string | undefined, defaultValue: boolean): boolean { - if (value === undefined) return defaultValue; - - const normalized = value.toLowerCase(); - if (normalized === 'true' || normalized === '1') return true; - if (normalized === 'false' || normalized === '0') return false; - - throw new Error( - `Invalid boolean value: "${value}". ` + - `Expected "true", "false", "1", or "0".` - ); -} -``` - -**Invalid AWS Account ID:** -```typescript -function validateAwsAccount(account: string): void { - if (!/^\d{12}$/.test(account)) { - throw new Error( - `Invalid AWS account ID: "${account}". ` + - `Expected a 12-digit number.` - ); - } -} -``` - -**Invalid AWS Region:** -```typescript -const VALID_REGIONS = [ - 'us-east-1', 'us-east-2', 'us-west-1', 'us-west-2', - 'eu-west-1', 'eu-west-2', 'eu-central-1', - 'ap-southeast-1', 'ap-southeast-2', 'ap-northeast-1', - // ... other regions -]; - -function validateAwsRegion(region: string): void { - if (!VALID_REGIONS.includes(region)) { - throw new Error( - `Invalid AWS region: "${region}". ` + - `Expected one of: ${VALID_REGIONS.join(', ')}` - ); - } -} -``` - -### Deployment Errors - -**Resource Name Conflicts:** -When deploying multiple environments to the same AWS account, users must use different project prefixes to avoid resource name conflicts. - -``` -Error: Resource with name "agentcore-vpc" already exists -Solution: Use a different CDK_PROJECT_PREFIX value (e.g., "agentcore-dev" vs "agentcore-prod") -``` - -**CORS Configuration Errors:** -Invalid CORS origins will cause API Gateway or ALB to reject requests. - -```typescript -function validateCorsOrigins(origins: string): void { - const originList = origins.split(',').map(o => o.trim()); - - for (const origin of originList) { - try { - new URL(origin); - } catch (e) { - throw new Error( - `Invalid CORS origin: "${origin}". ` + - `Expected a valid URL (e.g., "https://example.com")` - ); - } - } -} -``` - -### Frontend Build Errors - -**Missing Environment Variables:** -```bash -#!/bin/bash -: "${APP_API_URL:?APP_API_URL is required for production builds}" -: "${INFERENCE_API_URL:?INFERENCE_API_URL is required for production builds}" -``` - -**Template Substitution Errors:** -```bash -if ! command -v envsubst &> /dev/null; then - echo "Error: envsubst command not found" - echo "Install gettext package: apt-get install gettext-base" - exit 1 -fi -``` - -### Migration Errors - -**Configuration Not Found:** -```typescript -// No backward compatibility - users must migrate fully -if (process.env.DEPLOY_ENVIRONMENT) { - throw new Error( - '\n❌ DEPLOY_ENVIRONMENT is no longer supported\n' + - '━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\n' + - `Please migrate to explicit configuration:\n\n` + - ` Remove: DEPLOY_ENVIRONMENT=prod\n` + - ` Add: CDK_PROJECT_PREFIX=myproject-prod\n` + - ` CDK_RETAIN_DATA_ON_DELETE=true\n\n` + - `See migration guide: docs/MIGRATION_GUIDE.md\n` + - '━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\n' - ); -} -``` - -## Testing Strategy - -### Unit Tests - -**Configuration Loading Tests:** -```typescript -describe('loadConfig', () => { - it('should load configuration from environment variables', () => { - process.env.CDK_PROJECT_PREFIX = 'test-project'; - process.env.CDK_AWS_ACCOUNT = '123456789012'; - process.env.CDK_AWS_REGION = 'us-west-2'; - - const config = loadConfig(mockScope); - - expect(config.projectPrefix).toBe('test-project'); - expect(config.awsAccount).toBe('123456789012'); - expect(config.awsRegion).toBe('us-west-2'); - }); - - it('should throw error when required variables are missing', () => { - delete process.env.CDK_PROJECT_PREFIX; - - expect(() => loadConfig(mockScope)).toThrow('CDK_PROJECT_PREFIX is required'); - }); - - it('should use default values for optional variables', () => { - // Set only required variables - process.env.CDK_PROJECT_PREFIX = 'test'; - process.env.CDK_AWS_ACCOUNT = '123456789012'; - process.env.CDK_AWS_REGION = 'us-west-2'; - - const config = loadConfig(mockScope); - - expect(config.retainDataOnDelete).toBe(true); // Default - expect(config.fileUpload.corsOrigins).toBe('http://localhost:4200'); // Default - }); -}); -``` - -**Resource Naming Tests:** -```typescript -describe('getResourceName', () => { - it('should concatenate prefix and parts with hyphens', () => { - const config = { projectPrefix: 'myproject' }; - - expect(getResourceName(config, 'vpc')).toBe('myproject-vpc'); - expect(getResourceName(config, 'user', 'quotas')).toBe('myproject-user-quotas'); - }); - - it('should not add environment suffixes', () => { - const config = { projectPrefix: 'myproject' }; - - const name = getResourceName(config, 'vpc'); - - expect(name).not.toContain('-dev'); - expect(name).not.toContain('-test'); - expect(name).not.toContain('-prod'); - }); - - it('should preserve environment in prefix if user includes it', () => { - const config = { projectPrefix: 'myproject-dev' }; - - expect(getResourceName(config, 'vpc')).toBe('myproject-dev-vpc'); - }); -}); -``` - -**Removal Policy Tests:** -```typescript -describe('getRemovalPolicy', () => { - it('should return RETAIN when retainDataOnDelete is true', () => { - const config = { retainDataOnDelete: true }; - - expect(getRemovalPolicy(config)).toBe(cdk.RemovalPolicy.RETAIN); - }); - - it('should return DESTROY when retainDataOnDelete is false', () => { - const config = { retainDataOnDelete: false }; - - expect(getRemovalPolicy(config)).toBe(cdk.RemovalPolicy.DESTROY); - }); -}); - -describe('getAutoDeleteObjects', () => { - it('should return false when retainDataOnDelete is true', () => { - const config = { retainDataOnDelete: true }; - - expect(getAutoDeleteObjects(config)).toBe(false); - }); - - it('should return true when retainDataOnDelete is false', () => { - const config = { retainDataOnDelete: false }; - - expect(getAutoDeleteObjects(config)).toBe(true); - }); -}); -``` - -**Boolean Parsing Tests:** -```typescript -describe('parseBooleanEnv', () => { - it('should parse "true" as true', () => { - expect(parseBooleanEnv('true')).toBe(true); - expect(parseBooleanEnv('TRUE')).toBe(true); - expect(parseBooleanEnv('1')).toBe(true); - }); - - it('should parse "false" as false', () => { - expect(parseBooleanEnv('false')).toBe(false); - expect(parseBooleanEnv('FALSE')).toBe(false); - expect(parseBooleanEnv('0')).toBe(false); - }); - - it('should use default value when undefined', () => { - expect(parseBooleanEnv(undefined, true)).toBe(true); - expect(parseBooleanEnv(undefined, false)).toBe(false); - }); - - it('should throw error for invalid values', () => { - expect(() => parseBooleanEnv('yes')).toThrow('Invalid boolean value'); - expect(() => parseBooleanEnv('no')).toThrow('Invalid boolean value'); - expect(() => parseBooleanEnv('maybe')).toThrow('Invalid boolean value'); - }); -}); -``` - -**Validation Tests:** -```typescript -describe('validateAwsAccount', () => { - it('should accept valid 12-digit account IDs', () => { - expect(() => validateAwsAccount('123456789012')).not.toThrow(); - }); - - it('should reject non-12-digit account IDs', () => { - expect(() => validateAwsAccount('12345')).toThrow('Invalid AWS account ID'); - expect(() => validateAwsAccount('12345678901234')).toThrow('Invalid AWS account ID'); - }); - - it('should reject non-numeric account IDs', () => { - expect(() => validateAwsAccount('abcdefghijkl')).toThrow('Invalid AWS account ID'); - }); -}); - -describe('validateAwsRegion', () => { - it('should accept valid AWS regions', () => { - expect(() => validateAwsRegion('us-east-1')).not.toThrow(); - expect(() => validateAwsRegion('eu-west-1')).not.toThrow(); - }); - - it('should reject invalid regions', () => { - expect(() => validateAwsRegion('invalid-region')).toThrow('Invalid AWS region'); - expect(() => validateAwsRegion('us-east-99')).toThrow('Invalid AWS region'); - }); -}); -``` - -### Property-Based Tests - -**Property Test 1: Resource Naming (Property 1)** -```typescript -import * as fc from 'fast-check'; - -describe('Property: Resource naming is environment-agnostic', () => { - it('should never add environment suffixes to resource names', () => { - fc.assert( - fc.property( - fc.string({ minLength: 1, maxLength: 20 }).filter(s => /^[a-z0-9-]+$/.test(s)), - fc.array(fc.string({ minLength: 1, maxLength: 10 }).filter(s => /^[a-z0-9-]+$/.test(s))), - (prefix, parts) => { - const config = { projectPrefix: prefix }; - const name = getResourceName(config, ...parts); - - // Should not contain environment suffixes - const hasEnvSuffix = name.endsWith('-dev') || - name.endsWith('-test') || - name.endsWith('-prod'); - - return !hasEnvSuffix; - } - ), - { numRuns: 100 } - ); - }); -}); - -// Feature: environment-agnostic-refactor, Property 1: Resource naming is environment-agnostic -``` - -**Property Test 2: Removal Policy Mapping (Property 2)** -```typescript -describe('Property: Removal policy follows retention flag', () => { - it('should map retainDataOnDelete to correct removal policies', () => { - fc.assert( - fc.property( - fc.boolean(), - (retainDataOnDelete) => { - const config = { retainDataOnDelete }; - - const removalPolicy = getRemovalPolicy(config); - const autoDelete = getAutoDeleteObjects(config); - - if (retainDataOnDelete) { - return removalPolicy === cdk.RemovalPolicy.RETAIN && autoDelete === false; - } else { - return removalPolicy === cdk.RemovalPolicy.DESTROY && autoDelete === true; - } - } - ), - { numRuns: 100 } - ); - }); -}); - -// Feature: environment-agnostic-refactor, Property 2: Removal policy follows retention flag -``` - -**Property Test 3: CORS Configuration (Property 3)** -```typescript -describe('Property: CORS origins are configuration-driven', () => { - it('should parse comma-separated CORS origins correctly', () => { - fc.assert( - fc.property( - fc.array(fc.webUrl(), { minLength: 1, maxLength: 5 }), - (urls) => { - const corsString = urls.join(','); - const config = { fileUpload: { corsOrigins: corsString } }; - - const parsed = config.fileUpload.corsOrigins.split(',').map(o => o.trim()); - - return parsed.length === urls.length && - parsed.every((url, i) => url === urls[i]); - } - ), - { numRuns: 100 } - ); - }); -}); - -// Feature: environment-agnostic-refactor, Property 3: CORS origins are configuration-driven -``` - -**Property Test 4: Configuration Loading (Property 5)** -```typescript -describe('Property: Configuration loads from CDK_* variables', () => { - it('should load all CDK_* environment variables correctly', () => { - fc.assert( - fc.property( - fc.string({ minLength: 1, maxLength: 20 }), - fc.string({ minLength: 12, maxLength: 12 }).filter(s => /^\d+$/.test(s)), - fc.constantFrom('us-east-1', 'us-west-2', 'eu-west-1'), - (prefix, account, region) => { - process.env.CDK_PROJECT_PREFIX = prefix; - process.env.CDK_AWS_ACCOUNT = account; - process.env.CDK_AWS_REGION = region; - - const config = loadConfig(mockScope); - - return config.projectPrefix === prefix && - config.awsAccount === account && - config.awsRegion === region; - } - ), - { numRuns: 100 } - ); - }); -}); - -// Feature: environment-agnostic-refactor, Property 5: Configuration loads from CDK_* variables -``` - -**Property Test 5: Validation (Property 7)** -```typescript -describe('Property: Configuration value validation', () => { - it('should reject invalid AWS account IDs', () => { - fc.assert( - fc.property( - fc.string().filter(s => !/^\d{12}$/.test(s)), - (invalidAccount) => { - try { - validateAwsAccount(invalidAccount); - return false; // Should have thrown - } catch (e) { - return e.message.includes('Invalid AWS account ID'); - } - } - ), - { numRuns: 100 } - ); - }); - - it('should reject invalid boolean strings', () => { - fc.assert( - fc.property( - fc.string().filter(s => !['true', 'false', '1', '0', 'TRUE', 'FALSE'].includes(s)), - (invalidBool) => { - try { - parseBooleanEnv(invalidBool); - return false; // Should have thrown - } catch (e) { - return e.message.includes('Invalid boolean value'); - } - } - ), - { numRuns: 100 } - ); - }); -}); - -// Feature: environment-agnostic-refactor, Property 7: Configuration value validation -``` - -### Integration Tests - -**CDK Synthesis Test:** -```typescript -describe('CDK Stack Synthesis', () => { - it('should synthesize stacks without environment parameter', () => { - const app = new cdk.App(); - - process.env.CDK_PROJECT_PREFIX = 'test-project'; - process.env.CDK_AWS_ACCOUNT = '123456789012'; - process.env.CDK_AWS_REGION = 'us-west-2'; - process.env.CDK_RETAIN_DATA_ON_DELETE = 'false'; - - const stack = new InfrastructureStack(app, 'TestStack'); - const template = Template.fromStack(stack); - - // Verify resources are created with correct names - template.hasResourceProperties('AWS::EC2::VPC', { - Tags: [{ Key: 'Name', Value: 'test-project-vpc' }] - }); - - // Verify no environment-based logic - const resources = template.toJSON().Resources; - const resourceNames = Object.values(resources).map((r: any) => r.Properties?.TableName || r.Properties?.BucketName); - - resourceNames.forEach(name => { - if (name) { - expect(name).not.toContain('-dev'); - expect(name).not.toContain('-test'); - expect(name).not.toContain('-prod'); - } - }); - }); -}); -``` - -**Frontend Build Test:** -```bash -#!/bin/bash -# Test frontend build with environment variable substitution - -export APP_API_URL="https://test-api.example.com" -export INFERENCE_API_URL="https://test-inference.example.com" -export PRODUCTION="true" -export ENABLE_AUTHENTICATION="true" - -# Run build -cd frontend/ai.client -npm run build - -# Verify substitution worked -if grep -q "https://test-api.example.com" dist/*/main.*.js; then - echo "✅ Environment variable substitution successful" -else - echo "❌ Environment variable substitution failed" - exit 1 -fi -``` - -### Static Analysis Tests - -**Grep Tests for Environment References:** -```bash -#!/bin/bash -# Test that no environment conditionals exist in CDK code - -echo "Checking for environment conditionals..." - -# Check for config.environment references -if grep -r "config\.environment" infrastructure/lib/*.ts; then - echo "❌ Found config.environment references" - exit 1 -fi - -# Check for DEPLOY_ENVIRONMENT references -if grep -r "DEPLOY_ENVIRONMENT" scripts/; then - echo "❌ Found DEPLOY_ENVIRONMENT references" - exit 1 -fi - -# Check for environment === 'prod' patterns -if grep -r "environment === ['\"]prod['\"]" infrastructure/lib/*.ts; then - echo "❌ Found environment === 'prod' conditionals" - exit 1 -fi - -echo "✅ No environment conditionals found" -``` - -### Test Coverage Goals - -- **Unit tests**: 90%+ coverage of configuration loading and helper functions -- **Property tests**: 100 iterations minimum per property -- **Integration tests**: All CDK stacks synthesize successfully -- **Static analysis**: Zero environment conditionals in production code -- **End-to-end**: Successful deployment to test environment with new configuration - -### Testing During Migration - -**Migration Testing:** -- Test all stacks with new configuration variables only -- Verify resource names match expectations -- Confirm removal policies are correct -- Ensure DEPLOY_ENVIRONMENT throws clear error if present -- Verify all environment conditionals are removed diff --git a/.kiro/specs/environment-agnostic-refactor/requirements.md b/.kiro/specs/environment-agnostic-refactor/requirements.md deleted file mode 100644 index b7edc49b..00000000 --- a/.kiro/specs/environment-agnostic-refactor/requirements.md +++ /dev/null @@ -1,186 +0,0 @@ -# Requirements Document: Environment-Agnostic Refactoring - -## Introduction - -This specification defines the requirements for refactoring the AgentCore Public Stack application from an environment-aware codebase to a fully configuration-driven, environment-agnostic architecture. The refactoring will eliminate hardcoded environment logic (dev/test/prod conditionals) and replace it with explicit configuration parameters that can be set externally via GitHub Variables, environment variables, or CDK context. - -The goal is to make the codebase simple and accessible for open-source users deploying a single environment while maintaining the ability for the internal development team to manage multiple environments (dev/staging/prod) through GitHub Environments without code changes. - -## Glossary - -- **Environment-Agnostic Code**: Code that contains no knowledge of deployment environments (dev, test, prod) and makes no decisions based on environment names -- **Configuration-Driven**: An approach where all environment-specific behavior is controlled by external configuration rather than code logic -- **GitHub Environment**: A GitHub feature that allows setting environment-specific variables and secrets with optional protection rules -- **CDK Context**: Configuration values passed to AWS CDK applications via command-line parameters or cdk.json -- **Removal Policy**: AWS CDK setting that determines whether resources are retained or deleted when a stack is destroyed -- **Resource Naming**: The pattern used to generate AWS resource names (e.g., VPCs, DynamoDB tables, S3 buckets) -- **CORS Origins**: Cross-Origin Resource Sharing allowed origins for API endpoints -- **ECS Exec**: AWS ECS feature that allows debugging by executing commands in running containers -- **Project Prefix**: A string prepended to all AWS resource names to ensure uniqueness and identify ownership -- **Retention Flag**: A boolean configuration option that determines whether data resources should be retained on stack deletion - -## Requirements - -### Requirement 1: Remove Environment Parameter from CDK Configuration - -**User Story:** As an open-source user, I want to deploy the application without understanding environment concepts, so that I can get started quickly with minimal configuration. - -#### Acceptance Criteria - -1. THE CDK Configuration SHALL NOT contain an `environment` field in the `AppConfig` interface -2. THE CDK Configuration SHALL NOT accept an `environment` parameter from CDK context or environment variables -3. WHEN loading configuration, THE System SHALL NOT reference `DEPLOY_ENVIRONMENT` variable -4. THE CDK Configuration SHALL provide explicit boolean and string configuration options instead of environment-based conditionals - -### Requirement 2: Implement Configuration-Driven Resource Naming - -**User Story:** As a user, I want to control resource naming through a single configuration variable, so that I can deploy multiple instances without name conflicts. - -#### Acceptance Criteria - -1. THE Resource Naming Function SHALL use the `projectPrefix` value directly without appending environment suffixes -2. WHEN generating resource names, THE System SHALL concatenate `projectPrefix` with resource-specific parts using hyphens -3. THE System SHALL NOT add `-dev`, `-test`, or `-prod` suffixes automatically -4. WHEN users want environment-specific naming, THE System SHALL allow them to include the environment in the `projectPrefix` value itself (e.g., "myproject-dev") - -### Requirement 3: Replace Environment Conditionals with Explicit Configuration Flags - -**User Story:** As a developer, I want explicit configuration options for resource behavior, so that I can make informed decisions about retention and security settings. - -#### Acceptance Criteria - -1. THE CDK Configuration SHALL provide a `retainDataOnDelete` boolean flag to control removal policies -2. WHEN `retainDataOnDelete` is true, THE System SHALL set removal policies to RETAIN for data resources (DynamoDB tables, S3 buckets) -3. WHEN `retainDataOnDelete` is false, THE System SHALL set removal policies to DESTROY and enable `autoDeleteObjects` for S3 buckets -4. THE System SHALL NOT use `config.environment === 'prod'` or similar conditionals anywhere in the codebase - -### Requirement 4: Implement Configuration-Driven CORS Settings - -**User Story:** As a user, I want to specify allowed CORS origins through configuration, so that I can control API access without modifying code. - -#### Acceptance Criteria - -1. THE System SHALL load CORS origins from configuration variables -2. WHEN no CORS origins are specified, THE System SHALL use `http://localhost:4200` as the default for local development -3. THE System SHALL NOT have hardcoded production or development CORS origins in the code -4. WHEN multiple CORS origins are provided, THE System SHALL accept them as a comma-separated string - -### Requirement 5: Remove DEPLOY_ENVIRONMENT Variable from Scripts - -**User Story:** As a maintainer, I want to simplify deployment scripts by removing unused environment variables, so that the deployment process is clearer and less error-prone. - -#### Acceptance Criteria - -1. THE Deployment Scripts SHALL NOT export or reference `DEPLOY_ENVIRONMENT` variable -2. THE CDK Synthesis Commands SHALL NOT pass `--context environment="${DEPLOY_ENVIRONMENT}"` -3. THE Deployment Scripts SHALL pass explicit configuration flags as CDK context parameters -4. WHEN loading environment configuration, THE Scripts SHALL use specific variable names (e.g., `CDK_RETAIN_DATA_ON_DELETE`, `CDK_ENABLE_ECS_EXEC`) - -### Requirement 6: Implement Build-Time Configuration Injection for Frontend - -**User Story:** As a user, I want frontend API URLs to be configurable at build time, so that I can deploy to different environments without hardcoding URLs. - -#### Acceptance Criteria - -1. THE Frontend Build Process SHALL support environment variable substitution in configuration files -2. THE Frontend SHALL use a single environment configuration template with placeholder variables -3. WHEN building the frontend, THE System SHALL replace placeholders with values from environment variables -4. THE Frontend Configuration SHALL support variables for `appApiUrl`, `inferenceApiUrl`, and `enableAuthentication` -5. THE Frontend SHALL NOT contain separate `environment.development.ts` or `environment.production.ts` files with hardcoded URLs - -### Requirement 7: Update CDK Configuration Loading - -**User Story:** As a developer, I want CDK configuration to be loaded from explicit environment variables, so that I can see exactly what configuration is being used. - -#### Acceptance Criteria - -1. THE CDK Configuration Loader SHALL read configuration from environment variables with `CDK_` prefix -2. THE CDK Configuration Loader SHALL provide a `parseBooleanEnv()` helper function for boolean flags -3. WHEN a boolean environment variable is not set, THE System SHALL use sensible defaults (e.g., `retainDataOnDelete` defaults to true) -4. THE CDK Configuration SHALL validate that required variables are present before deployment -5. THE CDK Configuration SHALL log loaded configuration values for debugging purposes - -### Requirement 8: Document Configuration Options for Open-Source Users - -**User Story:** As an open-source user, I want clear documentation on required configuration variables, so that I can deploy the application successfully. - -#### Acceptance Criteria - -1. THE Documentation SHALL list all required GitHub Variables and Secrets for deployment -2. THE Documentation SHALL provide example values for each configuration variable -3. THE Documentation SHALL explain the purpose and impact of each configuration flag -4. THE Documentation SHALL include a "Quick Start" section for single-environment deployment -5. THE Documentation SHALL include an "Advanced" section for multi-environment deployment using GitHub Environments - -### Requirement 9: Support GitHub Environments for Multi-Environment Deployments - -**User Story:** As a team member, I want to use GitHub Environments to manage dev/staging/prod deployments, so that I can maintain separate environments without code changes. - -#### Acceptance Criteria - -1. THE GitHub Actions Workflows SHALL support the `environment` key to reference GitHub Environments -2. WHEN a workflow runs, THE System SHALL load variables and secrets from the specified GitHub Environment -3. THE Workflows SHALL support manual environment selection via `workflow_dispatch` inputs -4. THE Workflows SHALL support automatic environment selection based on branch (e.g., `main` → production, `develop` → development) -5. THE Documentation SHALL explain how to create and configure GitHub Environments - -### Requirement 10: Remove Environment-Specific Logic from All CDK Stacks - -**User Story:** As a maintainer, I want all CDK stacks to be environment-agnostic, so that the infrastructure code is simple and predictable. - -#### Acceptance Criteria - -1. THE Infrastructure Stack SHALL NOT contain `config.environment === 'prod'` conditionals -2. THE App API Stack SHALL NOT contain environment-based removal policy logic -3. THE Inference API Stack SHALL NOT contain environment-based configuration -4. THE Frontend Stack SHALL NOT contain environment-based CORS or domain logic -5. THE Gateway Stack SHALL NOT contain environment-based configuration -6. WHEN reviewing CDK code, THE System SHALL have zero references to `config.environment` property - -### Requirement 11: Validate Configuration at Deployment Time - -**User Story:** As a user, I want to receive clear error messages if required configuration is missing, so that I can fix issues before deployment fails. - -#### Acceptance Criteria - -1. WHEN required configuration variables are missing, THE System SHALL throw an error with a descriptive message -2. THE Error Message SHALL list the missing variable names and their expected format -3. THE System SHALL validate boolean flags are valid boolean strings ("true", "false", "1", "0") -4. THE System SHALL validate AWS account IDs are 12-digit numbers -5. THE System SHALL validate AWS regions are valid region codes - -### Requirement 12: Provide Migration Guide for Existing Deployments - -**User Story:** As a team member, I want a step-by-step migration guide, so that I can safely migrate existing deployments to the new configuration approach. - -#### Acceptance Criteria - -1. THE Migration Guide SHALL list all configuration variables that need to be created -2. THE Migration Guide SHALL provide a mapping from old environment-based behavior to new configuration flags -3. THE Migration Guide SHALL include a checklist of code changes required -4. THE Migration Guide SHALL explain how to test the migration in a non-production environment first -5. THE Migration Guide SHALL document rollback procedures if issues occur - -### Requirement 13: Update All Deployment Scripts - -**User Story:** As a user, I want deployment scripts to use the new configuration approach, so that deployments are consistent and predictable. - -#### Acceptance Criteria - -1. THE `load-env.sh` Script SHALL NOT export `DEPLOY_ENVIRONMENT` variable -2. THE CDK Deployment Scripts SHALL pass explicit configuration flags as context parameters -3. THE Frontend Build Scripts SHALL support environment variable substitution -4. THE Scripts SHALL validate required environment variables are set before proceeding -5. THE Scripts SHALL provide helpful error messages when configuration is missing - -### Requirement 14: Remove Environment Files from Frontend - -**User Story:** As a frontend developer, I want a single environment configuration file, so that I don't have to maintain multiple files with duplicated settings. - -#### Acceptance Criteria - -1. THE Frontend SHALL have a single `environment.ts` file with localhost defaults for local development -2. THE Frontend SHALL NOT have `environment.development.ts` or `environment.production.ts` files -3. WHEN building for deployment, THE System SHALL inject configuration values into the environment file -4. THE Frontend Build Process SHALL use `envsubst` or similar tool for variable substitution -5. THE Frontend SHALL validate that required configuration values are present at runtime diff --git a/.kiro/specs/environment-agnostic-refactor/task-10.1-summary.md b/.kiro/specs/environment-agnostic-refactor/task-10.1-summary.md deleted file mode 100644 index 45fd23bc..00000000 --- a/.kiro/specs/environment-agnostic-refactor/task-10.1-summary.md +++ /dev/null @@ -1,153 +0,0 @@ -# Task 10.1 Implementation Summary - -## Changes Made to `scripts/common/load-env.sh` - -### 1. Removed DEPLOY_ENVIRONMENT Variable -- ❌ Removed: `export DEPLOY_ENVIRONMENT="${DEPLOY_ENVIRONMENT:-prod}"` -- ❌ Removed: `--context environment="${DEPLOY_ENVIRONMENT}"` from `build_cdk_context_params()` -- ❌ Removed: `log_info " Environment: ${DEPLOY_ENVIRONMENT}"` from configuration display - -### 2. Added New Configuration Variables with Defaults -Added the following new variables with sensible defaults: - -```bash -# Behavior flags with defaults -export CDK_RETAIN_DATA_ON_DELETE="${CDK_RETAIN_DATA_ON_DELETE:-true}" -export CDK_ENABLE_AUTHENTICATION="${CDK_ENABLE_AUTHENTICATION:-true}" - -# File upload configuration with defaults -export CDK_FILE_UPLOAD_CORS_ORIGINS="${CDK_FILE_UPLOAD_CORS_ORIGINS:-http://localhost:4200}" -export CDK_FILE_UPLOAD_MAX_SIZE_MB="${CDK_FILE_UPLOAD_MAX_SIZE_MB:-10}" -``` - -### 3. Enhanced Validation - -#### Added `validate_required_vars()` Function -Validates that required CDK_* variables are set with helpful error messages: -- `CDK_PROJECT_PREFIX` - Required resource name prefix -- `CDK_AWS_ACCOUNT` - Required 12-digit AWS account ID -- `CDK_AWS_REGION` - Required AWS region code - -Each error includes: -- Clear error message -- Explanation of what the variable is for -- Example of how to set it - -#### Enhanced `validate_config()` Function -Added format validation for: -- **AWS Account ID**: Must be exactly 12 digits -- **Boolean flags**: Must be 'true', 'false', '1', or '0' - - `CDK_RETAIN_DATA_ON_DELETE` - - `CDK_ENABLE_AUTHENTICATION` - -### 4. Improved Configuration Logging - -#### Added `log_config()` Function -New logging function with blue color for configuration values: -```bash -log_config() { - echo -e "${BLUE}[CONFIG]${NC} $1" -} -``` - -#### Enhanced Configuration Display -Updated configuration output to show: -- ✅ Project Prefix -- ✅ AWS Account -- ✅ AWS Region -- ✅ VPC CIDR (with `` if empty) -- ✅ Retain Data flag -- ✅ CORS Origins -- ✅ Hosted Zone (if set) -- ✅ ALB Subdomain (if set) -- ✅ Certificate ARN (if set) -- ✅ AWS Identity (from credentials) - -### 5. Updated `build_cdk_context_params()` Function - -**Removed:** -```bash -context_params="${context_params} --context environment=\"${DEPLOY_ENVIRONMENT}\"" -``` - -**Now starts with:** -```bash -# Required parameters - always include (will fail validation if empty) -context_params="${context_params} --context projectPrefix=\"${CDK_PROJECT_PREFIX}\"" -context_params="${context_params} --context awsAccount=\"${CDK_AWS_ACCOUNT}\"" -context_params="${context_params} --context awsRegion=\"${CDK_AWS_REGION}\"" -``` - -## Validation Requirements Met - -✅ **Requirement 5.1**: Deployment Scripts SHALL NOT export or reference `DEPLOY_ENVIRONMENT` variable -- Removed all exports and references to `DEPLOY_ENVIRONMENT` - -✅ **Requirement 13.1**: The `load-env.sh` Script SHALL NOT export `DEPLOY_ENVIRONMENT` variable -- Variable completely removed from script - -✅ **Additional Requirements Implemented**: -- Added validation for required `CDK_*` variables (Requirement 7.4, 11.1) -- Added default values for optional variables (Requirement 7.3) -- Added configuration logging (Requirement 7.5) -- Added format validation for AWS Account ID (Requirement 11.4) -- Added format validation for boolean flags (Requirement 11.3) - -## Testing Recommendations - -### Manual Testing -```bash -# Test with minimal required variables -export CDK_PROJECT_PREFIX="test-project" -export CDK_AWS_ACCOUNT="123456789012" -export CDK_AWS_REGION="us-west-2" -source scripts/common/load-env.sh - -# Test with missing required variable -unset CDK_PROJECT_PREFIX -source scripts/common/load-env.sh # Should fail with helpful error - -# Test with invalid AWS account ID -export CDK_AWS_ACCOUNT="12345" -source scripts/common/load-env.sh # Should fail with validation error - -# Test with invalid boolean flag -export CDK_RETAIN_DATA_ON_DELETE="maybe" -source scripts/common/load-env.sh # Should fail with validation error -``` - -### Automated Testing -The script should be tested as part of: -- Task 10.2: Update deployment scripts to use new variables -- Task 11: Integration testing of all stacks -- Task 12: End-to-end deployment testing - -## Migration Impact - -### For Users -Users must now set explicit configuration variables instead of relying on `DEPLOY_ENVIRONMENT`: - -**Before:** -```bash -export DEPLOY_ENVIRONMENT="prod" -``` - -**After:** -```bash -export CDK_PROJECT_PREFIX="myproject-prod" -export CDK_AWS_ACCOUNT="123456789012" -export CDK_AWS_REGION="us-west-2" -export CDK_RETAIN_DATA_ON_DELETE="true" -``` - -### For CI/CD -GitHub Actions workflows must be updated to pass CDK_* variables instead of DEPLOY_ENVIRONMENT. - -## Files Modified -- ✅ `scripts/common/load-env.sh` - Complete refactor to remove environment awareness - -## Next Steps -- Task 10.2: Update individual stack deployment scripts -- Task 10.3: Update GitHub Actions workflows -- Task 11: Update CDK configuration loader -- Task 12: Integration testing diff --git a/.kiro/specs/environment-agnostic-refactor/tasks.md b/.kiro/specs/environment-agnostic-refactor/tasks.md deleted file mode 100644 index c81dec21..00000000 --- a/.kiro/specs/environment-agnostic-refactor/tasks.md +++ /dev/null @@ -1,436 +0,0 @@ -# Implementation Plan: Environment-Agnostic Refactoring - -## Overview - -This implementation plan converts the AgentCore Public Stack from an environment-aware architecture to a fully configuration-driven system. The refactoring removes all environment conditionals (dev/test/prod) and replaces them with explicit configuration parameters loaded from environment variables. - -The implementation follows a clean approach with no backward compatibility - all old environment-based logic has been removed and replaced with the new configuration system. - -## Progress Summary - -**Completed (Core Implementation):** -- ✅ CDK configuration module updated (environment field removed, new flags added) -- ✅ Resource naming simplified (no environment suffixes) -- ✅ Removal policy helpers implemented -- ✅ All CDK stacks updated (infrastructure, app-api, inference-api, frontend, gateway, rag-ingestion) -- ✅ Deployment scripts updated (load-env.sh, CDK synthesis commands) -- ✅ CDK synthesis checkpoint passed -- ✅ Frontend environment configuration (single file with build-time injection) -- ✅ Angular configuration updates (file replacements removed, runtime validation added) -- ✅ GitHub Actions workflows (environment selection and GitHub Environments integration) -- ✅ Documentation (migration guide created) - -**Remaining (Optional Enhancements):** -- GitHub Environments setup guide documentation -- Configuration reference table documentation -- Optional testing tasks (unit tests, property tests, static analysis) - -## Tasks - -- [x] 1. Update CDK Configuration Module - - [x] 1.1 Remove `environment` field from `AppConfig` interface - - Remove `environment: 'prod' | 'dev' | 'test'` field from interface - - Add `retainDataOnDelete: boolean` field - - Update all interface references in config.ts - - _Requirements: 1.1, 3.1_ - - - [x] 1.2 Implement configuration loading from environment variables - - Create `parseBooleanEnv()` helper function for boolean flags - - Create `validateAwsAccount()` function for account ID validation - - Create `validateAwsRegion()` function for region validation - - Update `loadConfig()` to read from `CDK_*` environment variables - - Add validation for required variables (projectPrefix, awsAccount, awsRegion) - - Add logging of loaded configuration values - - Throw error if `DEPLOY_ENVIRONMENT` is present (no backward compatibility) - - _Requirements: 1.2, 1.3, 7.1, 7.2, 7.3, 7.4_ - - - [ ]* 1.3 Write unit tests for configuration loading - - Test loading configuration from environment variables - - Test validation of required variables - - Test boolean parsing with valid and invalid values - - Test AWS account ID validation - - Test AWS region validation - - Test default values for optional variables - - Test error when DEPLOY_ENVIRONMENT is present - - _Requirements: 7.1, 7.2, 7.3, 7.4, 11.1, 11.2_ - - - [ ]* 1.4 Write property test for configuration loading - - **Property 5: Configuration loads from CDK_* variables** - - Generate random valid configuration values - - Verify all values are loaded correctly - - _Requirements: 7.1, 7.3_ - -- [x] 2. Update Resource Naming Function - - [x] 2.1 Simplify `getResourceName()` to remove environment suffix logic - - Remove environment suffix conditional logic - - Implement simple concatenation: `[projectPrefix, ...parts].join('-')` - - Update function signature if needed - - _Requirements: 2.1, 2.2, 2.3_ - - - [ ]* 2.2 Write unit tests for resource naming - - Test concatenation with various prefixes and parts - - Test that no `-dev`, `-test`, or `-prod` suffixes are added - - Test that user-provided environment in prefix is preserved - - _Requirements: 2.1, 2.2, 2.3_ - - - [ ]* 2.3 Write property test for resource naming - - **Property 1: Resource naming is environment-agnostic** - - Generate random project prefixes and resource parts - - Verify no automatic environment suffixes are added - - _Requirements: 2.1, 2.2, 2.3_ - -- [x] 3. Create Removal Policy Helper Functions - - [x] 3.1 Implement `getRemovalPolicy()` helper - - Create function that maps `retainDataOnDelete` to CDK RemovalPolicy - - Return RETAIN when true, DESTROY when false - - _Requirements: 3.2, 3.3_ - - - [x] 3.2 Implement `getAutoDeleteObjects()` helper - - Create function that returns inverse of `retainDataOnDelete` - - Return false when retaining, true when destroying - - _Requirements: 3.3_ - - - [ ]* 3.3 Write unit tests for removal policy helpers - - Test getRemovalPolicy with true and false - - Test getAutoDeleteObjects with true and false - - _Requirements: 3.2, 3.3_ - - - [ ]* 3.4 Write property test for removal policy mapping - - **Property 2: Removal policy follows retention flag** - - Generate random boolean values for retainDataOnDelete - - Verify correct mapping to removal policies - - _Requirements: 3.2, 3.3_ - -- [x] 4. Update Infrastructure Stack - - [x] 4.1 Remove environment conditionals from infrastructure-stack.ts - - Search for all `config.environment === 'prod'` patterns - - Replace removal policy conditionals with `getRemovalPolicy(config)` - - Update any other environment-based logic - - _Requirements: 3.4, 10.1_ - - - [ ]* 4.2 Write static analysis test for infrastructure stack - - Grep for `config.environment` references - - Grep for `environment === 'prod'` patterns - - Verify zero matches found - - _Requirements: 3.4, 10.1_ - -- [x] 5. Update App API Stack - - [x] 5.1 Remove environment conditionals from app-api-stack.ts - - Update all DynamoDB table removal policies to use `getRemovalPolicy(config)` - - Update S3 bucket removal policies and autoDeleteObjects - - Replace CORS origin conditionals with config-driven approach - - Remove any other environment-based logic - - _Requirements: 3.2, 3.3, 3.4, 4.1, 10.2_ - - - [ ]* 5.2 Write static analysis test for app API stack - - Grep for `config.environment` references - - Grep for hardcoded CORS origins - - Verify zero environment conditionals - - _Requirements: 3.4, 4.3, 10.2_ - -- [x] 6. Update Inference API Stack - - [x] 6.1 Remove environment conditionals from inference-api-stack.ts - - Update removal policies to use `getRemovalPolicy(config)` - - Remove any environment-based configuration - - _Requirements: 3.4, 10.3_ - - - [ ]* 6.2 Write static analysis test for inference API stack - - Grep for `config.environment` references - - Verify zero environment conditionals - - _Requirements: 3.4, 10.3_ - -- [x] 7. Update Frontend Stack - - [x] 7.1 Remove environment conditionals from frontend-stack.ts - - Update removal policies to use `getRemovalPolicy(config)` - - Remove environment-based CORS or domain logic - - _Requirements: 3.4, 10.4_ - - - [ ]* 7.2 Write static analysis test for frontend stack - - Grep for `config.environment` references - - Verify zero environment conditionals - - _Requirements: 3.4, 10.4_ - -- [x] 8. Update Gateway Stack - - [x] 8.1 Remove environment conditionals from gateway-stack.ts - - Update removal policies to use `getRemovalPolicy(config)` - - Remove any environment-based configuration - - _Requirements: 3.4, 10.5_ - - - [ ]* 8.2 Write static analysis test for gateway stack - - Grep for `config.environment` references - - Verify zero environment conditionals - - _Requirements: 3.4, 10.5_ - -- [x] 9. Checkpoint - Verify CDK stacks synthesize successfully - - Ensure all CDK stacks synthesize without errors - - Verify resource names are correct - - Verify removal policies are set correctly - - Ask the user if questions arise - -- [x] 10. Update Deployment Scripts - - [x] 10.1 Update `scripts/common/load-env.sh` - - Remove `DEPLOY_ENVIRONMENT` variable export - - Add validation for required `CDK_*` variables - - Add default values for optional variables - - Add configuration logging - - _Requirements: 5.1, 13.1_ - - - [x] 10.2 Update CDK synthesis scripts - - Remove `--context environment="${DEPLOY_ENVIRONMENT}"` from all cdk commands - - Update `scripts/stack-infrastructure/synth.sh` - - Update `scripts/stack-infrastructure/deploy.sh` - - Update other stack deployment scripts as needed - - _Requirements: 5.2_ - - - [ ]* 10.3 Write static analysis test for deployment scripts - - Grep for `DEPLOY_ENVIRONMENT` in all scripts - - Grep for `--context environment=` in all scripts - - Verify zero matches found - - _Requirements: 5.1, 5.2, 13.1_ - -- [x] 11. Update Frontend Environment Configuration - - [x] 11.1 Create single environment.ts file with localhost defaults - - Remove `environment.development.ts` and `environment.production.ts` files - - Update `environment.ts` to use localhost URLs for local development - - Ensure file works for local development without any configuration - - _Requirements: 6.2, 14.1, 14.2_ - - - [x] 11.2 Update frontend build script for production deployments - - Modify `scripts/stack-frontend/build.sh` to replace localhost URLs with deployment URLs - - Use `sed` or `envsubst` to inject environment-specific values at build time - - Set environment variables: `APP_API_URL`, `INFERENCE_API_URL`, `PRODUCTION`, `ENABLE_AUTHENTICATION` - - Add validation for required variables in production builds - - _Requirements: 6.1, 6.3, 13.3_ - - - [ ]* 11.3 Write static analysis test for frontend environment files - - Verify only one environment.ts file exists - - Verify no environment.development.ts or environment.production.ts files - - Grep for hardcoded production URLs in environment.ts - - _Requirements: 6.5, 14.2_ - - - [ ]* 11.4 Write property test for environment variable substitution - - **Property 4: Environment variable substitution works correctly** - - Generate random environment variable values - - Verify placeholders are replaced correctly - - _Requirements: 6.1, 6.3_ - -- [x] 12. Update Angular Configuration - - [x] 12.1 Update angular.json build configurations - - Remove file replacement configurations for environment files (no longer needed) - - Ensure build uses single environment.ts file - - _Requirements: 6.2_ - - - [x] 12.2 Add runtime configuration validation to frontend - - Add validation in app initialization (app.config.ts or main.ts) to check required config values - - Display clear error message if configuration is missing or invalid - - Validate appApiUrl and inferenceApiUrl are not localhost in production mode - - _Requirements: 14.5_ - - - [ ]* 12.3 Write property test for frontend runtime validation - - **Property 8: Frontend runtime validation** - - Generate configurations with missing required values - - Verify errors are detected and reported - - _Requirements: 14.5_ - -- [x] 13. Update GitHub Actions Workflows - - [x] 13.1 Update infrastructure.yml workflow - - Add `environment` key to job to reference GitHub Environments - - Add `workflow_dispatch` input for manual environment selection - - Add automatic environment selection based on branch (main → production, develop → development) - - Pass all configuration from GitHub Environment variables (CDK_PROJECT_PREFIX, CDK_AWS_REGION, etc.) - - Remove any DEPLOY_ENVIRONMENT references - - _Requirements: 9.1, 9.2, 9.3, 9.4_ - - - [x] 13.2 Update app-api.yml workflow - - Add environment selection logic (workflow_dispatch + branch-based) - - Pass configuration from GitHub Environment variables - - Update to use environment-specific AWS credentials - - _Requirements: 9.1, 9.2_ - - - [x] 13.3 Update inference-api.yml workflow - - Add environment selection logic (workflow_dispatch + branch-based) - - Pass configuration from GitHub Environment variables - - Update to use environment-specific AWS credentials - - _Requirements: 9.1, 9.2_ - - - [x] 13.4 Update frontend.yml workflow - - Add environment selection logic (workflow_dispatch + branch-based) - - Pass frontend configuration variables for build-time injection (APP_API_URL, INFERENCE_API_URL, etc.) - - Update to use environment-specific AWS credentials - - _Requirements: 9.1, 9.2_ - - - [x] 13.5 Update gateway.yml workflow - - Add environment selection logic (workflow_dispatch + branch-based) - - Pass configuration from GitHub Environment variables - - Update to use environment-specific AWS credentials - - _Requirements: 9.1, 9.2_ - -- [x] 14. Create Documentation - - [x] 14.1 Create migration guide (docs/MIGRATION_GUIDE.md) - - Document all configuration variables that need to be created - - Provide mapping from old environment-based behavior to new configuration flags - - Include step-by-step migration instructions with examples - - Document testing procedures for validating migration - - Include rollback procedures if issues occur - - Add troubleshooting section for common migration issues - - _Requirements: 12.1, 12.2, 12.3, 12.4, 12.5_ - - - [x] 14.2 Update README.md with configuration documentation - - Add "Quick Start" section for single-environment deployment - - List all required GitHub Variables and Secrets with descriptions - - Provide example values for each variable - - Explain purpose and impact of each configuration flag - - Add section on local development setup (no configuration needed) - - _Requirements: 8.1, 8.2, 8.3, 8.4_ - - - [ ]* 14.3 Add GitHub Environments setup guide - - Document how to create GitHub Environments in repository settings - - Explain environment-specific variables and secrets configuration - - Provide example configurations for development, staging, and production - - Document protection rules and approval workflows for production - - Add diagrams showing environment selection flow - - _Requirements: 8.4, 9.5_ - - - [ ]* 14.4 Create configuration reference table - - Create comprehensive table of all environment variables in docs/CONFIGURATION.md - - Include columns: variable name, type, default value, required/optional, description - - Organize by category (CDK, Frontend, Backend, Optional Features) - - Document which variables are required vs optional - - Add examples for each variable type - - _Requirements: 8.1, 8.2, 8.3_ - -- [ ] 15. Final Testing and Validation - - [ ]* 15.1 Run all unit tests - - Execute all configuration loading tests - - Execute all resource naming tests - - Execute all removal policy tests - - Execute all validation tests (AWS account, region, boolean parsing) - - Verify 100% pass rate - - _Requirements: All_ - - - [ ]* 15.2 Run all property-based tests - - Execute Property 1: Resource naming is environment-agnostic (100+ iterations) - - Execute Property 2: Removal policy follows retention flag (100+ iterations) - - Execute Property 3: CORS origins are configuration-driven (100+ iterations) - - Execute Property 4: Environment variable substitution (100+ iterations) - - Execute Property 5: Configuration loads from CDK_* variables (100+ iterations) - - Execute Property 7: Configuration value validation (100+ iterations) - - Execute Property 8: Frontend runtime validation (100+ iterations) - - Verify no failures across all properties - - _Requirements: All testable properties_ - - - [ ]* 15.3 Run static analysis tests - - Execute grep test for `config.environment` in CDK stacks (expect 0 matches) - - Execute grep test for `environment === 'prod'` patterns (expect 0 matches) - - Execute grep test for `DEPLOY_ENVIRONMENT` in scripts (expect 0 matches) - - Execute grep test for `--context environment=` in scripts (expect 0 matches) - - Execute grep test for hardcoded production URLs in frontend (expect 0 matches) - - Verify zero matches for all patterns - - _Requirements: 3.4, 5.1, 5.2, 10.1-10.6_ - - - [x] 15.4 Test CDK synthesis with new configuration - - Set all required CDK_* environment variables (CDK_PROJECT_PREFIX, CDK_AWS_ACCOUNT, CDK_AWS_REGION) - - Set optional variables (CDK_RETAIN_DATA_ON_DELETE, CDK_FILE_UPLOAD_CORS_ORIGINS, etc.) - - Synthesize all stacks (infrastructure, app-api, inference-api, frontend, gateway) - - Verify CloudFormation templates are generated correctly - - Verify resource names match expected pattern (projectPrefix-resource) - - Verify removal policies are set according to retainDataOnDelete flag - - Verify no environment suffixes (-dev, -test, -prod) in resource names - - _Requirements: All CDK requirements_ - - - [x] 15.5 Test frontend build with new configuration - - Test local development build (should use localhost URLs from environment.ts) - - Set frontend environment variables (APP_API_URL, INFERENCE_API_URL, PRODUCTION, ENABLE_AUTHENTICATION) - - Build frontend application for production - - Verify environment variable substitution worked correctly - - Verify no hardcoded production URLs remain in built files - - Verify production flag is set correctly - - Test that built application connects to correct API URLs - - _Requirements: 6.1, 6.3, 14.5_ - - - [x] 15.6 Test GitHub Actions workflow configuration - - Verify workflow files have environment selection logic - - Verify workflows reference GitHub Environment variables correctly - - Test workflow_dispatch with manual environment selection - - Test automatic environment selection based on branch - - Verify no DEPLOY_ENVIRONMENT references remain - - _Requirements: 9.1, 9.2, 9.3, 9.4_ - -- [x] 16. Final Checkpoint - - All core implementation tasks completed successfully - - CDK stacks synthesize without errors - - Configuration system fully functional - - Deployment scripts updated and working - - Frontend configuration implemented - - GitHub Actions workflows configured - - Migration guide documentation complete - - System is production-ready and environment-agnostic - -## Implementation Status - -### ✅ Core Implementation Complete - -The environment-agnostic refactoring is **fully implemented and production-ready**. All critical functionality has been completed: - -1. **CDK Configuration** - Fully refactored with explicit configuration flags -2. **Resource Naming** - Simplified to use projectPrefix without environment suffixes -3. **Removal Policies** - Configuration-driven with helper functions -4. **All CDK Stacks** - Updated to be environment-agnostic (6 stacks) -5. **Deployment Scripts** - Updated to use new configuration approach -6. **Frontend Configuration** - Single environment file with build-time injection -7. **GitHub Actions** - Environment selection and GitHub Environments integration -8. **Documentation** - Comprehensive migration guide with troubleshooting - -### 📋 Optional Enhancements - -The following tasks are marked as optional (with `*`) and can be completed for additional validation: - -- **Unit Tests** - Test configuration loading, validation, and helper functions -- **Property-Based Tests** - Test configuration properties across random inputs -- **Static Analysis Tests** - Grep tests to verify no environment conditionals remain -- **GitHub Environments Guide** - Detailed setup documentation -- **Configuration Reference** - Comprehensive table of all variables - -These optional tasks provide additional confidence but are not required for the system to function correctly. - -## Notes - -- Tasks marked with `*` are optional testing and documentation tasks -- Each task references specific requirements for traceability -- The implementation follows a clean break approach with no backward compatibility -- Configuration is fully external via environment variables -- GitHub Environments enable multi-environment deployments without code changes -- **Core implementation is complete and production-ready** - -## Key Achievements - -### Configuration System -- Removed `environment` field from CDK configuration -- Added explicit `retainDataOnDelete` boolean flag -- Implemented validation helpers for AWS account IDs, regions, and boolean values -- Created removal policy helper functions for consistent resource management -- All configuration loaded from `CDK_*` environment variables with clear defaults - -### Resource Management -- Simplified resource naming to use `projectPrefix` directly -- Removed automatic environment suffixes (`-dev`, `-test`, `-prod`) -- Users can include environment identifiers in prefix if desired (e.g., "myproject-prod") -- All removal policies now configuration-driven via `retainDataOnDelete` flag - -### Code Quality -- Zero environment conditionals in CDK stacks (verified across 6 stacks) -- No `config.environment` references anywhere in codebase -- No `DEPLOY_ENVIRONMENT` references in deployment scripts -- Clean, maintainable code that's easy for open-source users to understand - -### Deployment Flexibility -- Same codebase deploys to any environment -- Configuration changes don't require code modifications -- GitHub Environments support for multi-environment workflows -- Sensible defaults for quick single-environment deployment - -### Documentation -- Comprehensive migration guide with step-by-step instructions -- Troubleshooting section covering common issues -- Configuration variable reference with examples -- Rollback procedures for emergency situations diff --git a/.kiro/specs/github-actions-documentation/.config.kiro b/.kiro/specs/github-actions-documentation/.config.kiro deleted file mode 100644 index d30049bf..00000000 --- a/.kiro/specs/github-actions-documentation/.config.kiro +++ /dev/null @@ -1 +0,0 @@ -{"generationMode": "requirements-first"} \ No newline at end of file diff --git a/.kiro/specs/github-actions-documentation/design.md b/.kiro/specs/github-actions-documentation/design.md deleted file mode 100644 index 534b833e..00000000 --- a/.kiro/specs/github-actions-documentation/design.md +++ /dev/null @@ -1,505 +0,0 @@ -# Design Document: GitHub Actions Configuration Documentation - -## Overview - -This design specifies a documentation generation system that creates comprehensive reference documentation for GitHub Actions configuration in the AgentCore Public Stack project. The system will analyze 5 workflow files, extract all GitHub Variables and Secrets, trace their usage through scripts and CDK stacks, determine requirement status, identify default values, and generate a well-structured markdown document at `.github/README-ACTIONS.md`. - -The documentation will serve as the single source of truth for developers setting up GitHub Actions for CI/CD deployment, eliminating confusion about which configuration values are needed and where they come from. - -## Architecture - -### High-Level Flow - -``` -Workflow Files (.github/workflows/*.yml) - ↓ - [Extraction Layer] - ↓ -Configuration Scripts (scripts/common/load-env.sh) - ↓ - [Tracing Layer] - ↓ -CDK Configuration (infrastructure/lib/config.ts, cdk.context.json) - ↓ - [Analysis Layer] - ↓ -Documentation Generator - ↓ -README-ACTIONS.md -``` - -### Component Architecture - -The system consists of four main components: - -1. **Workflow Parser**: Extracts variables and secrets from YAML workflow files -2. **Configuration Tracer**: Traces configuration values through scripts and CDK -3. **Requirement Analyzer**: Determines if values are required or optional -4. **Documentation Generator**: Produces formatted markdown output - -## Components and Interfaces - -### 1. Workflow Parser - -**Purpose**: Extract all GitHub Variables (`vars.*`) and Secrets (`secrets.*`) from workflow YAML files. - -**Input**: -- Workflow file path (string) -- Workflow YAML content (string) - -**Output**: -```typescript -interface WorkflowConfig { - workflowName: string; - variables: ConfigValue[]; - secrets: ConfigValue[]; -} - -interface ConfigValue { - name: string; // e.g., "AWS_REGION", "CDK_AWS_ACCOUNT" - type: 'variable' | 'secret'; - usageLocations: string[]; // Job names or step names where used -} -``` - -**Algorithm**: -1. Parse YAML using a YAML parser library -2. Traverse all `env:` blocks at workflow, job, and step levels -3. Extract references matching patterns: - - `${{ vars.VARIABLE_NAME }}` - - `${{ secrets.SECRET_NAME }}` -4. Record the location (job/step) where each is used -5. Deduplicate by name while preserving all usage locations - -**Edge Cases**: -- Variables used in conditional expressions (`if:` statements) -- Variables used in matrix strategies -- Variables used in reusable workflow calls - -### 2. Configuration Tracer - -**Purpose**: Trace configuration values from workflows through scripts to CDK stacks to understand their flow and find default values. - -**Input**: -- ConfigValue from Workflow Parser -- File paths to check: `scripts/common/load-env.sh`, `infrastructure/lib/config.ts`, `infrastructure/cdk.context.json` - -**Output**: -```typescript -interface TracedConfig extends ConfigValue { - defaultValue?: string | number | boolean; - defaultSource?: 'workflow' | 'load-env.sh' | 'config.ts' | 'cdk.context.json'; - cdkUsage?: { - configKey: string; // Key in config.ts interface - stacksUsing: string[]; // Which stacks use this config - }; -} -``` - -**Tracing Logic**: - -For each configuration value: - -1. **Check workflow YAML** for inline defaults: - ```yaml - env: - CDK_REQUIRE_APPROVAL: never # This is a default - ``` - -2. **Check `load-env.sh`** for export statements with defaults: - ```bash - export CDK_AWS_REGION="${CDK_AWS_REGION:-$(get_json_value "awsRegion" "${CONTEXT_FILE}")}" - # Default comes from cdk.context.json if env var not set - ``` - -3. **Check `config.ts`** for fallback values: - ```typescript - production: parseBooleanEnv(process.env.CDK_PRODUCTION, true), // Default: true - ``` - -4. **Check `cdk.context.json`** for context defaults: - ```json - { - "awsRegion": "us-west-2", - "appApi": { - "cpu": 512 - } - } - ``` - -**Parsing Strategies**: -- **YAML**: Use YAML parser library -- **Shell script**: Regex patterns for `export VAR="${VAR:-default}"` and `get_json_value` calls -- **TypeScript**: AST parsing or regex for assignment patterns with `||` or default parameters -- **JSON**: Standard JSON parser - -### 3. Requirement Analyzer - -**Purpose**: Determine if a configuration value is Required or Optional based on whether it has defaults and whether downstream resources require it. - -**Input**: -- TracedConfig from Configuration Tracer - -**Output**: -```typescript -interface AnalyzedConfig extends TracedConfig { - required: boolean; - requirementReason: string; // Human-readable explanation -} -``` - -**Decision Logic**: - -A configuration value is **Required** if: -1. It has NO default value in any location (workflow, load-env.sh, config.ts, cdk.context.json), AND -2. The downstream CDK resource or script requires it to function - -A configuration value is **Optional** if: -1. It has a default value in any location, OR -2. The downstream resource can function without it (e.g., optional features) - -**Determining Downstream Requirements**: - -For CDK configuration: -- Check if the config property is marked with `?` (optional) in TypeScript interface -- Check if the config is used in conditional logic (`if (config.value)`) -- Check if validation in `config.ts` throws errors for missing values - -For AWS resources: -- Use AWS MCP tools to check resource documentation -- Example: `CDK_AWS_ACCOUNT` is required because AWS CDK cannot deploy without an account ID -- Example: `CDK_CERTIFICATE_ARN` is optional because ALB can work without HTTPS - -**Examples**: - -```typescript -// Required: No default, validation throws error -if (!projectPrefix) { - throw new Error('CDK_PROJECT_PREFIX is required'); -} - -// Optional: Has default value -production: parseBooleanEnv(process.env.CDK_PRODUCTION, true), // Default: true - -// Optional: Marked optional in interface -certificateArn?: string; - -// Optional: Used conditionally -if (config.certificateArn) { - // Configure HTTPS -} -``` - -### 4. Documentation Generator - -**Purpose**: Generate formatted markdown documentation from analyzed configuration values. - -**Input**: -- Map of workflow name to AnalyzedConfig[] -- Template for documentation structure - -**Output**: -- Markdown string to be written to `.github/README-ACTIONS.md` - -**Document Structure**: - -```markdown -# GitHub Actions Configuration - -## GitHub Variables and Secrets - -This document lists all GitHub Variables and Secrets required for CI/CD workflows. - -### Infrastructure Stack - -| Name | Type | Required | Default | Description | -|------|------|----------|---------|-------------| -| AWS_REGION | Variable | Yes | `us-west-2` | AWS region for deployment | -| CDK_AWS_ACCOUNT | Secret | Yes | None | 12-digit AWS account ID | -| ... | ... | ... | ... | ... | - -### App API Stack - -[Same table structure] - -### Inference API Stack - -[Same table structure] - -### Frontend Stack - -[Same table structure] - -### Gateway Stack - -[Same table structure] -``` - -**Formatting Rules**: -- Use markdown tables for consistency and scannability -- Sort entries alphabetically by name within each stack -- Use backticks for default values: `` `true` ``, `` `us-west-2` `` -- Use "None" for missing defaults -- Keep descriptions to one sentence (max 100 characters) -- Use consistent capitalization: "Yes"/"No" for Required column - -**Description Generation**: - -Descriptions should be derived from: -1. Comments in workflow files -2. Variable names (e.g., `CDK_VPC_CIDR` → "CIDR block for VPC") -3. Usage context in CDK stacks -4. AWS resource documentation (via MCP tools) - -**Description Templates**: -- `AWS_REGION`: "AWS region for resource deployment" -- `CDK_PROJECT_PREFIX`: "Prefix for all resource names" -- `CDK_*_CPU`: "CPU units for [service] ECS task" -- `CDK_*_MEMORY`: "Memory (MB) for [service] ECS task" -- `CDK_*_ENABLED`: "Enable/disable [feature]" -- `*_API_KEY`: "API key for [service] integration" - -## Data Models - -### Configuration Value Lifecycle - -``` -WorkflowConfig (raw extraction) - ↓ -TracedConfig (with defaults and CDK usage) - ↓ -AnalyzedConfig (with requirement status) - ↓ -DocumentationEntry (formatted for output) -``` - -### Complete Data Model - -```typescript -interface DocumentationEntry { - name: string; - type: 'Variable' | 'Secret'; - required: 'Yes' | 'No'; - default: string; // Formatted for display, "None" if missing - description: string; -} - -interface StackDocumentation { - stackName: string; - entries: DocumentationEntry[]; -} - -interface CompleteDocumentation { - stacks: StackDocumentation[]; -} -``` - -## Correctness Properties - -*A property is a characteristic or behavior that should hold true across all valid executions of a system—essentially, a formal statement about what the system should do. Properties serve as the bridge between human-readable specifications and machine-verifiable correctness guarantees.* - -### Property 1: File Creation -*For any* execution of the documentation generator, the output file `.github/README-ACTIONS.md` should exist after completion. -**Validates: Requirements 1.1** - -### Property 2: Complete Variable Extraction -*For any* workflow file containing variables referenced via `vars.*` syntax, all such variables should be extracted and included in the documentation. -**Validates: Requirements 2.1** - -### Property 3: Complete Secret Extraction -*For any* workflow file containing secrets referenced via `secrets.*` syntax, all such secrets should be extracted and included in the documentation. -**Validates: Requirements 2.2** - -### Property 4: Name Preservation -*For any* configuration value extracted from a workflow, the name in the documentation should exactly match the name in the workflow file. -**Validates: Requirements 2.3** - -### Property 5: Type Classification -*For any* configuration value, if it uses `vars.*` syntax it should be classified as "Variable", and if it uses `secrets.*` syntax it should be classified as "Secret". -**Validates: Requirements 2.4** - -### Property 6: Requirement Classification Consistency -*For any* configuration value with a default value in any location (workflow, load-env.sh, config.ts, cdk.context.json), it should be marked as "Optional" in the documentation. -**Validates: Requirements 3.3** - -### Property 7: Default Value Detection -*For any* configuration value with a default specified in workflow YAML, load-env.sh, config.ts, or cdk.context.json, that default value should be documented. -**Validates: Requirements 4.2, 4.3, 4.4, 4.5** - -### Property 8: Format Consistency -*For any* two stack subsections in the generated documentation, they should use the same format structure (both tables or both lists with identical field ordering). -**Validates: Requirements 6.2** - -### Property 9: Description Presence -*For any* configuration value in the documentation, there should be a non-empty description field. -**Validates: Requirements 5.1** - -### Property 10: Description Conciseness -*For any* description in the documentation, it should be 150 characters or less. -**Validates: Requirements 5.3** - -### Property 11: Scope Exclusion -*For any* generated documentation, it should not contain workflow job names, step names, or deployment procedure instructions. -**Validates: Requirements 12.1, 12.2, 12.3, 12.4** - -## Error Handling - -### Workflow Parsing Errors - -**Error**: Invalid YAML syntax in workflow file -**Handling**: Log error with file name and line number, skip that workflow, continue with others - -**Error**: Workflow file not found -**Handling**: Log warning, skip that workflow, continue with others - -**Error**: Unexpected workflow structure (missing expected keys) -**Handling**: Log warning, extract what's possible, continue - -### Configuration Tracing Errors - -**Error**: Cannot parse load-env.sh (syntax error) -**Handling**: Log error, continue without shell script defaults, rely on other sources - -**Error**: Cannot parse config.ts (TypeScript syntax error) -**Handling**: Log error, continue without TypeScript defaults, rely on other sources - -**Error**: Cannot parse cdk.context.json (invalid JSON) -**Handling**: Log error, continue without JSON defaults, rely on other sources - -**Error**: Configuration value not found in any default source -**Handling**: Mark as "None" for default value, continue - -### Requirement Analysis Errors - -**Error**: Cannot determine if value is required (ambiguous usage) -**Handling**: Default to marking as "Required" (safer choice), log warning for manual review - -**Error**: AWS MCP tool unavailable or returns error -**Handling**: Fall back to heuristic analysis (check for `?` in TypeScript, conditional usage), log warning - -### Documentation Generation Errors - -**Error**: Cannot write to output file (permissions) -**Handling**: Throw error with clear message about file permissions - -**Error**: No configuration values found for a stack -**Handling**: Include stack section with message "No configuration required" or "Configuration inherited from Infrastructure Stack" - -## Testing Strategy - -### Unit Tests - -**Workflow Parser Tests**: -- Test extraction of variables from `env:` blocks at different levels (workflow, job, step) -- Test extraction of secrets from `env:` blocks -- Test handling of variables in conditional expressions -- Test deduplication of repeated variable references -- Test parsing of all 5 actual workflow files - -**Configuration Tracer Tests**: -- Test extraction of defaults from load-env.sh export statements -- Test extraction of defaults from config.ts assignments -- Test extraction of defaults from cdk.context.json -- Test handling of missing default sources -- Test tracing of specific known variables (e.g., `CDK_AWS_REGION`) - -**Requirement Analyzer Tests**: -- Test classification of values with defaults as Optional -- Test classification of values without defaults as Required -- Test handling of optional TypeScript properties (`?`) -- Test handling of conditional usage patterns -- Test specific known required values (e.g., `CDK_AWS_ACCOUNT`) - -**Documentation Generator Tests**: -- Test markdown table generation -- Test sorting of entries alphabetically -- Test formatting of default values -- Test generation of all 5 stack sections -- Test handling of empty configuration sets - -### Property-Based Tests - -Each property test should run a minimum of 100 iterations and be tagged with the format: -**Feature: github-actions-documentation, Property {number}: {property_text}** - -**Property 1 Test**: Generate documentation, verify file exists at expected path -**Property 2 Test**: Create workflow with random variables, verify all extracted -**Property 3 Test**: Create workflow with random secrets, verify all extracted -**Property 4 Test**: Create workflow with specific names, verify exact match in output -**Property 5 Test**: Create workflow with mix of vars/secrets, verify correct classification -**Property 6 Test**: Create config with random defaults, verify all marked Optional -**Property 7 Test**: Create config with defaults in random locations, verify all documented -**Property 8 Test**: Generate documentation, verify all sections use same format -**Property 9 Test**: Generate documentation, verify all entries have descriptions -**Property 10 Test**: Generate documentation, verify all descriptions under 150 chars -**Property 11 Test**: Generate documentation, verify no workflow/deployment details present - -### Integration Tests - -**End-to-End Test**: -1. Run documentation generator on actual project workflows -2. Verify output file exists and is valid markdown -3. Verify all 5 stacks are documented -4. Verify known required variables are marked Required -5. Verify known optional variables are marked Optional -6. Verify known defaults are documented correctly -7. Manually review a sample of descriptions for accuracy - -**Regression Test**: -1. Keep a snapshot of generated documentation -2. After code changes, regenerate and compare -3. Flag any unexpected changes for review - -## Implementation Notes - -### Technology Choices - -**Language**: TypeScript (matches infrastructure code, good YAML/JSON support) - -**Libraries**: -- `js-yaml`: YAML parsing for workflow files -- `@typescript-eslint/parser`: TypeScript AST parsing for config.ts -- `glob`: File pattern matching for finding workflows - -**Execution**: -- Can be run as a standalone script: `npm run generate-docs` -- Can be integrated into CI to verify documentation is up-to-date -- Can be run manually by developers when adding new configuration - -### File Locations - -**Input Files**: -- `.github/workflows/infrastructure.yml` -- `.github/workflows/app-api.yml` -- `.github/workflows/inference-api.yml` -- `.github/workflows/frontend.yml` -- `.github/workflows/gateway.yml` -- `scripts/common/load-env.sh` -- `infrastructure/lib/config.ts` -- `infrastructure/cdk.context.json` - -**Output File**: -- `.github/README-ACTIONS.md` - -### Maintenance - -**When to Update**: -- When adding new GitHub Variables or Secrets to workflows -- When changing default values in config files -- When adding new workflows -- When changing requirement status of existing configuration - -**Verification**: -- Run `npm run generate-docs` after configuration changes -- Review diff to ensure changes are expected -- Commit updated documentation with configuration changes - -### Future Enhancements - -**Potential Additions** (out of scope for initial implementation): -- Generate environment-specific documentation (dev vs prod) -- Include example values for each configuration -- Add links to AWS documentation for AWS-specific config -- Generate JSON schema for validation -- Create interactive web version of documentation -- Add configuration validation script that checks GitHub settings against documentation diff --git a/.kiro/specs/github-actions-documentation/requirements.md b/.kiro/specs/github-actions-documentation/requirements.md deleted file mode 100644 index f88165ef..00000000 --- a/.kiro/specs/github-actions-documentation/requirements.md +++ /dev/null @@ -1,162 +0,0 @@ -# Requirements Document - -## Introduction - -This document specifies the requirements for creating comprehensive documentation of GitHub Actions configuration for the AgentCore Public Stack project. The documentation will help developers understand what GitHub Variables and Secrets are required for each of the 5 stack deployment workflows. - -## Glossary - -- **GitHub_Variables**: Non-sensitive configuration values stored in GitHub repository settings, accessed via `vars.*` in workflows -- **GitHub_Secrets**: Sensitive configuration values stored encrypted in GitHub repository settings, accessed via `secrets.*` in workflows -- **Workflow**: A GitHub Actions YAML file that defines CI/CD automation for a specific stack -- **Stack**: A deployable unit of infrastructure (Infrastructure, App API, Inference API, Frontend, or Gateway) -- **Documentation_System**: The README file that will contain the configuration reference - -## Requirements - -### Requirement 1: Document Structure - -**User Story:** As a developer, I want a well-organized documentation structure, so that I can quickly find configuration information for any stack. - -#### Acceptance Criteria - -1. THE Documentation_System SHALL create a file at `.github/README-ACTIONS.md` -2. THE Documentation_System SHALL include exactly one section titled "GitHub Variables and Secrets" -3. WITHIN the "GitHub Variables and Secrets" section, THE Documentation_System SHALL create exactly 5 subsections, one for each workflow -4. THE Documentation_System SHALL name subsections as: "Infrastructure Stack", "App API Stack", "Inference API Stack", "Frontend Stack", and "Gateway Stack" -5. THE Documentation_System SHALL use a consistent format across all subsections - -### Requirement 2: Variable and Secret Extraction - -**User Story:** As a developer, I want complete information about all configuration values, so that I can properly configure GitHub Actions for deployment. - -#### Acceptance Criteria - -1. FOR EACH workflow file, THE Documentation_System SHALL extract all variables referenced via `vars.*` syntax -2. FOR EACH workflow file, THE Documentation_System SHALL extract all secrets referenced via `secrets.*` syntax -3. THE Documentation_System SHALL preserve the exact name as it appears in the workflow (e.g., `AWS_REGION`, `CDK_AWS_ACCOUNT`) -4. THE Documentation_System SHALL identify the type of each configuration value (Variable or Secret) -5. THE Documentation_System SHALL analyze all job steps and environment blocks to find all configuration references - -### Requirement 3: Requirement Status Classification - -**User Story:** As a developer, I want to know which configuration values are required versus optional, so that I can prioritize my setup work and know what I must provide. - -#### Acceptance Criteria - -1. FOR EACH configuration value, THE Documentation_System SHALL classify it as either "Required" or "Optional" -2. WHEN a configuration value has no default value AND the downstream resource (in CDK stack or script) requires that value, THE Documentation_System SHALL mark it as "Required" -3. WHEN a configuration value has a default value OR the downstream resource can function without it, THE Documentation_System SHALL mark it as "Optional" -4. THE Documentation_System SHALL use AWS MCP tools to check AWS resource documentation for required parameters when determining requirement status -5. THE Documentation_System SHALL trace configuration values from workflow through scripts to CDK stacks to determine if the final resource requires the value -6. THE Documentation_System SHALL clearly indicate the Required/Optional status in the documentation format - -### Requirement 4: Default Value Documentation - -**User Story:** As a developer, I want to see default values for configuration items, so that I understand what happens when I don't provide a value. - -#### Acceptance Criteria - -1. FOR EACH configuration value, THE Documentation_System SHALL identify if a default value exists -2. WHEN a default value is specified in the workflow YAML, THE Documentation_System SHALL document that default value -3. WHEN a default value is specified in `scripts/common/load-env.sh`, THE Documentation_System SHALL document that default value -4. WHEN a default value is specified in `infrastructure/lib/config.ts`, THE Documentation_System SHALL document that default value -5. WHEN a default value is specified in `infrastructure/cdk.context.json`, THE Documentation_System SHALL document that default value -6. WHEN no default value exists in any of these locations, THE Documentation_System SHALL indicate "None" or leave the default field empty -7. THE Documentation_System SHALL display default values in a clear, readable format - -### Requirement 5: Purpose Description - -**User Story:** As a developer, I want to understand what each configuration value does, so that I can set appropriate values for my environment. - -#### Acceptance Criteria - -1. FOR EACH configuration value, THE Documentation_System SHALL provide a short description of its purpose -2. THE Description SHALL explain what the configuration value controls or affects -3. THE Description SHALL be concise (typically one sentence) -4. THE Description SHALL use clear, non-technical language where possible -5. WHEN a configuration value affects multiple resources, THE Description SHALL mention the primary use case - -### Requirement 6: Consistent Formatting - -**User Story:** As a developer, I want consistent formatting across all stack sections, so that I can quickly scan and compare configurations. - -#### Acceptance Criteria - -1. THE Documentation_System SHALL use either a table format or structured list format for all configuration entries -2. THE Format SHALL be identical across all 5 stack subsections -3. WHEN using table format, THE Documentation_System SHALL include columns for: Name, Type, Required/Optional, Default, and Description -4. WHEN using list format, THE Documentation_System SHALL include all the same information fields in a consistent order -5. THE Documentation_System SHALL use markdown formatting for readability - -### Requirement 7: Infrastructure Stack Configuration - -**User Story:** As a developer, I want complete documentation of Infrastructure Stack configuration, so that I can deploy the foundation layer. - -#### Acceptance Criteria - -1. THE Documentation_System SHALL document all variables from `infrastructure.yml` workflow -2. THE Documentation_System SHALL document all secrets from `infrastructure.yml` workflow -3. THE Documentation_System SHALL include configuration values used in synth, test, and deploy jobs -4. THE Documentation_System SHALL identify VPC, networking, and ALB-related configuration -5. THE Documentation_System SHALL document authentication-related configuration (AWS credentials, role ARNs) - -### Requirement 8: App API Stack Configuration - -**User Story:** As a developer, I want complete documentation of App API Stack configuration, so that I can deploy the application backend service. - -#### Acceptance Criteria - -1. THE Documentation_System SHALL document all variables from `app-api.yml` workflow -2. THE Documentation_System SHALL document all secrets from `app-api.yml` workflow -3. THE Documentation_System SHALL include Docker image configuration -4. THE Documentation_System SHALL include ECS task configuration (CPU, memory, desired count) -5. THE Documentation_System SHALL include authentication configuration (Entra ID client, tenant, redirect URI) - -### Requirement 9: Inference API Stack Configuration - -**User Story:** As a developer, I want complete documentation of Inference API Stack configuration, so that I can deploy the Bedrock AgentCore Runtime. - -#### Acceptance Criteria - -1. THE Documentation_System SHALL document all variables from `inference-api.yml` workflow -2. THE Documentation_System SHALL document all secrets from `inference-api.yml` workflow -3. THE Documentation_System SHALL include runtime environment configuration (log level, directories, URLs) -4. THE Documentation_System SHALL include API key configuration (Tavily, Nova Act) -5. THE Documentation_System SHALL include GPU and resource configuration options - -### Requirement 10: Frontend Stack Configuration - -**User Story:** As a developer, I want complete documentation of Frontend Stack configuration, so that I can deploy the Angular application. - -#### Acceptance Criteria - -1. THE Documentation_System SHALL document all variables from `frontend.yml` workflow -2. THE Documentation_System SHALL document all secrets from `frontend.yml` workflow -3. THE Documentation_System SHALL include CloudFront configuration (domain, price class, Route53) -4. THE Documentation_System SHALL include S3 bucket configuration -5. THE Documentation_System SHALL include certificate configuration for HTTPS - -### Requirement 11: Gateway Stack Configuration - -**User Story:** As a developer, I want complete documentation of Gateway Stack configuration, so that I can deploy the Bedrock AgentCore Gateway and Lambda tools. - -#### Acceptance Criteria - -1. THE Documentation_System SHALL document all variables from `gateway.yml` workflow -2. THE Documentation_System SHALL document all secrets from `gateway.yml` workflow -3. THE Documentation_System SHALL include API Gateway configuration (type, throttling, WAF) -4. THE Documentation_System SHALL include Lambda function configuration -5. THE Documentation_System SHALL include logging configuration - -### Requirement 12: Scope Limitation - -**User Story:** As a developer, I want focused documentation on configuration only, so that I'm not overwhelmed with unnecessary information. - -#### Acceptance Criteria - -1. THE Documentation_System SHALL NOT document workflow architecture or job structure -2. THE Documentation_System SHALL NOT document deployment processes or procedures -3. THE Documentation_System SHALL NOT document script implementations -4. THE Documentation_System SHALL NOT document CDK stack details -5. THE Documentation_System SHALL focus exclusively on GitHub Variables and Secrets configuration diff --git a/.kiro/specs/github-actions-documentation/tasks.md b/.kiro/specs/github-actions-documentation/tasks.md deleted file mode 100644 index 4439baf6..00000000 --- a/.kiro/specs/github-actions-documentation/tasks.md +++ /dev/null @@ -1,132 +0,0 @@ -# Implementation Plan: GitHub Actions Configuration Documentation - -## Overview - -This plan creates comprehensive reference documentation for GitHub Actions configuration by analyzing the 5 workflow files and related configuration sources. The LLM will directly analyze workflows, trace configuration through scripts and CDK stacks, and write the documentation at `.github/README-ACTIONS.md`. No code generation is required - this is a pure documentation task broken into manageable analysis chunks. - -## Tasks - -- [x] 1. Create document structure and introduction - - Create `.github/README-ACTIONS.md` - - Add document title: "GitHub Actions Configuration" - - Add introduction explaining the purpose of this document - - Create main section: "## GitHub Variables and Secrets" - - Add brief explanation of Variables vs Secrets - - _Requirements: 1.1, 1.2_ - - _Files to analyze: None (just structure)_ - -- [x] 2. Document Infrastructure Stack configuration - - [x] 2.1 Analyze Infrastructure Stack workflow - - Read `.github/workflows/infrastructure.yml` - - Read `scripts/common/load-env.sh` for defaults - - Read `infrastructure/lib/config.ts` for defaults and usage - - Read `infrastructure/cdk.context.json` for defaults - - Extract all `vars.*` and `secrets.*` references - - Determine which are Required vs Optional based on defaults and CDK usage - - _Requirements: 2.1, 2.2, 2.3, 2.4, 2.5, 3.1, 3.2, 3.3, 4.1, 4.2, 4.3, 4.4, 4.5, 7.1, 7.2, 7.3, 7.4, 7.5_ - - - [x] 2.2 Write Infrastructure Stack documentation section - - Create subsection: "### Infrastructure Stack" - - Create markdown table with columns: Name, Type, Required, Default, Description - - Document all variables and secrets found in analysis - - Sort entries alphabetically by name - - Write concise descriptions (≤150 chars) for each entry - - _Requirements: 5.1, 5.2, 5.3, 6.1, 6.2, 6.3, 6.5_ - -- [x] 3. Document App API Stack configuration - - [x] 3.1 Analyze App API Stack workflow - - Read `.github/workflows/app-api.yml` - - Read `scripts/common/load-env.sh` for defaults - - Read `infrastructure/lib/config.ts` for defaults and usage - - Read `infrastructure/lib/app-api-stack.ts` for usage patterns - - Read `infrastructure/cdk.context.json` for defaults - - Extract all `vars.*` and `secrets.*` references - - Determine which are Required vs Optional based on defaults and CDK usage - - _Requirements: 2.1, 2.2, 2.3, 2.4, 2.5, 3.1, 3.2, 3.3, 4.1, 4.2, 4.3, 4.4, 4.5, 8.1, 8.2, 8.3, 8.4, 8.5_ - - - [x] 3.2 Write App API Stack documentation section - - Create subsection: "### App API Stack" - - Create markdown table with columns: Name, Type, Required, Default, Description - - Document all variables and secrets found in analysis - - Sort entries alphabetically by name - - Write concise descriptions (≤150 chars) for each entry - - Ensure format matches Infrastructure Stack section - - _Requirements: 5.1, 5.2, 5.3, 6.1, 6.2, 6.3, 6.5_ - -- [x] 4. Document Inference API Stack configuration - - [x] 4.1 Analyze Inference API Stack workflow - - Read `.github/workflows/inference-api.yml` - - Read `scripts/common/load-env.sh` for defaults - - Read `infrastructure/lib/config.ts` for defaults and usage - - Read `infrastructure/lib/inference-api-stack.ts` for usage patterns - - Read `infrastructure/cdk.context.json` for defaults - - Extract all `vars.*` and `secrets.*` references (including ENV_* runtime variables) - - Determine which are Required vs Optional based on defaults and CDK usage - - _Requirements: 2.1, 2.2, 2.3, 2.4, 2.5, 3.1, 3.2, 3.3, 4.1, 4.2, 4.3, 4.4, 4.5, 9.1, 9.2, 9.3, 9.4, 9.5_ - - - [x] 4.2 Write Inference API Stack documentation section - - Create subsection: "### Inference API Stack" - - Create markdown table with columns: Name, Type, Required, Default, Description - - Document all variables and secrets found in analysis - - Sort entries alphabetically by name - - Write concise descriptions (≤150 chars) for each entry - - Ensure format matches previous sections - - _Requirements: 5.1, 5.2, 5.3, 6.1, 6.2, 6.3, 6.5_ - -- [x] 5. Document Frontend Stack configuration - - [x] 5.1 Analyze Frontend Stack workflow - - Read `.github/workflows/frontend.yml` - - Read `scripts/common/load-env.sh` for defaults - - Read `infrastructure/lib/config.ts` for defaults and usage - - Read `infrastructure/lib/frontend-stack.ts` for usage patterns - - Read `infrastructure/cdk.context.json` for defaults - - Extract all `vars.*` and `secrets.*` references - - Determine which are Required vs Optional based on defaults and CDK usage - - _Requirements: 2.1, 2.2, 2.3, 2.4, 2.5, 3.1, 3.2, 3.3, 4.1, 4.2, 4.3, 4.4, 4.5, 10.1, 10.2, 10.3, 10.4, 10.5_ - - - [x] 5.2 Write Frontend Stack documentation section - - Create subsection: "### Frontend Stack" - - Create markdown table with columns: Name, Type, Required, Default, Description - - Document all variables and secrets found in analysis - - Sort entries alphabetically by name - - Write concise descriptions (≤150 chars) for each entry - - Ensure format matches previous sections - - _Requirements: 5.1, 5.2, 5.3, 6.1, 6.2, 6.3, 6.5_ - -- [x] 6. Document Gateway Stack configuration - - [x] 6.1 Analyze Gateway Stack workflow - - Read `.github/workflows/gateway.yml` - - Read `scripts/common/load-env.sh` for defaults - - Read `infrastructure/lib/config.ts` for defaults and usage - - Read `infrastructure/lib/gateway-stack.ts` for usage patterns - - Read `infrastructure/cdk.context.json` for defaults - - Extract all `vars.*` and `secrets.*` references - - Determine which are Required vs Optional based on defaults and CDK usage - - _Requirements: 2.1, 2.2, 2.3, 2.4, 2.5, 3.1, 3.2, 3.3, 4.1, 4.2, 4.3, 4.4, 4.5, 11.1, 11.2, 11.3, 11.4, 11.5_ - - - [x] 6.2 Write Gateway Stack documentation section - - Create subsection: "### Gateway Stack" - - Create markdown table with columns: Name, Type, Required, Default, Description - - Document all variables and secrets found in analysis - - Sort entries alphabetically by name - - Write concise descriptions (≤150 chars) for each entry - - Ensure format matches previous sections - - _Requirements: 5.1, 5.2, 5.3, 6.1, 6.2, 6.3, 6.5_ - -- [x] 7. Review and finalize documentation - - Review entire document for consistency - - Verify all 5 stacks are documented with identical table format - - Check that all descriptions are concise and clear - - Verify Required/Optional classifications are accurate - - Verify default values are correctly documented - - Ensure no workflow architecture or deployment details are included (scope limitation) - - _Requirements: 6.2, 12.1, 12.2, 12.3, 12.4, 12.5_ - -## Notes - -- Each task involves reading and analyzing specific files to extract configuration information -- No code generation is required - this is pure documentation work -- The LLM will directly analyze workflows and write the markdown documentation -- Tasks are broken down by stack to make the analysis manageable -- Each stack analysis follows the same pattern: analyze workflow → trace defaults → determine requirements → write documentation -- The final document will be a single markdown file at `.github/README-ACTIONS.md` diff --git a/.kiro/specs/github-actions-job-summaries/.config.kiro b/.kiro/specs/github-actions-job-summaries/.config.kiro deleted file mode 100644 index a175a341..00000000 --- a/.kiro/specs/github-actions-job-summaries/.config.kiro +++ /dev/null @@ -1 +0,0 @@ -{"specId": "0c4a9b5c-8748-43ae-a5f2-636d49862ad4", "workflowType": "requirements-first", "specType": "feature"} diff --git a/.kiro/specs/github-actions-job-summaries/design.md b/.kiro/specs/github-actions-job-summaries/design.md deleted file mode 100644 index 7be5ba71..00000000 --- a/.kiro/specs/github-actions-job-summaries/design.md +++ /dev/null @@ -1,249 +0,0 @@ -# Design Document: GitHub Actions Job Summaries - -## Overview - -This design adds rich, visually polished GitHub Actions job summaries (`$GITHUB_STEP_SUMMARY`) across all 10 CI/CD workflows in the AgentCore Public Stack monorepo. Currently, summaries exist only on final deploy jobs and consist of basic metadata plus raw JSON dumps. The nightly and version-check workflows produce no summaries at all. - -The approach introduces a shared summary generator script library in `scripts/common/` that each workflow calls to produce standardized, information-dense markdown. Every job type (build, test, deploy, teardown) gets a tailored summary with consistent headers, timing data, collapsible detail sections, and failure diagnostics. - -### Design Decisions - -1. **Single shared library vs. per-stack scripts**: A single `scripts/common/summary.sh` file with composable functions keeps summaries consistent and avoids duplication across 10 workflows. Stack-specific data is passed as parameters or environment variables. - -2. **Shell functions over separate scripts per section**: Rather than one script per summary type, we use a library of bash functions (`write_header`, `write_build_summary`, `write_test_summary`, etc.) that jobs source and call. This keeps the YAML thin while allowing each job to compose exactly the sections it needs. - -3. **Timing via `$SECONDS` and step outputs**: GitHub Actions doesn't expose job-level timing natively. We capture `$SECONDS` at the start and end of key phases and pass durations as parameters to the summary functions. This avoids external dependencies. - -4. **CDK outputs parsed with `jq`**: All workflows already have `jq` available. We parse CDK output JSON files into markdown tables instead of dumping raw JSON, using the existing `cdk-outputs-*.json` artifact files. - -5. **`if: always()` on all summary steps**: Summary generation steps run regardless of job outcome, ensuring failed runs still produce diagnostic output. - -## Architecture - -```mermaid -graph TD - subgraph "scripts/common/" - SUM[summary.sh
Shared function library] - end - - subgraph "Workflow Jobs" - BJ[Build Jobs] -->|source + call| SUM - TJ[Test Jobs] -->|source + call| SUM - DJ[Deploy Jobs] -->|source + call| SUM - NJ[Nightly Aggregator] -->|source + call| SUM - VJ[Version Check] -->|source + call| SUM - end - - SUM -->|writes to| GS[$GITHUB_STEP_SUMMARY] - - subgraph "Data Sources" - VER[VERSION file] - GIT[git metadata] - CDK[cdk-outputs-*.json] - TEST[test output / coverage] - DOCKER[docker inspect] - CACHE[cache hit/miss] - end - - VER --> SUM - GIT --> SUM - CDK --> SUM - TEST --> SUM - DOCKER --> SUM - CACHE --> SUM -``` - -### Summary Generation Flow - -Each workflow job follows this pattern: - -1. **Source the library**: `source scripts/common/summary.sh` -2. **Capture timing**: Record `$SECONDS` at phase boundaries -3. **Call functions**: `write_header`, then job-specific functions (`write_build_summary`, `write_deploy_summary`, etc.) -4. **Append to `$GITHUB_STEP_SUMMARY`**: Each function appends markdown to the summary file - -### Workflow Integration Points - -| Workflow | Jobs Getting Summaries | Summary Type | -|---|---|---| -| `infrastructure.yml` | build, synth, test, deploy | Header + Deploy (Infrastructure) | -| `app-api.yml` | build-docker, test-python, test-docker, test-cdk, deploy, create-git-tag | Header + Build + Test + Deploy (ECS) | -| `inference-api.yml` | build-docker, test-python, test-docker, test-cdk, deploy | Header + Build + Test + Deploy (AgentCore) | -| `frontend.yml` | build-frontend, test-frontend, test-cdk, deploy-assets | Header + Build + Test + Deploy (CloudFront) | -| `gateway.yml` | build-cdk, test-cdk, deploy-stack, test-gateway | Header + Deploy (Lambda) | -| `rag-ingestion.yml` | build-docker, test-docker, test-cdk, deploy | Header + Build + Test + Deploy (ECS) | -| `sagemaker-fine-tuning.yml` | build, synth, test, deploy | Header + Deploy (SageMaker) | -| `bootstrap-data-seeding.yml` | seed | Header + Deploy (Bootstrap) | -| `nightly.yml` | all jobs + final aggregator | Header + Status Table + Coverage + Smoke + Teardown | -| `version-check.yml` | version-check | Header + Checklist + Remediation | - -## Components and Interfaces - -### `scripts/common/summary.sh` — Shared Function Library - -This is the core component. It exports bash functions that generate markdown sections. - -#### Function Signatures - -```bash -# Core header — called by every job -# Params: workflow_name, status (success|failure|partial), stack_name -# Reads from env: CDK_PROJECT_PREFIX, CDK_AWS_REGION, GITHUB_* vars -write_header() - -# Build summary for Docker workflows -# Params: image_tag, platform, image_size_bytes, ecr_uri, image_digest -# Optional env: CACHE_HIT_PYTHON, CACHE_HIT_NODE -write_build_summary() - -# Test summary for Python test jobs -# Params: total, passed, failed, skipped, duration_seconds -# Optional: coverage_percent, failing_test_names (newline-separated, max 10) -write_test_summary_python() - -# Test summary for frontend test jobs -# Params: total_suites, total_tests, passed, failed, duration_seconds -# Optional: coverage_percent -write_test_summary_frontend() - -# Test summary for CDK validation -# Params: result (pass|fail), resource_count -write_test_summary_cdk() - -# Test summary for Docker image tests -# Params: health_check_result (pass|fail), startup_time_seconds -write_test_summary_docker() - -# Deploy summary — dispatches to stack-specific formatting -# Params: stack_type (infrastructure|app-api|inference-api|frontend|gateway|rag-ingestion|sagemaker|bootstrap) -# Reads: cdk-outputs-*.json or env vars for stack-specific data -write_deploy_summary() - -# Timing footer -# Params: phase_timings (associative array or key=value pairs) -write_timing_footer() - -# Failure summary -# Params: step_name, exit_code, log_tail (last 20 lines) -write_failure_summary() - -# Collapsible section wrapper -# Params: summary_label, content -write_collapsible() - -# CDK outputs as formatted table (replaces raw JSON dump) -# Params: outputs_json_file -write_cdk_outputs_table() - -# Nightly aggregator — status table across all jobs -# Params: job_results (array of name|status|duration tuples) -write_nightly_summary() - -# Version check summary -# Params: version_bumped (pass|fail), manifests_synced (pass|fail), lockfiles_synced (pass|fail) -# Optional: old_version, new_version -write_version_check_summary() -``` - -#### Environment Variables Contract - -The summary functions read these from the GitHub Actions environment: - -| Variable | Source | Used By | -|---|---|---| -| `CDK_PROJECT_PREFIX` | GitHub vars | `write_header` | -| `CDK_AWS_REGION` | GitHub vars | `write_header` | -| `GITHUB_WORKFLOW` | GitHub built-in | `write_header` | -| `GITHUB_SHA` | GitHub built-in | `write_header` | -| `GITHUB_REF_NAME` | GitHub built-in | `write_header` | -| `GITHUB_EVENT_NAME` | GitHub built-in | `write_header` | -| `GITHUB_ACTOR` | GitHub built-in | `write_header` | -| `GITHUB_RUN_ID` | GitHub built-in | `write_header` | -| `IMAGE_TAG` | Job output | `write_build_summary` | - -### Workflow YAML Changes - -Each workflow's summary steps change from inline markdown to a script call: - -```yaml -# Before (inline, deploy-only) -- name: Deployment summary - if: success() - run: | - echo "## App API Deployment Successful ✅" >> $GITHUB_STEP_SUMMARY - # ... 20+ lines of inline markdown - -# After (script-based, every job) -- name: Generate summary - if: always() - run: | - source scripts/common/summary.sh - write_header "App API" "success" "AppApiStack" - write_deploy_summary "app-api" - write_timing_footer "install=${INSTALL_DURATION}" "build=${BUILD_DURATION}" "deploy=${DEPLOY_DURATION}" -``` - -## Data Models - -### Summary Section Schema - -Each summary function produces a markdown section. The logical structure: - -``` -┌─────────────────────────────────────────────┐ -│ HEADER │ -│ ┌─────────────────────────────────────────┐ │ -│ │ Status emoji + Workflow name │ │ -│ │ Environment | Region | Project Prefix │ │ -│ │ Version | Commit SHA | Branch | Message │ │ -│ │ Trigger type | Actor │ │ -│ │ [workflow_dispatch inputs if present] │ │ -│ └─────────────────────────────────────────┘ │ -├─────────────────────────────────────────────┤ -│ JOB-SPECIFIC CONTENT │ -│ (Build / Test / Deploy details) │ -│ Tables, metrics, key-value pairs │ -├─────────────────────────────────────────────┤ -│ CDK OUTPUTS (collapsible) │ -│
Stack Outputs │ -│ Formatted markdown table │ -│
│ -├─────────────────────────────────────────────┤ -│ FAILURE DETAILS (if applicable, collapsible) │ -│
Error Details │ -│ Step name, exit code, log tail │ -│
│ -├─────────────────────────────────────────────┤ -│ TIMING FOOTER │ -│ Phase durations + total wall-clock time │ -└─────────────────────────────────────────────┘ -``` - -### CDK Outputs Table Format - -Instead of raw JSON, CDK outputs are rendered as: - -| Output Key | Value | -|---|---| -| EcsClusterName | `dev-agentcore-cluster` | -| EcsServiceName | `dev-agentcore-app-api` | -| ... | ... | - -### Nightly Status Table Format - -| Job | Status | Duration | -|---|---|---| -| Install Backend | ✅ Pass | 1m 23s | -| Test Backend | ✅ Pass | 3m 45s | -| Deploy Infrastructure | ✅ Pass | 5m 12s | -| ... | ... | ... | -| **Total** | **✅ All Passed** | **32m 15s** | - -### Version Check Checklist Format - -| Check | Status | Details | -|---|---|---| -| VERSION bumped | ✅ | `1.2.0` → `1.3.0` | -| Manifests in sync | ✅ | All 3 manifests match | -| Lockfiles in sync | ❌ | `frontend/ai.client/package-lock.json` out of sync | - diff --git a/.kiro/specs/github-actions-job-summaries/requirements.md b/.kiro/specs/github-actions-job-summaries/requirements.md deleted file mode 100644 index 203462b0..00000000 --- a/.kiro/specs/github-actions-job-summaries/requirements.md +++ /dev/null @@ -1,160 +0,0 @@ -# Requirements Document - -## Introduction - -This feature enhances the GitHub Actions Job Summaries (`$GITHUB_STEP_SUMMARY`) across all CI/CD workflows in the AgentCore Public Stack monorepo. Currently, summaries exist only on the final deploy jobs and are minimal — typically just environment, region, project prefix, and a raw JSON dump of CDK outputs. Several workflows and many intermediate jobs produce no summary at all. - -The goal is to make every workflow run produce a rich, visually polished, information-dense summary on the GitHub dashboard — covering build metadata, test results, deployment details, timing, version info, and links — so that developers get a spectacular at-a-glance view of what happened without digging through logs. - -### Current State Analysis - -| Workflow | Current Summary | Location | -|---|---|---| -| `infrastructure.yml` | Basic deploy details + raw JSON outputs | `deploy` job only | -| `rag-ingestion.yml` | Basic deploy details + image tag + raw JSON outputs | `deploy-infrastructure` job only | -| `inference-api.yml` | Basic deploy details + image tag + raw JSON outputs | `deploy-infrastructure` job only | -| `app-api.yml` | Basic deploy details + image tag + raw JSON outputs | `deploy-infrastructure` and `create-git-tag` jobs | -| `frontend.yml` | Basic deploy details + CloudFront note | `deploy-assets` job only | -| `gateway.yml` | Basic deploy details + resource list + raw JSON outputs | `deploy-stack` job only | -| `sagemaker-fine-tuning.yml` | Basic deploy details + resource list + raw JSON outputs | `deploy` job only | -| `bootstrap-data-seeding.yml` | Minimal 3-line summary | `seed` job only | -| `nightly.yml` | No summary at all | — | -| `version-check.yml` | No summary at all | — | - -### Gaps Identified - -1. No workflow-level summary that aggregates results across all jobs -2. No build metadata (Docker image size, build duration, cache hit/miss) -3. No test result summaries (pass/fail counts, coverage percentages) -4. No version information (VERSION file content, git SHA, previous version) -5. No timing information (job durations, total pipeline time) -6. No visual structure (no emojis for status, no tables, no collapsible sections) -7. No links to artifacts, ECR images, or CloudFormation stacks -8. Nightly workflow has zero summary despite being the most complex pipeline -9. Version-check workflow has no summary despite being a PR gate - -## Glossary - -- **Job_Summary**: The markdown content written to `$GITHUB_STEP_SUMMARY` in a GitHub Actions workflow step, rendered on the GitHub Actions run dashboard page -- **Summary_Generator_Script**: A shell script in `scripts/common/` that generates standardized Job_Summary markdown content for a given workflow -- **Workflow**: A GitHub Actions YAML file in `.github/workflows/` that defines a CI/CD pipeline -- **Stack**: A CDK-defined set of AWS resources deployed by a single workflow (e.g., AppApiStack, InferenceApiStack) -- **Deploy_Job**: The final job in a deployment workflow that runs `cdk deploy` and triggers service updates -- **Build_Job**: A job that compiles code or builds Docker images -- **Test_Job**: A job that runs unit tests, integration tests, or CDK validation -- **Nightly_Workflow**: The `nightly.yml` workflow that runs a full deploy-test-teardown cycle on a schedule -- **Version_Check_Workflow**: The `version-check.yml` workflow that validates VERSION file changes on PRs to main - -## Requirements - -### Requirement 1: Standardized Summary Header - -**User Story:** As a developer, I want every workflow summary to start with a consistent header showing the workflow name, status, and key metadata, so that I can immediately identify what ran and whether it succeeded. - -#### Acceptance Criteria - -1. THE Summary_Generator_Script SHALL produce a header section containing the workflow display name, a status emoji (✅ for success, ❌ for failure, ⚠️ for partial), the environment name, the AWS region, and the project prefix -2. THE Summary_Generator_Script SHALL include the application version from the VERSION file, the git commit SHA (short form), the branch name, and the commit message (first line) in the header section -3. THE Summary_Generator_Script SHALL include the workflow trigger type (push, pull_request, workflow_dispatch, schedule) in the header section -4. WHEN a workflow is triggered by workflow_dispatch, THE Summary_Generator_Script SHALL display the user-provided input parameters in the header section - -### Requirement 2: Build Job Summaries for Docker Workflows - -**User Story:** As a developer, I want build jobs to report Docker image metadata in the summary, so that I can verify the correct image was built and track image sizes over time. - -#### Acceptance Criteria - -1. WHEN a Docker image build completes successfully, THE Build_Job SHALL write to the Job_Summary the image tag, the target platform (e.g., linux/arm64), and the compressed image size in human-readable format -2. WHEN a Docker image is pushed to ECR, THE Build_Job SHALL write to the Job_Summary the full ECR repository URI and the image digest (SHA256) -3. WHEN dependency caching is used, THE Build_Job SHALL report whether the cache was a hit or miss for each cache key (Python packages, node_modules) - -### Requirement 3: Test Job Summaries - -**User Story:** As a developer, I want test jobs to report pass/fail counts and coverage in the summary, so that I can see test health without opening log files. - -#### Acceptance Criteria - -1. WHEN Python tests complete, THE Test_Job SHALL write to the Job_Summary the total number of tests, the number passed, the number failed, the number skipped, and the test duration -2. WHEN frontend tests complete, THE Test_Job SHALL write to the Job_Summary the total number of test suites, the number of tests passed, the number failed, and the test duration -3. WHEN CDK validation completes, THE Test_Job SHALL write to the Job_Summary the validation result (pass/fail) and the number of CloudFormation resources in the synthesized template -4. WHEN Docker image tests complete, THE Test_Job SHALL write to the Job_Summary the health check result and the container startup time -5. IF any test job fails, THEN THE Test_Job SHALL write to the Job_Summary a summary of the failure including the failing test names (up to 10) - -### Requirement 4: Deploy Job Summaries for All Stacks - -**User Story:** As a developer, I want deploy job summaries to show rich deployment details specific to each stack type, so that I can verify the deployment completed correctly and see what changed. - -#### Acceptance Criteria - -1. WHEN the Infrastructure stack deploys successfully, THE Deploy_Job SHALL write to the Job_Summary a resources table listing VPC ID, ALB ARN, ECS Cluster name, number of DynamoDB tables created, and number of S3 buckets created, extracted from the CDK outputs file -2. WHEN the App API stack deploys successfully, THE Deploy_Job SHALL write to the Job_Summary the ECS service name, the ECS cluster name, the task definition revision, the Docker image tag, and confirmation that force-new-deployment was triggered -3. WHEN the Inference API stack deploys successfully, THE Deploy_Job SHALL write to the Job_Summary the Docker image tag, the SSM parameter path that was updated, the target platform (linux/arm64), and the AgentCore Runtime update mechanism description -4. WHEN the Frontend stack deploys successfully, THE Deploy_Job SHALL write to the Job_Summary the S3 bucket name, the CloudFront distribution ID, whether cache invalidation was triggered, and the estimated propagation time -5. WHEN the Gateway stack deploys successfully, THE Deploy_Job SHALL write to the Job_Summary the number of Lambda functions deployed, the list of MCP tool names, and the API Gateway endpoint URL if available from CDK outputs -6. WHEN the RAG Ingestion stack deploys successfully, THE Deploy_Job SHALL write to the Job_Summary the Docker image tag, the target platform, and the ECS task definition details extracted from CDK outputs -7. WHEN the SageMaker Fine-Tuning stack deploys successfully, THE Deploy_Job SHALL write to the Job_Summary the list of DynamoDB tables, the S3 bucket name, and the SageMaker execution role ARN extracted from CDK outputs -8. WHEN the Bootstrap Data Seeding workflow completes, THE Deploy_Job SHALL write to the Job_Summary the auth provider ID that was seeded, the number of DynamoDB items written, and the tables that were seeded -9. THE Deploy_Job SHALL render CDK stack outputs in a formatted markdown table instead of a raw JSON code block - -### Requirement 5: Nightly Workflow Summary - -**User Story:** As a developer, I want the nightly workflow to produce a comprehensive summary of the entire deploy-test-teardown cycle, so that I can review nightly health at a glance each morning. - -#### Acceptance Criteria - -1. THE Nightly_Workflow SHALL produce a Job_Summary containing a status table with one row per job showing the job name, status (pass/fail/skip), and duration -2. WHEN backend tests complete in the nightly workflow, THE Nightly_Workflow SHALL include the backend test coverage percentage in the Job_Summary -3. WHEN frontend tests complete in the nightly workflow, THE Nightly_Workflow SHALL include the frontend test coverage percentage in the Job_Summary -4. WHEN the smoke test job completes, THE Nightly_Workflow SHALL include the smoke test results (endpoints tested, response codes) in the Job_Summary -5. WHEN the teardown job completes, THE Nightly_Workflow SHALL include confirmation of which stacks were destroyed in the Job_Summary -6. WHEN the AI coverage analysis job completes, THE Nightly_Workflow SHALL include a summary of coverage gaps identified in the Job_Summary - -### Requirement 6: Version Check Workflow Summary - -**User Story:** As a developer, I want the version-check workflow to produce a clear summary showing which checks passed and which failed, so that I can fix version issues quickly on PRs. - -#### Acceptance Criteria - -1. THE Version_Check_Workflow SHALL produce a Job_Summary containing a checklist table with rows for: VERSION file bumped, manifests in sync, and lockfiles in sync, each showing pass or fail status -2. WHEN the VERSION file has been bumped, THE Version_Check_Workflow SHALL display the old version (from main) and the new version (from the PR branch) in the Job_Summary -3. IF any version check fails, THEN THE Version_Check_Workflow SHALL include remediation instructions in the Job_Summary explaining the exact commands to run - -### Requirement 7: Pipeline Timing Information - -**User Story:** As a developer, I want to see how long each phase of the pipeline took, so that I can identify bottlenecks and track pipeline performance over time. - -#### Acceptance Criteria - -1. THE Summary_Generator_Script SHALL capture and display the start time and end time for each major phase (install, build, test, synth, deploy) in the Job_Summary -2. THE Summary_Generator_Script SHALL display the total workflow wall-clock duration in the Job_Summary footer - -### Requirement 8: Collapsible Detail Sections - -**User Story:** As a developer, I want verbose details (like full CDK outputs or test logs) to be in collapsible sections, so that the summary is scannable but I can drill into details when needed. - -#### Acceptance Criteria - -1. THE Summary_Generator_Script SHALL wrap CDK stack outputs JSON in a collapsible `
` HTML element with a descriptive `` label -2. THE Summary_Generator_Script SHALL wrap lists of more than 5 items (e.g., test failures, resource lists) in a collapsible `
` HTML element -3. THE Summary_Generator_Script SHALL keep the top-level summary content (header, status table, key metrics) always visible without requiring expansion - -### Requirement 9: Script-Based Summary Generation - -**User Story:** As a developer, I want summary generation logic to live in reusable shell scripts rather than inline YAML, so that summaries are consistent across workflows and maintainable. - -#### Acceptance Criteria - -1. THE Summary_Generator_Script SHALL be implemented as one or more shell scripts in the `scripts/common/` directory -2. THE Summary_Generator_Script SHALL accept parameters for stack name, environment, region, project prefix, and status to generate the appropriate summary content -3. THE Summary_Generator_Script SHALL be callable from any workflow YAML file with a single `bash` invocation -4. WHEN a new stack workflow is added, THE Summary_Generator_Script SHALL support generating a summary for the new stack without modifying the shared script, by accepting stack-specific data as parameters or environment variables - -### Requirement 10: Failure Summaries - -**User Story:** As a developer, I want failed workflow runs to still produce a useful summary showing what failed and where, so that I can diagnose issues without scrolling through logs. - -#### Acceptance Criteria - -1. WHEN a deploy job fails, THE Deploy_Job SHALL write to the Job_Summary the step that failed, the exit code, and the last 20 lines of relevant log output in a collapsible section -2. WHEN a build job fails, THE Build_Job SHALL write to the Job_Summary the build step that failed and the error message -3. THE Summary_Generator_Script SHALL use the `if: always()` condition on summary steps so that summaries are generated for both successful and failed runs diff --git a/.kiro/specs/github-actions-job-summaries/tasks.md b/.kiro/specs/github-actions-job-summaries/tasks.md deleted file mode 100644 index d5f246d7..00000000 --- a/.kiro/specs/github-actions-job-summaries/tasks.md +++ /dev/null @@ -1,200 +0,0 @@ -# Implementation Plan: GitHub Actions Job Summaries - -## Overview - -Implement a shared bash function library (`scripts/common/summary.sh`) and integrate it into all 10 CI/CD workflows to produce rich, standardized GitHub Actions job summaries. The approach is incremental: build the core library first, then integrate workflow-by-workflow, starting with the simplest cases and building toward the complex nightly aggregator. - -## Tasks - -- [x] 1. Create the shared summary generator library with core functions - - [x] 1.1 Create `scripts/common/summary.sh` with `write_header` function - - Implement `write_header` accepting `workflow_name`, `status` (success|failure|partial), and `stack_name` parameters - - Read `CDK_PROJECT_PREFIX`, `CDK_AWS_REGION`, `GITHUB_SHA`, `GITHUB_REF_NAME`, `GITHUB_EVENT_NAME`, `GITHUB_ACTOR`, `GITHUB_RUN_ID` from environment - - Read version from `VERSION` file, extract short commit SHA, first line of commit message - - Display status emoji (✅/❌/⚠️), environment, region, project prefix, version, branch, trigger type - - When `GITHUB_EVENT_NAME` is `workflow_dispatch`, display user-provided input parameters from `$GITHUB_EVENT_PATH` - - Append all output to `$GITHUB_STEP_SUMMARY` - - _Requirements: 1.1, 1.2, 1.3, 1.4_ - - - [x] 1.2 Add `write_collapsible` and `write_cdk_outputs_table` utility functions - - `write_collapsible` accepts `summary_label` and `content`, wraps in `
...` HTML - - `write_cdk_outputs_table` accepts a CDK outputs JSON file path, parses with `jq`, renders as a markdown table (Output Key | Value) - - Wrap output in a collapsible section with descriptive label - - _Requirements: 8.1, 8.3, 4.9_ - - - [x] 1.3 Add `write_timing_footer` function - - Accept key=value pairs for phase timings (e.g., `install=45` `build=120` `deploy=300`) - - Display each phase duration in human-readable format (Xm Ys) - - Display total workflow wall-clock duration using `$SECONDS` - - _Requirements: 7.1, 7.2_ - - - [x] 1.4 Add `write_failure_summary` function - - Accept `step_name`, `exit_code`, and `log_tail` (last 20 lines) parameters - - Render failure details inside a collapsible `
` section - - Include step name, exit code, and log output - - _Requirements: 10.1, 10.2, 10.3_ - - - [x] 1.5 Add `write_build_summary` function - - Accept `image_tag`, `platform`, `image_size_bytes`, `ecr_uri`, `image_digest` parameters - - Read optional `CACHE_HIT_PYTHON` and `CACHE_HIT_NODE` env vars for cache hit/miss reporting - - Display image metadata in a table: tag, platform, compressed size (human-readable), ECR URI, digest - - _Requirements: 2.1, 2.2, 2.3_ - - - [x] 1.6 Add test summary functions: `write_test_summary_python`, `write_test_summary_frontend`, `write_test_summary_cdk`, `write_test_summary_docker` - - `write_test_summary_python`: accept total, passed, failed, skipped, duration_seconds; optional coverage_percent, failing_test_names (newline-separated, max 10) - - `write_test_summary_frontend`: accept total_suites, total_tests, passed, failed, duration_seconds; optional coverage_percent - - `write_test_summary_cdk`: accept result (pass|fail), resource_count - - `write_test_summary_docker`: accept health_check_result (pass|fail), startup_time_seconds - - Wrap lists of more than 5 failing test names in a collapsible section - - _Requirements: 3.1, 3.2, 3.3, 3.4, 3.5, 8.2_ - - - [x] 1.7 Add `write_deploy_summary` function with stack-type dispatch - - Accept `stack_type` parameter to dispatch to stack-specific formatting - - Implement sub-formatters for each stack type: `infrastructure`, `app-api`, `inference-api`, `frontend`, `gateway`, `rag-ingestion`, `sagemaker`, `bootstrap` - - Each sub-formatter extracts relevant fields from CDK outputs JSON or environment variables - - Infrastructure: VPC ID, ALB ARN, ECS Cluster name, DynamoDB table count, S3 bucket count - - App API: ECS service/cluster name, task definition revision, image tag, force-new-deployment confirmation - - Inference API: image tag, SSM parameter path, target platform, AgentCore Runtime update description - - Frontend: S3 bucket name, CloudFront distribution ID, cache invalidation status, propagation time - - Gateway: Lambda function count, MCP tool names, API Gateway endpoint URL - - RAG Ingestion: image tag, target platform, ECS task definition details - - SageMaker: DynamoDB tables, S3 bucket name, SageMaker execution role ARN - - Bootstrap: auth provider ID, DynamoDB items written, tables seeded - - _Requirements: 4.1, 4.2, 4.3, 4.4, 4.5, 4.6, 4.7, 4.8, 4.9_ - -- [x] 2. Checkpoint — Verify shared library - - Ensure `scripts/common/summary.sh` is syntactically valid (`bash -n scripts/common/summary.sh`) - - Ensure all functions are defined and sourceable - - Ask the user if questions arise - -- [x] 3. Integrate summaries into `version-check.yml` - - [x] 3.1 Add `write_version_check_summary` function to `scripts/common/summary.sh` - - Accept `version_bumped`, `manifests_synced`, `lockfiles_synced` (each pass|fail) - - Accept optional `old_version` and `new_version` parameters - - Render a checklist table with pass/fail status per check - - When any check fails, include remediation instructions (exact commands to run) - - _Requirements: 6.1, 6.2, 6.3_ - - - [x] 3.2 Update `.github/workflows/version-check.yml` to generate summary - - Add a summary generation step with `if: always()` after the evaluate-results step - - Source `scripts/common/summary.sh` and call `write_header` + `write_version_check_summary` - - Pass step outcomes from existing `version-bumped`, `manifests-synced`, `lockfiles-synced` step IDs - - Extract old/new version values from VERSION file and `origin/main` for display - - _Requirements: 6.1, 6.2, 6.3, 9.1, 9.3, 10.3_ - -- [x] 4. Integrate summaries into `app-api.yml` - - [x] 4.1 Add summary steps to `build-docker` job in `app-api.yml` - - Capture `$SECONDS` at job start for timing - - After Docker build, capture image size via `docker inspect` - - Add summary step with `if: always()` that sources `summary.sh` and calls `write_header`, `write_build_summary`, `write_timing_footer` - - On failure, call `write_failure_summary` with relevant error context - - _Requirements: 2.1, 2.2, 2.3, 7.1, 9.3, 10.2, 10.3_ - - - [x] 4.2 Add summary steps to `test-python`, `test-docker`, and `test-cdk` jobs in `app-api.yml` - - In `test-python`: capture pytest output (total/passed/failed/skipped/duration), call `write_test_summary_python` - - In `test-docker`: capture health check result and startup time, call `write_test_summary_docker` - - In `test-cdk`: capture validation result and resource count, call `write_test_summary_cdk` - - Each test job gets `write_header` + test-specific summary + `write_timing_footer` - - All summary steps use `if: always()` - - _Requirements: 3.1, 3.3, 3.4, 3.5, 7.1, 9.3, 10.3_ - - - [x] 4.3 Replace existing inline deploy summary in `app-api.yml` with script-based summary - - Remove the existing inline `Deployment summary` step from `deploy-infrastructure` job - - Add new summary step: source `summary.sh`, call `write_header`, `write_deploy_summary "app-api"`, `write_cdk_outputs_table`, `write_timing_footer` - - On failure, call `write_failure_summary` - - Use `if: always()` condition - - _Requirements: 4.2, 4.9, 7.1, 8.1, 9.1, 9.3, 10.1, 10.3_ - - - [x] 4.4 Add summary step to `push-to-ecr` job in `app-api.yml` - - After ECR push, call `write_header` and `write_build_summary` with ECR URI and image digest - - Use `if: always()` - - _Requirements: 2.2, 9.3, 10.3_ - -- [x] 5. Integrate summaries into `inference-api.yml` - - [x] 5.1 Add summary steps to build, test, and deploy jobs in `inference-api.yml` - - Build job: `write_header` + `write_build_summary` (image tag, platform linux/arm64, image size) - - Test jobs (test-python, test-docker, test-cdk): appropriate `write_test_summary_*` calls - - Deploy job: replace existing inline summary with `write_header` + `write_deploy_summary "inference-api"` + `write_cdk_outputs_table` + `write_timing_footer` - - All summary steps use `if: always()`, call `write_failure_summary` on failure - - _Requirements: 2.1, 2.2, 3.1, 3.3, 3.4, 4.3, 4.9, 7.1, 9.3, 10.1, 10.3_ - -- [x] 6. Integrate summaries into `frontend.yml` - - [x] 6.1 Add summary steps to build, test, and deploy jobs in `frontend.yml` - - Build job: `write_header` + build metadata (no Docker, but build duration and output size) - - Test jobs (test-frontend, test-cdk): `write_test_summary_frontend` and `write_test_summary_cdk` - - Deploy job: replace existing inline summary with `write_header` + `write_deploy_summary "frontend"` + `write_timing_footer` - - All summary steps use `if: always()` - - _Requirements: 3.2, 3.3, 4.4, 4.9, 7.1, 9.3, 10.3_ - -- [x] 7. Integrate summaries into remaining stack workflows - - [x] 7.1 Add summary steps to `infrastructure.yml` - - Deploy job: `write_header` + `write_deploy_summary "infrastructure"` + `write_cdk_outputs_table` + `write_timing_footer` - - Replace existing inline summary, use `if: always()` - - _Requirements: 4.1, 4.9, 7.1, 9.3, 10.1, 10.3_ - - - [x] 7.2 Add summary steps to `gateway.yml` - - Deploy job: `write_header` + `write_deploy_summary "gateway"` + `write_cdk_outputs_table` + `write_timing_footer` - - Replace existing inline summary, use `if: always()` - - _Requirements: 4.5, 4.9, 7.1, 9.3, 10.1, 10.3_ - - - [x] 7.3 Add summary steps to `rag-ingestion.yml` - - Build and deploy jobs: `write_header` + `write_build_summary` + `write_deploy_summary "rag-ingestion"` + `write_cdk_outputs_table` + `write_timing_footer` - - Replace existing inline summary, use `if: always()` - - _Requirements: 2.1, 2.2, 4.6, 4.9, 7.1, 9.3, 10.1, 10.3_ - - - [x] 7.4 Add summary steps to `sagemaker-fine-tuning.yml` - - Deploy job: `write_header` + `write_deploy_summary "sagemaker"` + `write_cdk_outputs_table` + `write_timing_footer` - - Replace existing inline summary, use `if: always()` - - _Requirements: 4.7, 4.9, 7.1, 9.3, 10.1, 10.3_ - - - [x] 7.5 Add summary steps to `bootstrap-data-seeding.yml` - - Seed job: `write_header` + `write_deploy_summary "bootstrap"` + `write_timing_footer` - - Replace existing inline summary, use `if: always()` - - _Requirements: 4.8, 7.1, 9.3, 10.3_ - -- [x] 8. Checkpoint — Verify all stack workflow integrations - - Ensure all 8 stack workflows (infrastructure, app-api, inference-api, frontend, gateway, rag-ingestion, sagemaker-fine-tuning, bootstrap-data-seeding) have summary steps - - Ensure all summary steps use `if: always()` condition - - Ensure no inline summary markdown remains in any workflow - - Ensure all workflows source `scripts/common/summary.sh` - - Ask the user if questions arise - -- [x] 9. Integrate summaries into `nightly.yml` - - [x] 9.1 Add `write_nightly_summary` function to `scripts/common/summary.sh` - - Accept job results as an array of `name|status|duration` tuples - - Render a status table with one row per job showing name, status emoji (✅/❌/⏭️), and duration - - Include a total row with aggregate status and total duration - - Accept backend and frontend coverage percentages for display - - Accept smoke test results (endpoints tested, response codes) for display - - Accept teardown confirmation (stacks destroyed) for display - - Accept AI coverage analysis summary for display - - _Requirements: 5.1, 5.2, 5.3, 5.4, 5.5, 5.6_ - - - [x] 9.2 Add summary steps to individual jobs in `nightly.yml` - - Add `if: always()` summary steps to: `test-backend`, `test-frontend`, `deploy-*` jobs, `smoke-test`, `teardown`, `ai-coverage-analysis` - - Each job outputs its status and duration as job outputs for the aggregator - - Each job also writes its own per-job summary using the appropriate `write_*` functions - - _Requirements: 5.1, 5.2, 5.3, 5.4, 5.5, 5.6, 7.1, 10.3_ - - - [x] 9.3 Add a final aggregator job to `nightly.yml` - - Add a new `summary` job that `needs` all other jobs and runs with `if: always()` - - Collect job outcomes and durations from job outputs - - Source `summary.sh`, call `write_header "Nightly Build & Test" `, then `write_nightly_summary` with all job results - - _Requirements: 5.1, 5.2, 5.3, 5.4, 5.5, 5.6, 9.3_ - -- [x] 10. Final checkpoint — Validate all workflows - - Ensure all 10 workflows have summary generation steps - - Ensure `scripts/common/summary.sh` contains all functions from the design: `write_header`, `write_build_summary`, `write_test_summary_python`, `write_test_summary_frontend`, `write_test_summary_cdk`, `write_test_summary_docker`, `write_deploy_summary`, `write_timing_footer`, `write_failure_summary`, `write_collapsible`, `write_cdk_outputs_table`, `write_nightly_summary`, `write_version_check_summary` - - Ensure all summary steps use `if: always()` condition - - Ensure no raw JSON dumps remain in deploy summaries (replaced by `write_cdk_outputs_table`) - - Ensure all requirements (1–10) are covered by at least one task - - Ask the user if questions arise - -## Notes - -- All code is bash shell scripting — the shared library and workflow YAML changes -- Tasks marked with `*` are optional and can be skipped for faster MVP -- Each task references specific requirements for traceability -- Checkpoints ensure incremental validation -- The library follows the "Shell Scripts First" convention: YAML stays thin, logic lives in `scripts/` -- All summary steps must use `if: always()` so failed runs still produce diagnostic output diff --git a/.kiro/specs/multi-runtime-auth-providers/FRONTEND_AUTH_STRATEGY.md b/.kiro/specs/multi-runtime-auth-providers/FRONTEND_AUTH_STRATEGY.md deleted file mode 100644 index a2645ba1..00000000 --- a/.kiro/specs/multi-runtime-auth-providers/FRONTEND_AUTH_STRATEGY.md +++ /dev/null @@ -1,259 +0,0 @@ -# Frontend Authentication Strategy for Multi-Runtime Architecture - -## Overview - -The frontend authentication strategy has been updated to align with the backend's issuer-based provider resolution. The key insight is that **provider_id is never in the JWT token** - instead, the backend resolves the provider by matching the token's **issuer claim** against configured providers in the database. - -## How It Works - -### Backend Provider Resolution (Already Implemented) - -```python -# In GenericOIDCJWTValidator.resolve_provider_from_token() - -1. Decode JWT token (no signature verification) -2. Extract issuer claim: iss = "https://login.microsoftonline.com/{tenant}/v2.0" -3. Query enabled providers from DynamoDB -4. Match issuer to provider (handles variants like Entra ID v1/v2) -5. Return matched AuthProvider object -``` - -### Frontend Flow - -``` -User authenticates with provider - ↓ -Frontend receives JWT token (contains issuer claim, NOT provider_id) - ↓ -Frontend stores token in localStorage - ↓ -Frontend stores provider_id in sessionStorage (from login flow) - ↓ -When making inference request: - ↓ -Frontend calls GET /auth/runtime-endpoint (with JWT in Authorization header) - ↓ -Backend extracts issuer from JWT - ↓ -Backend matches issuer to provider in database - ↓ -Backend returns runtime endpoint URL + provider_id - ↓ -Frontend uses runtime endpoint URL for inference API calls -``` - -## Key Components - -### 1. AuthApiService (`auth-api.service.ts`) - -```typescript -/** - * Get the AgentCore Runtime endpoint URL for the user's auth provider. - * - * The backend resolves the provider by extracting the issuer claim from the - * user's JWT token and matching it against configured providers in the database. - */ -getRuntimeEndpoint(): Observable { - return this.http.get(`${this.baseUrl()}/auth/runtime-endpoint`); -} -``` - -**Response:** -```typescript -{ - runtime_endpoint_url: "https://bedrock-agentcore.us-east-1.amazonaws.com/runtimes/arn:aws:bedrock-agentcore:us-east-1:123456789012:agent/abc-123/invocations", - provider_id: "entra-id" -} -``` - -### 2. AuthService (`auth.service.ts`) - -**Simplified Approach:** -- No longer attempts to extract provider_id from JWT token -- Tracks provider_id in sessionStorage (set during login flow) -- Uses signal for reactive provider_id tracking -- Provider_id is used for: - - Routing logout requests to correct provider - - Routing refresh token requests to correct provider - - Display purposes in UI - -```typescript -// Signal for tracking current provider (from sessionStorage) -readonly currentProviderId = signal(null); - -// Get provider ID (for logout/refresh routing) -getProviderId(): string | null { - return this.currentProviderId(); -} -``` - -### 3. User Model (`user.model.ts`) - -**No provider_id field:** -```typescript -export interface User { - email: string; - user_id: string; - firstName: string; - lastName: string; - fullName: string; - roles: string[]; - picture?: string; - // NO provider_id - not in JWT token -} -``` - -## Backend API Endpoint (To Be Implemented) - -### GET /auth/runtime-endpoint - -**Purpose:** Return the runtime endpoint URL for the authenticated user's provider - -**Authentication:** Required (JWT in Authorization header) - -**Implementation:** -```python -@router.get("/auth/runtime-endpoint") -async def get_runtime_endpoint(current_user: User = Depends(get_current_user)): - """ - Get the AgentCore Runtime endpoint URL for the user's auth provider. - - Resolves the provider from the user's JWT token issuer claim. - """ - # Get the JWT token from the request - token = request.headers.get("Authorization").replace("Bearer ", "") - - # Resolve provider from token's issuer claim - generic_validator = _get_generic_validator() - provider = await generic_validator.resolve_provider_from_token(token) - - if not provider: - raise HTTPException( - status_code=404, - detail="Provider not found for token issuer" - ) - - if not provider.agentcore_runtime_endpoint_url: - raise HTTPException( - status_code=404, - detail=f"Runtime not ready for provider {provider.provider_id}" - ) - - return { - "runtime_endpoint_url": provider.agentcore_runtime_endpoint_url, - "provider_id": provider.provider_id - } -``` - -**Response Codes:** -- 200: Success - returns runtime endpoint URL -- 401: Unauthorized - invalid or missing JWT token -- 404: Provider not found or runtime not ready - -## Why This Approach Works - -### 1. Issuer is Standard OIDC Claim -Every OIDC-compliant JWT token contains an `iss` (issuer) claim: -```json -{ - "iss": "https://login.microsoftonline.com/{tenant}/v2.0", - "sub": "user-id", - "email": "user@example.com", - "aud": "client-id", - "exp": 1234567890 -} -``` - -### 2. Backend Already Has Provider Resolution Logic -The `GenericOIDCJWTValidator` already implements issuer-based provider resolution: -- Handles issuer variants (Entra ID v1 vs v2) -- Caches issuer → provider mappings -- Queries enabled providers from DynamoDB - -### 3. No Frontend Token Parsing Required -- Frontend doesn't need to decode JWT tokens -- Frontend doesn't need to understand issuer formats -- Backend handles all provider resolution logic -- Frontend just calls the API and gets the runtime URL - -### 4. Consistent with Existing Auth Flow -- Login flow already stores provider_id in sessionStorage -- Logout/refresh already use stored provider_id for routing -- Runtime endpoint resolution follows the same pattern - -## Usage Example - -### In Chat Service (Inference Requests) - -```typescript -export class ChatService { - private authApiService = inject(AuthApiService); - private http = inject(HttpClient); - - async sendMessage(message: string): Promise { - // 1. Get runtime endpoint URL for user's provider - const runtimeInfo = await firstValueFrom( - this.authApiService.getRuntimeEndpoint() - ); - - // 2. Use provider-specific runtime endpoint - const response = await firstValueFrom( - this.http.post(runtimeInfo.runtime_endpoint_url, { - message: message, - // ... other payload - }) - ); - - // 3. Process response - console.log('Response from runtime:', response); - } -} -``` - -### Error Handling - -```typescript -this.authApiService.getRuntimeEndpoint().subscribe({ - next: (response) => { - // Use runtime endpoint URL - this.runtimeEndpointUrl = response.runtime_endpoint_url; - }, - error: (error) => { - if (error.status === 404) { - // Provider not found or runtime not ready - this.showError('Your authentication provider is not configured. Please contact support.'); - } else if (error.status === 401) { - // Token expired or invalid - this.authService.logout(); - } - } -}); -``` - -## Benefits of This Approach - -1. **Simpler Frontend**: No JWT parsing, no issuer extraction -2. **Backend Controls Resolution**: All provider matching logic in one place -3. **Consistent with Existing Patterns**: Uses same validator as authentication -4. **Handles Issuer Variants**: Backend already handles Entra ID v1/v2, etc. -5. **Cacheable**: Backend can cache issuer → provider mappings -6. **Secure**: Frontend never needs to parse or validate tokens - -## Migration Notes - -### What Changed -- Removed provider_id extraction from JWT tokens in frontend -- Simplified AuthService to only track provider_id from sessionStorage -- Removed provider_id field from User model -- Updated AuthApiService documentation to reflect issuer-based resolution - -### What Stayed the Same -- Backend provider resolution logic (already implemented) -- Login flow (still stores provider_id in sessionStorage) -- Logout/refresh routing (still uses stored provider_id) -- Token storage and validation - -### Next Steps -1. Implement GET /auth/runtime-endpoint backend endpoint (Task 15) -2. Update frontend chat service to fetch runtime endpoint (Task 13) -3. Test end-to-end flow with multiple providers diff --git a/.kiro/specs/multi-runtime-auth-providers/design.md b/.kiro/specs/multi-runtime-auth-providers/design.md deleted file mode 100644 index 29ca730b..00000000 --- a/.kiro/specs/multi-runtime-auth-providers/design.md +++ /dev/null @@ -1,970 +0,0 @@ -# Multi-Runtime Authentication Providers - Design - -## Architecture Overview - -### Core Concept - -Deploy a separate AWS Bedrock AgentCore Runtime instance for each OIDC authentication provider. Each runtime is configured with its provider's specific JWT authorizer (issuer URL, client ID, JWKS URI). When an admin adds a provider via the UI, a Lambda function automatically provisions the corresponding runtime. - -### Key Insight - -AWS Bedrock AgentCore supports multiple runtime instances per account (quota: 1,000), and each runtime can have its own independent JWT authorizer configuration. This enables a "runtime per provider" architecture where each provider gets native JWT validation without requiring a proxy layer. - -### High-Level Flow - -``` -Admin creates provider in UI - ↓ -App API saves to DynamoDB - ↓ -DynamoDB Stream triggers Lambda - ↓ -Lambda provisions AgentCore Runtime - ↓ -Runtime ARN stored in DynamoDB - ↓ -User authenticates with provider - ↓ -Frontend fetches runtime endpoint URL - ↓ -Frontend calls runtime directly - ↓ -Runtime validates JWT and processes request -``` - -## Component Architecture - -### 1. DynamoDB Auth Providers Table - -**Purpose**: Store provider configuration and runtime tracking information - -**Schema Extensions**: - -```python -# New fields added to AuthProvider model -agentcore_runtime_arn: Optional[str] = None # ARN of the provisioned runtime -agentcore_runtime_id: Optional[str] = None # Runtime ID for API calls -agentcore_runtime_endpoint_url: Optional[str] = None # Runtime endpoint URL -agentcore_runtime_status: str = "PENDING" # PENDING | CREATING | READY | UPDATING | FAILED | UPDATE_FAILED -agentcore_runtime_error: Optional[str] = None # Error message if provisioning fails -``` - -**DynamoDB Streams**: Enabled with `NEW_AND_OLD_IMAGES` to capture all changes for Lambda processing. - -### 2. Runtime Provisioner Lambda - -**Purpose**: Automatically create, update, and delete AgentCore Runtimes based on provider changes - -**Trigger**: DynamoDB Streams on Auth Providers table - -**Event Handling**: -- `INSERT`: Create new runtime with provider's JWT config -- `MODIFY`: Update runtime if JWT-relevant fields changed (issuer, client ID, JWKS URI) -- `REMOVE`: Delete runtime and clean up SSM parameters - -**Runtime Creation Process**: -1. Extract provider details from DynamoDB stream event -2. Fetch current container image tag from SSM -3. Construct runtime name: `{projectPrefix}_agentcore_runtime_{provider_id}` -4. Determine discovery URL from issuer URL or JWKS URI -5. Call `bedrock-agentcore-control:CreateAgentRuntime` with: - - Container image URI from ECR - - JWT authorizer config (discovery URL, allowed audience) - - Shared resource references (Memory ARN, Gateway ID, Code Interpreter ID, Browser ID) - - Runtime execution role ARN - - Environment variables -6. Store runtime ARN, ID, and endpoint URL in DynamoDB -7. Store runtime ARN in SSM for cross-stack reference - -**Error Handling**: -- Catch all exceptions during runtime creation -- Update DynamoDB with `FAILED` status and error message -- Log detailed error information to CloudWatch -- Retry logic handled by Lambda DynamoDB Stream integration (3 attempts) - -### 3. Runtime Updater Lambda - -**Purpose**: Automatically update all provider runtimes when new container images are deployed - -**Trigger**: EventBridge rule detecting SSM parameter changes for `/inference-api/image-tag` - -**Update Process**: -1. Detect SSM parameter change event from EventBridge -2. Fetch new image tag from SSM -3. Query DynamoDB for all providers with existing runtimes -4. Get new container URI from ECR -5. Update each runtime in parallel (max 5 concurrent): - - Fetch current runtime configuration - - Call `UpdateAgentRuntime` with new container image - - Preserve all other configuration (JWT auth, network, environment) - - Retry up to 3 times with exponential backoff (2s, 4s, 8s) -6. Update DynamoDB status for each provider (UPDATING or UPDATE_FAILED) -7. Send SNS notification summary with success/failure counts - -**Retry Logic**: -- 3 attempts per runtime with exponential backoff -- Individual runtime failures don't affect others -- Failed runtimes marked in DynamoDB with error details -- SNS alert sent for each persistent failure - -### 4. Frontend Runtime Selection Strategy - -**Approach**: Direct Runtime Invocation (No ALB Routing) - -**Key Insight**: AgentCore Runtimes are AWS-managed services with their own HTTPS API endpoints. The frontend calls these endpoints directly using the AWS Bedrock API, not through an ALB. - -**Current Architecture**: -``` -Frontend → AgentCore Runtime HTTPS Endpoint → JWT Validation → Process Request -``` - -**Endpoint Format**: -``` -https://bedrock-agentcore.{region}.amazonaws.com/runtimes/{runtime-arn}/invocations -``` - -**Implementation**: -1. Frontend determines user's auth provider from JWT token or auth service -2. Frontend fetches runtime endpoint URL for that provider from App API -3. Frontend calls the provider-specific runtime endpoint directly -4. Runtime validates JWT using its configured authorizer - -**Frontend Flow**: -```typescript -// 1. Get user's provider ID from auth service -const providerId = this.authService.getProviderId(); // e.g., "entra-id" - -// 2. Fetch runtime endpoint URL for this provider -const runtimeEndpoint = await this.apiService.getRuntimeEndpoint(providerId); -// Returns: "https://bedrock-agentcore.us-east-1.amazonaws.com/runtimes/arn:aws:bedrock-agentcore:us-east-1:123456789012:agent/abc-123/invocations" - -// 3. Call the runtime endpoint directly -const response = await fetch(runtimeEndpoint, { - method: 'POST', - headers: { - 'Authorization': `Bearer ${token}`, - 'Content-Type': 'application/json', - }, - body: JSON.stringify(payload), -}); -``` - -**App API Endpoint** (new): -```python -@router.get("/auth/runtime-endpoint") -async def get_runtime_endpoint(current_user: User = Depends(get_current_user)): - """Get the AgentCore Runtime endpoint URL for the user's auth provider.""" - # Get user's provider ID from JWT claims or user record - provider_id = current_user.provider_id - - # Fetch provider from DynamoDB - provider = await provider_repo.get_provider(provider_id) - - if not provider or not provider.agentcore_runtime_endpoint_url: - raise HTTPException(status_code=404, detail="Runtime not found for provider") - - return { - "runtime_endpoint_url": provider.agentcore_runtime_endpoint_url, - "provider_id": provider_id, - } -``` - -**Why No ALB Routing**: -- AgentCore Runtimes are AWS-managed services, not EC2/Fargate targets -- They have their own HTTPS endpoints managed by AWS -- Cannot be added to ALB target groups -- Frontend calls them directly via AWS Bedrock API - -### 5. Shared Resources - -All runtimes share these AgentCore resources (created once in Inference API Stack): - -- **AgentCore Memory**: Single instance for conversation persistence -- **AgentCore Gateway**: Single instance for MCP tool integration -- **Code Interpreter Custom**: Single instance for code execution -- **Browser Custom**: Single instance for web automation -- **DynamoDB Tables**: Users, roles, tools, sessions, costs, quotas -- **S3 Buckets**: File uploads, vector storage -- **IAM Execution Role**: Shared role with permissions for all resources - -**Benefits of Sharing**: -- Cost efficiency (no duplication of expensive resources) -- Consistent user experience across providers -- Simplified resource management -- Centralized data storage - -### 6. Runtime Naming Convention - -**Format**: `{projectPrefix}_agentcore_runtime_{provider_id}` - -**Rules**: -- Replace hyphens with underscores (AgentCore requirement) -- Use provider ID from database -- Include project prefix for multi-tenant isolation - -**Examples**: -- `bsu_agentcore_runtime_entra_id` -- `bsu_agentcore_runtime_okta_prod` -- `bsu_agentcore_runtime_google_workspace` - -## Data Flow - -### Provider Creation Flow - -``` -1. Admin submits provider form in UI - ↓ -2. Frontend POST /admin/auth-providers - ↓ -3. App API validates and saves to DynamoDB - ↓ -4. DynamoDB Stream emits INSERT event - ↓ -5. Runtime Provisioner Lambda triggered - ↓ -6. Lambda calls CreateAgentRuntime API - ↓ -7. AgentCore provisions runtime (2-5 minutes) - ↓ -8. Lambda stores runtime ARN in DynamoDB - ↓ -9. Lambda stores runtime ARN in SSM - ↓ -10. Admin UI polls for status updates - ↓ -11. Status changes: PENDING → CREATING → READY -``` - -### User Authentication Flow - -``` -1. User authenticates with their provider (Entra ID, Okta, etc.) - ↓ -2. Frontend receives JWT token - ↓ -3. Frontend extracts provider ID from token or auth service - ↓ -4. Frontend fetches runtime endpoint URL from App API - ↓ -5. Frontend calls provider-specific runtime endpoint directly - ↓ -6. Runtime validates JWT using provider's JWKS - ↓ -7. Runtime processes request and returns response -``` - -### Container Image Update Flow - -``` -1. CI/CD builds new Docker image - ↓ -2. Image pushed to ECR with new tag - ↓ -3. CDK deployment updates SSM parameter - ↓ -4. EventBridge detects SSM parameter change - ↓ -5. Runtime Updater Lambda triggered - ↓ -6. Lambda queries all providers with runtimes - ↓ -7. Lambda updates runtimes in parallel (max 5 concurrent) - ↓ -8. Each runtime restarts with new image (2-5 min) - ↓ -9. DynamoDB updated with status for each provider - ↓ -10. SNS notification sent if any failures -``` - -## Infrastructure Components - -### Architectural Decision: Integration with App API Stack - -The runtime provisioning Lambda functions are integrated into the existing App API stack rather than creating a separate RuntimeProvisionerStack. This decision was made to avoid unnecessary cross-stack dependencies: - -**Why App API Stack?** -- The App API stack already depends on the Inference API stack for shared resource ARNs (Memory, Gateway, Code Interpreter, Browser, Runtime Execution Role) -- The Lambda functions need access to both the Auth Providers DynamoDB table (owned by App API stack) and the shared resource ARNs (from Inference API stack) -- Creating a separate stack would require the new stack to depend on both App API and Inference API stacks, creating a complex dependency chain -- Integrating into App API stack keeps the dependency graph simple: Infrastructure → Inference API → App API - -**Benefits**: -- Simpler deployment order (no new stack to coordinate) -- Cleaner dependency management -- All auth-related infrastructure in one stack -- Easier to reason about and maintain - -### Modified Stack: AppApiStack (Runtime Management Integration) - -**Purpose**: Integrate runtime provisioning Lambda functions into the existing App API stack - -**New Resources Added**: -- Runtime Provisioner Lambda function -- Runtime Updater Lambda function -- EventBridge rule for SSM parameter changes -- SNS topic for alerts -- IAM roles and policies for Lambda functions -- CloudWatch dashboard for monitoring -- CloudWatch alarms for failures - -**Dependencies**: -- Infrastructure Stack (VPC, security groups) -- Inference API Stack (shared resource ARNs, execution role ARN) - -**Deployment Order**: After Inference API Stack (unchanged) - -### Modified Stack: AppApiStack (Expanded) - -**Changes**: -1. Enable DynamoDB Streams on Auth Providers table -2. Export stream ARN to SSM for Lambda trigger -3. Update AuthProvider model with runtime tracking fields -4. Add new endpoint: `GET /auth/runtime-endpoint` to return runtime URL for user's provider -5. **Add Runtime Provisioner Lambda function** with DynamoDB Stream trigger -6. **Add Runtime Updater Lambda function** with EventBridge trigger -7. **Add SNS topic** for runtime management alerts -8. **Add EventBridge rule** to detect SSM parameter changes for image tags -9. **Add IAM roles and policies** for Lambda functions -10. **Add CloudWatch dashboard** for runtime monitoring -11. **Add CloudWatch alarms** for failure detection - -### Modified Stack: InferenceApiStack - -**Changes**: -1. **Remove single runtime creation** (now handled by Lambda) -2. Keep shared resources (Memory, Gateway, Code Interpreter, Browser) -3. Export runtime execution role ARN to SSM -4. Export shared resource ARNs to SSM (if not already exported) - -**Migration Strategy**: - -The current InferenceApiStack creates a single runtime for Entra ID at deployment time. With the new design, this becomes obsolete since runtimes are created dynamically by Lambda when providers are added. - -**Option A: Bootstrap with Existing Provider (Recommended)**: -1. Before deploying the updated InferenceApiStack, ensure Entra ID provider exists in DynamoDB -2. Deploy updated AppApiStack with Lambda functions (Lambda will create Entra ID runtime) -3. Deploy updated InferenceApiStack (removes CDK-managed runtime) -4. Old runtime is deleted by CloudFormation, new Lambda-managed runtime takes over -5. Brief service interruption during transition (~2-5 minutes) - -**Option B: Parallel Migration**: -1. Deploy updated AppApiStack with Lambda functions (Lambda creates new Entra ID runtime) -2. Update frontend to use new runtime endpoint -3. Verify new runtime works -4. Deploy updated InferenceApiStack (removes old runtime) -5. Zero downtime but requires coordination - -**Option C: Manual Migration**: -1. Manually create Entra ID provider in DynamoDB via admin UI -2. Wait for Lambda to provision runtime -3. Update frontend configuration -4. Deploy updated InferenceApiStack -5. Most control but requires manual steps - -**Recommended Approach**: Option A with maintenance window -- Schedule deployment during low-usage period -- Communicate expected 5-10 minute downtime -- Rollback plan: revert InferenceApiStack deployment - -### Modified Stack: FrontendStack - -**Changes**: -1. Update API service to fetch runtime endpoint URL from App API -2. Update auth service to track current provider ID -3. Add admin UI for runtime status display -4. Add admin UI for runtime version tracking - -## Security Considerations - -### IAM Permissions - -**Runtime Provisioner Lambda**: -- `bedrock-agentcore:CreateAgentRuntime` -- `bedrock-agentcore:UpdateAgentRuntime` -- `bedrock-agentcore:DeleteAgentRuntime` -- `bedrock-agentcore:GetAgentRuntime` -- `dynamodb:UpdateItem` (Auth Providers table) -- `ssm:GetParameter`, `ssm:PutParameter`, `ssm:DeleteParameter` -- `ecr:DescribeRepositories`, `ecr:DescribeImages` -- `iam:PassRole` (for runtime execution role) - -**Runtime Updater Lambda**: -- `bedrock-agentcore:GetAgentRuntime` -- `bedrock-agentcore:UpdateAgentRuntime` -- `dynamodb:Scan`, `dynamodb:UpdateItem` (Auth Providers table) -- `ssm:GetParameter` -- `ecr:DescribeRepositories`, `ecr:DescribeImages` -- `sns:Publish` (for alerts) - -**Runtime Execution Role** (shared by all runtimes): -- All permissions currently granted to single runtime -- Access to Memory, Gateway, Code Interpreter, Browser -- DynamoDB table access (users, roles, tools, sessions, costs, quotas) -- S3 bucket access (uploads, vectors) -- Bedrock model invocation - -### JWT Validation - -Each runtime validates JWTs independently using its provider's configuration: -- Discovery URL points to provider's OIDC configuration -- JWKS URI fetched from discovery document -- Public keys cached and rotated automatically -- Token signature verified using provider's public key -- Audience claim validated against configured client ID -- Issuer claim validated against configured issuer URL - -### Network Security - -- Runtimes deployed in PUBLIC network mode (AgentCore requirement) -- Runtimes have AWS-managed HTTPS endpoints with TLS -- Security groups control inbound/outbound traffic for supporting infrastructure -- VPC endpoints for AWS service access (optional) - -## Monitoring and Observability - -### CloudWatch Metrics - -**Custom Metrics** (namespace: `AgentCore/RuntimeUpdates`): -- `UpdateSuccess`: Count of successful runtime updates -- `UpdateFailure`: Count of failed runtime updates -- `UpdateDuration`: Time taken to update all runtimes -- `RuntimeCount`: Total number of active runtimes - -**CloudWatch Dashboard**: -- Runtime update success rate graph -- Runtime update duration graph -- Runtime count by status -- Failed update details - -### CloudWatch Alarms - -- **Runtime Update Failures**: Triggers when UpdateFailure > 0 -- **High Update Duration**: Triggers when UpdateDuration > 30 minutes -- **Runtime Creation Failures**: Triggers on Lambda errors - -### SNS Notifications - -**Alert Topics**: -- Runtime provisioning failures -- Runtime update failures -- Runtime deletion failures - -**Notification Content**: -- Provider ID and display name -- Runtime ID and ARN -- Error message and stack trace -- Timestamp and attempt count -- Action required - -### Admin Dashboard - -**Runtime Status View**: -- List of all providers with runtime status -- Current image version per runtime -- Outdated runtime count -- Last update timestamp -- Error details for failed runtimes - -**Runtime Version Tracking**: -- Current deployed image tag -- Image tag per runtime -- Version mismatch indicators -- Manual update trigger button - -## Error Handling - -### Runtime Creation Failures - -**Causes**: -- Invalid JWT configuration (bad discovery URL, invalid client ID) -- ECR image not found -- IAM permission issues -- AgentCore API rate limiting -- Network connectivity issues - -**Handling**: -1. Catch exception in Lambda -2. Update DynamoDB with FAILED status and error message -3. Log detailed error to CloudWatch -4. Lambda DynamoDB Stream integration retries (3 attempts) -5. Admin UI displays error to user - -**Recovery**: -- Admin fixes provider configuration -- Update triggers new runtime creation attempt -- Or admin deletes and recreates provider - -### Runtime Update Failures - -**Causes**: -- Runtime not found (deleted externally) -- AgentCore API rate limiting -- Network connectivity issues -- Invalid runtime configuration - -**Handling**: -1. Retry up to 3 times with exponential backoff -2. Update DynamoDB with UPDATE_FAILED status -3. Send SNS alert with failure details -4. Continue updating other runtimes (no cascading failures) - -**Recovery**: -- Manual retry via admin UI -- Or wait for next image deployment (automatic retry) - -### Routing Failures - -**Causes**: -- Provider ID not found in database -- Runtime not ready (still provisioning) -- Runtime endpoint URL not stored in DynamoDB -- Network connectivity issues - -**Handling**: -- App API returns 404 if provider not found -- Frontend displays error message -- User retries or contacts support - -**Recovery**: -- Wait for runtime provisioning to complete -- Or admin fixes provider configuration - -## Performance Considerations - -### Runtime Provisioning Time - -- **Expected**: 2-5 minutes per runtime -- **Optimization**: None available (AWS-managed process) -- **User Experience**: Show "Provisioning..." status in UI, send email when ready - -### Runtime Update Time - -- **Expected**: 2-5 minutes per runtime -- **Optimization**: Parallel updates (max 5 concurrent) -- **Total Time**: ~5-10 minutes for 5 providers, ~20-30 minutes for 20 providers - -### Request Latency - -- **No Added Latency**: Frontend calls runtime endpoints directly (no proxy, no ALB routing) -- **JWT Validation**: Handled natively by AgentCore (cached JWKS) -- **Routing Overhead**: None (direct API calls) - -### Scalability - -- **Provider Limit**: 1,000 runtimes per account (AWS quota) -- **Concurrent Updates**: 5 runtimes at a time (configurable) -- **AgentCore API Rate Limits**: 5 TPS for Create/Update/Delete operations - -## Cost Analysis - -### Per-Runtime Costs - -- **Base Cost**: $0 (serverless, no idle charges) -- **Invocation Cost**: $0.00002 per request -- **Session Cost**: $0.0001 per minute - -### Example: 5 Providers - -- 5 runtimes × $0 base = $0/month -- 1M requests/month × $0.00002 = $20/month -- Shared resources (Memory, Gateway, etc.): $50/month -- **Total**: ~$70/month (vs $50/month for single runtime) - -### Lambda Costs - -- **Runtime Provisioner**: ~$1/month (infrequent invocations) -- **Runtime Updater**: ~$2/month (monthly image updates) - -### Total Additional Cost - -- **5 Providers**: +$20-25/month -- **10 Providers**: +$40-50/month -- **20 Providers**: +$80-100/month - -## Removing Hardcoded Entra ID Configuration - -The current implementation has Microsoft Entra ID configuration hardcoded throughout the codebase. This section documents all locations where Entra ID configuration must be removed as part of the migration to dynamic provider management. - -### Configuration Files to Update - -#### 1. `infrastructure/lib/config.ts` - -**Remove these fields from `AppConfig` interface**: -```typescript -// REMOVE: -entraClientId: string; -entraTenantId: string; -``` - -**Remove these fields from `AppApiConfig` interface**: -```typescript -// REMOVE: -entraRedirectUri: string; -``` - -**Remove from `loadConfig()` function**: -```typescript -// REMOVE: -entraClientId: process.env.CDK_ENTRA_CLIENT_ID || scope.node.tryGetContext('entraClientId'), -entraTenantId: process.env.CDK_ENTRA_TENANT_ID || scope.node.tryGetContext('entraTenantId'), - -// REMOVE from appApi config: -entraRedirectUri: process.env.CDK_APP_API_ENTRA_REDIRECT_URI || scope.node.tryGetContext('appApi')?.entraRedirectUri, -``` - -#### 2. `infrastructure/lib/app-api-stack.ts` - -**Remove from ECS container environment variables**: -```typescript -// REMOVE these three lines: -ENTRA_CLIENT_ID: config.entraClientId, -ENTRA_TENANT_ID: config.entraTenantId, -ENTRA_REDIRECT_URI: config.appApi.entraRedirectUri, -``` - -**Remove from ECS container secrets**: -```typescript -// REMOVE entire secrets block: -secrets: { - ENTRA_CLIENT_SECRET: ecs.Secret.fromSecretsManager(authSecret, "secret"), -}, -``` - -**Remove authentication secret import**: -```typescript -// REMOVE: -const authSecretArn = ssm.StringParameter.valueForStringParameter( - this, - `/${config.projectPrefix}/auth/secret-arn` -); - -// REMOVE: -const authSecret = secretsmanager.Secret.fromSecretCompleteArn( - this, - "AuthSecret", - authSecretArn -); -``` - -**Remove authentication secret permissions**: -```typescript -// REMOVE: -taskDefinition.taskRole.addToPrincipalPolicy( - new iam.PolicyStatement({ - effect: iam.Effect.ALLOW, - actions: ["secretsmanager:GetSecretValue", "secretsmanager:DescribeSecret"], - resources: [authSecretArn], - }), -); -``` - -#### 3. `infrastructure/lib/inference-api-stack.ts` - -**Remove from runtime authorizer configuration**: -```typescript -// REMOVE entire authorizerConfiguration block: -authorizerConfiguration: { - customJwtAuthorizer: { - discoveryUrl: `https://login.microsoftonline.com/${config.entraTenantId}/v2.0/.well-known/openid-configuration`, - allowedAudience: [config.entraClientId], - } -}, -``` - -**Note**: The runtime resource itself will be removed entirely (see Phase 1 below), but if keeping it temporarily during migration, remove the authorizer configuration. - -#### 4. GitHub Workflows - -**Remove from all workflow files** (`.github/workflows/*.yml`): - -Remove these environment variables from the `env:` section: -```yaml -# REMOVE: -CDK_ENTRA_CLIENT_ID: ${{ vars.CDK_ENTRA_CLIENT_ID }} -CDK_ENTRA_TENANT_ID: ${{ vars.CDK_ENTRA_TENANT_ID }} -CDK_APP_API_ENTRA_REDIRECT_URI: ${{ vars.CDK_APP_API_ENTRA_REDIRECT_URI }} -``` - -Remove this secret: -```yaml -# REMOVE: -CDK_ENTRA_CLIENT_SECRET: ${{ secrets.CDK_ENTRA_CLIENT_SECRET }} -``` - -**Files to update**: -- `.github/workflows/infrastructure.yml` -- `.github/workflows/app-api.yml` -- `.github/workflows/inference-api.yml` - -#### 5. `cdk.context.json` - -**Remove Entra ID configuration** (if present): -```json -// REMOVE: -"entraClientId": "...", -"entraTenantId": "...", -"appApi": { - "entraRedirectUri": "..." -} -``` - -#### 6. GitHub Repository Settings - -**Delete these GitHub Variables** (Settings → Secrets and variables → Actions → Variables): -- `CDK_ENTRA_CLIENT_ID` -- `CDK_ENTRA_TENANT_ID` -- `CDK_APP_API_ENTRA_REDIRECT_URI` - -**Delete this GitHub Secret** (Settings → Secrets and variables → Actions → Secrets): -- `CDK_ENTRA_CLIENT_SECRET` - -#### 7. `scripts/common/load-env.sh` - -**Remove Entra ID environment variable exports**: -```bash -# REMOVE: -export CDK_ENTRA_CLIENT_ID="${CDK_ENTRA_CLIENT_ID:-$(get_json_value "entraClientId" "${CONTEXT_FILE}")}" -export CDK_ENTRA_TENANT_ID="${CDK_ENTRA_TENANT_ID:-$(get_json_value "entraTenantId" "${CONTEXT_FILE}")}" -export CDK_APP_API_ENTRA_REDIRECT_URI="${CDK_APP_API_ENTRA_REDIRECT_URI:-$(get_json_value "appApi.entraRedirectUri" "${CONTEXT_FILE}")}" -``` - -**Remove from context parameters function**: -```bash -# REMOVE: -if [ -n "${CDK_ENTRA_CLIENT_ID:-}" ]; then - context_params="${context_params} --context entraClientId=\"${CDK_ENTRA_CLIENT_ID}\"" -fi -if [ -n "${CDK_ENTRA_TENANT_ID:-}" ]; then - context_params="${context_params} --context entraTenantId=\"${CDK_ENTRA_TENANT_ID}\"" -fi -``` - -**Remove from config display**: -```bash -# REMOVE: -if [ -n "${CDK_ENTRA_CLIENT_ID:-}" ]; then - log_info " Entra Client ID: ${CDK_ENTRA_CLIENT_ID:0:20}..." -fi -``` - -#### 8. Stack Deployment Scripts - -**Remove from `scripts/stack-infrastructure/synth.sh` and `deploy.sh`**: -```bash -# REMOVE context parameters: ---context entraClientId="${CDK_ENTRA_CLIENT_ID}" \ ---context entraTenantId="${CDK_ENTRA_TENANT_ID}" \ -``` - -**Remove from `scripts/stack-app-api/synth.sh` and `deploy.sh`**: -```bash -# REMOVE context parameters: ---context entraClientId="${CDK_ENTRA_CLIENT_ID}" \ ---context entraTenantId="${CDK_ENTRA_TENANT_ID}" \ -``` - -**Remove from `scripts/stack-inference-api/synth.sh` and `deploy.sh`**: -```bash -# REMOVE context parameters: ---context entraClientId="${CDK_ENTRA_CLIENT_ID}" \ ---context entraTenantId="${CDK_ENTRA_TENANT_ID}" \ -``` - -### Backend Code Updates - -#### 9. Test Files - -**Search and update test files** that reference Entra ID: -```bash -# Find all test files with Entra references -grep -r "ENTRA_CLIENT_ID\|ENTRA_TENANT_ID\|ENTRA_REDIRECT_URI\|ENTRA_CLIENT_SECRET" backend/tests/ -``` - -**Update tests to**: -- Use mock auth providers from database instead of hardcoded Entra ID -- Test with multiple providers, not just Entra ID -- Remove Entra-specific test fixtures - -### Migration Checklist - -Complete these steps in order: - -**Phase 0: Pre-Migration** (before any code changes): -- [ ] Document current Entra ID configuration values -- [ ] Create Entra ID provider entry in DynamoDB (via admin UI or seed script) -- [ ] Verify all environment variables are documented -- [ ] Plan maintenance window - -**Phase 1: Remove CDK-Managed Runtime**: -- [ ] Remove runtime creation from `InferenceApiStack` -- [ ] Keep Memory, Gateway, Code Interpreter, Browser -- [ ] Export runtime execution role ARN to SSM (used by Lambda-created runtimes) -- [ ] Deploy updated `InferenceApiStack` - -**Phase 2: Remove Entra ID Configuration**: -- [ ] Update `config.ts` (remove Entra fields) -- [ ] Update `app-api-stack.ts` (remove Entra environment variables and secrets) -- [ ] Update `inference-api-stack.ts` (remove authorizer configuration if runtime still exists) -- [ ] Update GitHub workflow files (remove Entra variables/secrets) -- [ ] Update `cdk.context.json` (remove Entra configuration) -- [ ] Update `load-env.sh` (remove Entra exports) -- [ ] Update stack deployment scripts (remove Entra context parameters) -- [ ] Delete GitHub Variables and Secrets -- [ ] Update test files (remove Entra-specific tests) - -**Phase 3: Deploy Lambda-Managed Runtimes**: -- [ ] Deploy updated `AppApiStack` with Lambda functions -- [ ] Verify Entra ID runtime is created by Lambda -- [ ] Test authentication with Lambda-managed runtime - -**Phase 4: Validation**: -- [ ] Verify no references to `ENTRA_CLIENT_ID`, `ENTRA_TENANT_ID`, `ENTRA_REDIRECT_URI`, `ENTRA_CLIENT_SECRET` in codebase -- [ ] Verify no Entra-specific GitHub Variables or Secrets exist -- [ ] Verify all auth providers are managed via database -- [ ] Test end-to-end authentication flow - -### Why This Matters - -Removing hardcoded Entra ID configuration is critical because: - -1. **Single Source of Truth**: All auth providers (including Entra ID) should be managed via the database, not hardcoded in infrastructure -2. **Consistency**: Entra ID should be treated the same as any other OIDC provider -3. **Flexibility**: Admins can update Entra ID configuration via UI without redeploying infrastructure -4. **Scalability**: Adding new providers doesn't require code changes or redeployment -5. **Security**: Client secrets stored in Secrets Manager with provider ID keys, not hardcoded per-provider secrets - -## Trade-offs and Alternatives - -### Pros of Multi-Runtime Approach - -✅ Native JWT validation (no custom code) -✅ Complete provider isolation -✅ No added request latency -✅ Automatic provisioning -✅ Scalable to 1,000 providers -✅ Native AWS security - -### Cons of Multi-Runtime Approach - -❌ Longer provisioning time (2-5 min per provider) -❌ Higher operational complexity -❌ Multiple runtime instances to manage -❌ Frontend needs to fetch runtime endpoint per provider - -### Alternative: Auth Proxy (Option 1) - -**Approach**: Single runtime with validation proxy that reads all providers from DynamoDB - -**Pros**: -- Simpler routing (single runtime endpoint) -- Instant provider activation (no runtime provisioning) -- Unlimited providers (no AWS quota limits) -- Centralized auth logic - -**Cons**: -- Added request latency (+50-100ms) -- Custom JWT validation code -- Additional infrastructure (proxy service) -- Single point of failure - -### Recommendation - -- **1-5 Providers**: Multi-Runtime (this design) -- **5-10 Providers**: Multi-Runtime or Hybrid -- **10+ Providers**: Auth Proxy (Option 1) - -## Implementation Phases - -### Phase 0: Pre-Migration Preparation (Week 0) -- Document current Entra ID runtime configuration -- Create Entra ID provider entry in DynamoDB (if not exists) -- Verify all environment variables and configurations -- Plan maintenance window for migration - -### Phase 1: Core Infrastructure (Week 1) -- Update Auth Provider DynamoDB schema -- Enable DynamoDB Streams -- Export runtime execution role ARN to SSM -- **Remove runtime creation from InferenceApiStack** (keep shared resources) -- Update InferenceApiStack to only create Memory, Gateway, Code Interpreter, Browser - -**Code Removals**: -```typescript -// infrastructure/lib/inference-api-stack.ts -// REMOVE: this.runtime = new bedrock.CfnRuntime(...) -// REMOVE: Runtime-specific SSM parameters -// REMOVE: Runtime endpoint URL exports -// KEEP: Memory, Gateway, Code Interpreter, Browser -// KEEP: Runtime execution role (used by Lambda-created runtimes) -``` - -### Phase 2: Runtime Provisioner (Week 2) -- Create Runtime Provisioner Lambda function in App API Stack -- Add DynamoDB Stream trigger -- Add IAM permissions for Bedrock AgentCore operations -- Test runtime creation with sample provider - -### Phase 3: Runtime Updater (Week 3) -- Create Runtime Updater Lambda function in App API Stack -- Add EventBridge rule for SSM changes -- Add SNS topic for alerts -- Implement retry logic and SNS alerts -- Test automatic image updates - -### Phase 4: Routing & Frontend (Week 4) -- Update frontend to fetch runtime endpoint URL from App API -- Update auth service to track provider ID -- Add App API endpoint: GET /auth/runtime-endpoint -- Test end-to-end authentication flow - -### Phase 5: Monitoring & Observability (Week 5) -- Create CloudWatch dashboard -- Configure CloudWatch alarms -- Add admin UI for runtime status -- Add admin UI for version tracking - -### Phase 6: Testing & Validation (Week 6) -- End-to-end testing with multiple providers -- Load testing with concurrent requests -- Failure scenario testing -- Performance benchmarking - -### Phase 7: Documentation & Operations (Week 7) -- Operational runbooks -- Troubleshooting guides -- Team training -- Production deployment - -## Success Criteria - -1. ✅ Runtime provisioning success rate > 95% -2. ✅ Runtime update success rate > 98% -3. ✅ Average provisioning time < 5 minutes -4. ✅ Average update time < 5 minutes per runtime -5. ✅ Zero authentication failures due to routing -6. ✅ Admin UI shows real-time runtime status -7. ✅ SNS alerts sent for all failures -8. ✅ CloudWatch dashboard operational -9. ✅ All runtimes share Memory, Gateway, Code Interpreter, Browser -10. ✅ Users from any provider can access AI agent - -## Rollback Plan - -If critical issues arise: - -1. **Immediate**: Disable new provider creation in admin UI -2. **Short-term**: Route all traffic to primary runtime (Entra ID) -3. **Medium-term**: Implement auth proxy (Option 1) as fallback -4. **Long-term**: Fix issues and re-enable multi-runtime - -## Future Enhancements - -1. **Blue-Green Deployment**: Zero-downtime runtime updates -2. **Provider-Specific Resources**: Dedicated Memory/Gateway per provider -3. **Multi-Region Support**: Runtimes in multiple AWS regions -4. **Auto-Scaling**: Dynamic runtime provisioning based on load -5. **Cost Allocation**: Per-provider cost tracking and billing -6. **Runtime Health Checks**: Automated health monitoring and recovery -7. **Provider Groups**: Shared runtimes for provider groups -8. **Advanced Routing Logic**: Custom provider selection strategies diff --git a/.kiro/specs/multi-runtime-auth-providers/requirements.md b/.kiro/specs/multi-runtime-auth-providers/requirements.md deleted file mode 100644 index 795f3e0e..00000000 --- a/.kiro/specs/multi-runtime-auth-providers/requirements.md +++ /dev/null @@ -1,231 +0,0 @@ -# Multi-Runtime Authentication Providers - Requirements - -## Feature Overview - -Implement dynamic multi-runtime deployment strategy to support multiple OIDC authentication providers. When an admin adds a new authentication provider via the UI, automatically provision a dedicated AWS Bedrock AgentCore Runtime with that provider's JWT authorizer configuration. - -## Problem Statement - -The application currently supports dynamic database-driven OIDC provider management through the admin UI. However, the AgentCore Runtime is deployed with a single, hardcoded JWT authorizer pointing to Microsoft Entra ID. This creates a mismatch: - -- ✅ App API (port 8000) can authenticate users from any provider in the database -- ❌ Inference API (AgentCore Runtime, port 8001) only accepts Entra ID tokens -- ❌ Users authenticated via new providers cannot invoke the AI agent - -## User Stories - -### 1. Admin Provider Management -**As a** system administrator -**I want to** add new OIDC authentication providers through the admin UI -**So that** users from different identity providers can access the platform - -**Acceptance Criteria:** -- 1.1 When I create a new auth provider, a dedicated AgentCore Runtime is automatically provisioned -- 1.2 The runtime is configured with the provider's JWT authorizer (issuer URL, client ID, JWKS URI) -- 1.3 Runtime creation status is visible in the admin UI (PENDING → CREATING → READY → FAILED) -- 1.4 Runtime provisioning completes within 5 minutes -- 1.5 If provisioning fails, error details are displayed in the admin UI - -### 2. Automatic Runtime Updates -**As a** system administrator -**I want to** update authentication provider configuration -**So that** changes are reflected in the runtime without manual intervention - -**Acceptance Criteria:** -- 2.1 When I update a provider's issuer URL or client ID, the runtime is automatically updated -- 2.2 Runtime update status is visible (UPDATING) -- 2.3 Active sessions are not interrupted during updates -- 2.4 Update failures are logged and alerted - -### 3. Container Image Synchronization -**As a** DevOps engineer -**I want to** deploy new container images -**So that** all provider runtimes are automatically updated to the latest code - -**Acceptance Criteria:** -- 3.1 When a new Docker image is pushed to ECR, all provider runtimes are updated automatically -- 3.2 Updates happen in parallel to minimize total update time -- 3.3 Failed updates are retried with exponential backoff -- 3.4 SNS notifications are sent for update failures -- 3.5 Admin dashboard shows which runtimes are on which image versions - -### 4. Provider Deletion -**As a** system administrator -**I want to** delete authentication providers -**So that** unused providers and their resources are cleaned up - -**Acceptance Criteria:** -- 4.1 When I delete a provider, its runtime is automatically deleted -- 4.2 SSM parameters for the provider are cleaned up -- 4.3 Deletion is confirmed before proceeding -- 4.4 Active sessions using the provider are gracefully terminated - -### 5. User Authentication Routing -**As a** user -**I want to** authenticate with my organization's identity provider -**So that** I can access the AI agent with my existing credentials - -**Acceptance Criteria:** -- 5.1 Frontend determines my provider ID from my JWT token or auth service -- 5.2 Frontend fetches the correct runtime endpoint URL for my provider from App API -- 5.3 Frontend calls my provider's runtime endpoint directly -- 5.4 Runtime validates my JWT token using my provider's JWKS -- 5.5 Authentication failures provide clear error messages - -### 6. Shared Resource Access -**As a** user authenticated via any provider -**I want to** access shared platform resources -**So that** my experience is consistent regardless of provider - -**Acceptance Criteria:** -- 6.1 All runtimes share the same AgentCore Memory instance -- 6.2 All runtimes share the same AgentCore Gateway instance -- 6.3 All runtimes share the same Code Interpreter and Browser instances -- 6.4 All runtimes access the same DynamoDB tables (users, roles, tools, etc.) -- 6.5 All runtimes access the same S3 buckets (uploads, vectors) - -## Technical Requirements - -### Architecture Constraints - -1. **Stack Separation**: App API and Inference API are in separate CDK stacks -2. **Shared Resources**: Memory, Gateway, Code Interpreter, Browser are shared across all runtimes -3. **AWS Quotas**: Support up to 1,000 runtimes per account (AWS limit) -4. **Runtime Creation Time**: 2-5 minutes per runtime -5. **Deployment Order**: Infrastructure → Gateway → App API → Inference API - -### Database Schema - -Auth Providers table must track runtime information: - -``` -PK: AUTH_PROVIDER#{provider_id} -SK: AUTH_PROVIDER#{provider_id} -Attributes: - - agentcoreRuntimeArn: string (optional) - - agentcoreRuntimeId: string (optional) - - agentcoreRuntimeEndpointUrl: string (optional) - - agentcoreRuntimeStatus: string (PENDING | CREATING | READY | UPDATING | FAILED | UPDATE_FAILED) - - agentcoreRuntimeError: string (optional) -``` - -### Event-Driven Architecture - -1. **DynamoDB Streams**: Enabled on Auth Providers table -2. **Lambda Trigger**: Runtime Provisioner Lambda triggered by stream events -3. **EventBridge**: Triggers Runtime Updater Lambda when image tag changes in SSM -4. **SNS Notifications**: Alerts for provisioning/update failures - -### Routing Strategy - -**Direct Runtime Invocation**: -- Frontend fetches runtime endpoint URL from App API based on user's provider ID -- Frontend calls provider-specific runtime endpoint directly -- No ALB routing needed (AgentCore Runtimes are AWS-managed services with their own HTTPS endpoints) - -**Endpoint Format**: `https://bedrock-agentcore.{region}.amazonaws.com/runtimes/{runtime-arn}/invocations` - -### Security - -1. **IAM Roles**: Shared execution role for all runtimes (or per-runtime if needed) -2. **JWT Validation**: Each runtime validates tokens from its specific provider -3. **Resource Access**: All runtimes have identical permissions to shared resources -4. **Secrets**: Client secrets stored in Secrets Manager, referenced by provider ID - -## Non-Functional Requirements - -### Performance -- Runtime provisioning: < 5 minutes -- Runtime updates: < 5 minutes per runtime -- Image updates: All runtimes updated within 30 minutes (parallel execution) -- Request latency: No added latency vs single runtime (direct runtime invocation) - -### Scalability -- Support 1-10 providers initially -- Architecture supports up to 1,000 providers (AWS quota) -- Parallel runtime updates (max 5 concurrent) - -### Reliability -- Retry logic for transient failures (3 attempts with exponential backoff) -- SNS alerts for persistent failures -- CloudWatch metrics for monitoring -- Failed updates don't affect other runtimes - -### Observability -- CloudWatch dashboard for runtime status -- Admin UI shows runtime version and status -- Logs for all provisioning/update operations -- Metrics: update success rate, update duration, runtime count - -### Cost -- Estimated $20/month additional cost for 5 providers (vs single runtime) -- No base cost per runtime (serverless, pay per invocation) -- Shared resources minimize overhead - -## Dependencies - -### Existing Infrastructure -- App API Stack (DynamoDB tables, auth provider management) -- Inference API Stack (shared AgentCore resources) -- Infrastructure Stack (VPC, ALB, ECS Cluster) - -### New Infrastructure -- Runtime Provisioner Lambda + Stack -- Runtime Updater Lambda -- DynamoDB Streams on Auth Providers table -- EventBridge rule for image tag changes -- SNS topic for alerts -- App API endpoint for runtime URL lookup - -### Code Changes -- Auth Provider models (add runtime tracking fields) -- App API endpoint (GET /auth/runtime-endpoint) -- Frontend API service (fetch runtime endpoint URL per provider) -- Admin UI (display runtime status) - -## Out of Scope - -- Multi-region runtime deployment -- Blue-green deployment for runtimes -- Custom routing logic beyond header/path-based -- Runtime auto-scaling (handled by AgentCore) -- Provider-specific resource quotas (use existing quota system) - -## Success Metrics - -1. **Provisioning Success Rate**: > 95% of runtime creations succeed -2. **Update Success Rate**: > 98% of runtime updates succeed -3. **Provisioning Time**: < 5 minutes average -4. **Update Time**: < 5 minutes per runtime average -5. **User Impact**: Zero authentication failures due to routing issues -6. **Operational Overhead**: < 1 hour/week for runtime management - -## Risks and Mitigations - -### Risk 1: Runtime Creation Failures -**Impact**: Users cannot authenticate with new provider -**Mitigation**: Retry logic, detailed error logging, SNS alerts, admin UI shows status - -### Risk 2: Runtime Endpoint Resolution Failures -**Impact**: Requests cannot be routed to correct runtime -**Mitigation**: Comprehensive testing, endpoint validation, fallback error handling - -### Risk 3: Image Update Failures -**Impact**: Runtimes running stale code -**Mitigation**: Parallel updates with retry, SNS alerts, admin dashboard shows versions - -### Risk 4: Cost Overruns -**Impact**: Unexpected AWS charges -**Mitigation**: CloudWatch cost monitoring, runtime count limits, cost alerts - -### Risk 5: Shared Resource Contention -**Impact**: Performance degradation -**Mitigation**: Monitor resource usage, implement quotas, scale shared resources - -## Future Enhancements - -1. **Blue-Green Deployment**: Zero-downtime runtime updates -2. **Provider-Specific Resources**: Dedicated Memory/Gateway per provider -3. **Multi-Region Support**: Runtimes in multiple AWS regions -4. **Auto-Scaling**: Dynamic runtime provisioning based on load -5. **Cost Allocation**: Per-provider cost tracking and billing diff --git a/.kiro/specs/multi-runtime-auth-providers/tasks.md b/.kiro/specs/multi-runtime-auth-providers/tasks.md deleted file mode 100644 index a5de2735..00000000 --- a/.kiro/specs/multi-runtime-auth-providers/tasks.md +++ /dev/null @@ -1,333 +0,0 @@ -# Multi-Runtime Authentication Providers - Tasks - -## Overview - -This task list implements dynamic multi-runtime deployment for OIDC authentication providers. When an admin adds a provider via the UI, a Lambda function (integrated into the App API stack) automatically provisions a dedicated AWS Bedrock AgentCore Runtime with that provider's JWT authorizer configuration. - -The Lambda functions for runtime management are deployed as part of the App API stack rather than a separate stack, avoiding unnecessary cross-stack dependencies since the App API stack already depends on the Inference API stack for shared resource ARNs. - -## Task Breakdown - -### Phase 1: Database Schema Updates - -- [x] 2. Update Auth Providers DynamoDB Table - - [x] 2.1 Add runtime tracking fields to AuthProvider model in backend - - Add `agentcoreRuntimeArn: Optional[str]` - - Add `agentcoreRuntimeId: Optional[str]` - - Add `agentcoreRuntimeEndpointUrl: Optional[str]` - - Add `agentcoreRuntimeStatus: str` (default: "PENDING") - - Add `agentcoreRuntimeError: Optional[str]` - - [x] 2.2 Enable DynamoDB Streams on Auth Providers table in AppApiStack - - Set `stream: dynamodb.StreamViewType.NEW_AND_OLD_IMAGES` - - [x] 2.3 Export stream ARN to SSM Parameter Store - - Parameter: `/${projectPrefix}/auth/auth-providers-stream-arn` - - [x] 2.4 Deploy AppApiStack with schema changes - -### Phase 2: Remove CDK-Managed Runtime - -- [x] 3. Update InferenceApiStack - - [x] 3.1 Remove runtime creation code - - Remove `this.runtime = new bedrock.CfnRuntime(...)` - - Remove runtime-specific SSM parameters - - Remove runtime endpoint URL exports - - [x] 3.2 Keep shared resources - - Keep Memory, Gateway, Code Interpreter, Browser - - Keep all IAM roles (runtime execution role will be used by Lambda-created runtimes) - - [x] 3.3 Export runtime execution role ARN to SSM - - Parameter: `/${projectPrefix}/inference-api/runtime-execution-role-arn` - - [x] 3.4 Export shared resource ARNs to SSM (if not already exported) - - Memory ARN, Gateway ID, Code Interpreter ID, Browser ID - - [x] 3.5 Update CloudFormation outputs (remove runtime-specific outputs) - - [x] 3.6 Deploy InferenceApiStack (this will delete the old runtime) - -### Phase 3: Runtime Provisioner Lambda - -- [x] 4. Create Runtime Provisioner Lambda Function - - [x] 4.1 Create Lambda function code (`backend/lambda-functions/runtime-provisioner/`) - - Implement DynamoDB Stream event handler - - Implement `handle_insert()` - create new runtime - - Implement `handle_modify()` - update runtime if JWT config changed - - Implement `handle_remove()` - delete runtime and clean up SSM - - [x] 4.2 Implement runtime creation logic - - Fetch container image tag from SSM - - Construct runtime name: `{projectPrefix}_agentcore_runtime_{provider_id}` - - Determine discovery URL from issuer URL or JWKS URI - - Call `bedrock-agentcore-control:CreateAgentRuntime` API - - Store runtime ARN, ID, endpoint URL in DynamoDB - - Store runtime ARN in SSM: `/${projectPrefix}/runtimes/{provider_id}/arn` - - [x] 4.3 Implement error handling - - Catch all exceptions during runtime operations - - Update DynamoDB with FAILED status and error message - - Log detailed errors to CloudWatch - - [x] 4.4 Add retry logic (handled by Lambda DynamoDB Stream integration) - - [x] 4.5 Create requirements.txt with dependencies (boto3, etc.) - -- [x] 5. Add Runtime Provisioner Lambda to AppApiStack - - [x] 5.1 Update AppApiStack CDK file (`infrastructure/lib/app-api-stack.ts`) - - [x] 5.2 Define Lambda function resource - - Runtime: Python 3.13 - - Memory: 512 MB - - Timeout: 5 minutes - - Code from `backend/lambda-functions/runtime-provisioner/` - - Environment variables (project prefix, region, auth providers table name) - - [x] 5.3 Create IAM role for Lambda - - DynamoDB Stream read permissions - - DynamoDB UpdateItem permissions (Auth Providers table) - - Bedrock AgentCore permissions (CreateAgentRuntime, UpdateAgentRuntime, DeleteAgentRuntime, GetAgentRuntime) - - SSM Parameter Store read/write permissions - - ECR read permissions (DescribeRepositories, DescribeImages) - - IAM PassRole permission (for runtime execution role) - - CloudWatch Logs permissions - - [x] 5.4 Add DynamoDB Stream event source - - Use stream ARN from Auth Providers table - - Set batch size: 1 - - Set starting position: LATEST - - Enable retry with 3 attempts - - [x] 5.5 Add CloudWatch log group with retention policy - - [x] 5.6 Deploy AppApiStack with Runtime Provisioner Lambda - -### Phase 4: Runtime Updater Lambda - -- [x] 6. Create Runtime Updater Lambda Function - - [x] 6.1 Create Lambda function code (`backend/lambda-functions/runtime-updater/`) - - Implement EventBridge event handler - - Query DynamoDB for all providers with existing runtimes - - Fetch new container image URI from ECR - - Update runtimes in parallel (max 5 concurrent) - - Implement retry logic (3 attempts with exponential backoff) - - Update DynamoDB status for each provider - - Send SNS notification summary - - [x] 6.2 Implement update logic - - Fetch current runtime configuration via GetAgentRuntime - - Call UpdateAgentRuntime with new container image - - Preserve all other configuration (JWT auth, network, environment) - - [x] 6.3 Create requirements.txt with dependencies - -- [x] 7. Add Runtime Updater to AppApiStack - - [x] 7.1 Define Lambda function resource in AppApiStack - - Runtime: Python 3.13 - - Memory: 512 MB - - Timeout: 15 minutes (for parallel updates) - - Code from `backend/lambda-functions/runtime-updater/` - - [x] 7.2 Create IAM role for Lambda - - Bedrock AgentCore permissions (GetAgentRuntime, UpdateAgentRuntime) - - DynamoDB Scan and UpdateItem permissions - - SSM Parameter Store read permissions - - ECR read permissions - - SNS Publish permissions - - [x] 7.3 Create SNS topic for alerts - - Topic name: `{projectPrefix}-runtime-update-alerts` - - Add email subscription (optional) - - [x] 7.4 Create EventBridge rule - - Detect SSM parameter changes: `/${projectPrefix}/inference-api/image-tag` - - Target: Runtime Updater Lambda - - [x] 7.5 Deploy updated AppApiStack with Runtime Updater - -### Phase 5: Remove Entra ID Hardcoded Configuration - -- [x] 8. Update Configuration Files - - [x] 8.1 Update `infrastructure/lib/config.ts` - - Remove `entraClientId` and `entraTenantId` from `AppConfig` interface - - Remove `entraRedirectUri` from `AppApiConfig` interface - - Remove Entra fields from `loadConfig()` function - - [x] 8.2 Update `infrastructure/lib/app-api-stack.ts` - - Remove `ENTRA_CLIENT_ID`, `ENTRA_TENANT_ID`, `ENTRA_REDIRECT_URI` environment variables - - Remove `ENTRA_CLIENT_SECRET` from secrets block - - Remove authentication secret import (`authSecretArn`, `authSecret`) - - Remove authentication secret permissions from task role - - [x] 8.3 Update GitHub workflow files - - Remove `CDK_ENTRA_CLIENT_ID`, `CDK_ENTRA_TENANT_ID`, `CDK_APP_API_ENTRA_REDIRECT_URI` from env sections - - Remove `CDK_ENTRA_CLIENT_SECRET` from secrets - - Files: `.github/workflows/infrastructure.yml`, `app-api.yml`, `inference-api.yml` - - [x] 8.4 Update `cdk.context.json` - - Remove Entra ID configuration (if present) - - [x] 8.5 Update `scripts/common/load-env.sh` - - Remove Entra ID environment variable exports - - Remove Entra ID from context parameters function - - Remove Entra ID from config display - - [x] 8.6 Update stack deployment scripts - - Remove Entra context parameters from `scripts/stack-infrastructure/synth.sh` and `deploy.sh` - - Remove Entra context parameters from `scripts/stack-app-api/synth.sh` and `deploy.sh` - - Remove Entra context parameters from `scripts/stack-inference-api/synth.sh` and `deploy.sh` - -- [ ] 9. Update GitHub Repository Settings - - [ ] 9.1 Delete GitHub Variables - - Delete `CDK_ENTRA_CLIENT_ID` - - Delete `CDK_ENTRA_TENANT_ID` - - Delete `CDK_APP_API_ENTRA_REDIRECT_URI` - - [ ] 9.2 Delete GitHub Secrets - - Delete `CDK_ENTRA_CLIENT_SECRET` - -- [x] 10. Update Backend Code - - [x] 10.1 Search for Entra references in test files - - Run: `grep -r "ENTRA_CLIENT_ID\|ENTRA_TENANT_ID\|ENTRA_REDIRECT_URI\|ENTRA_CLIENT_SECRET" backend/tests/` - - [x] 10.2 Update test files to use mock auth providers from database - - [x] 10.3 Remove Entra-specific test fixtures - -- [ ] 11. Deploy Configuration Changes - - [ ] 11.1 Deploy updated AppApiStack (without Entra environment variables) - - [ ] 11.2 Verify deployment succeeds - - [ ] 11.3 Verify no references to Entra configuration in deployed resources - -### Phase 6: Frontend Updates - -- [x] 12. Update Frontend API Service - - [x] 12.1 Add method to fetch runtime endpoint URL - - `getRuntimeEndpoint(providerId: string): Promise` - - Calls `GET /auth/runtime-endpoint` - - [x] 12.2 Update auth service to track current provider ID - - Extract provider ID from JWT token or user record - - Store in signal: `currentProviderId = signal(null)` - -- [x] 13. Update Frontend Chat Service - - [x] 13.1 Fetch runtime endpoint URL before making inference requests - - Get provider ID from auth service - - Fetch runtime endpoint URL from API service - - Use runtime endpoint URL for all inference API calls - - [x] 13.2 Handle runtime endpoint resolution errors - - Display error message if provider not found - - Display error message if runtime not ready - -- [x] 14. Add Admin UI for Runtime Status - - [x] 14.1 Create runtime status component - - Display list of all providers with runtime status - - Show runtime ARN, ID, endpoint URL - - Show runtime status (PENDING, CREATING, READY, UPDATING, FAILED) - - Show error details for failed runtimes - - [x] 14.2 Add runtime version tracking - - Display current deployed image tag - - Display image tag per runtime - - Show version mismatch indicators - - [x] 14.3 Add manual update trigger button (optional) - -### Phase 7: App API Backend Updates - -- [x] 15. Add Runtime Endpoint API - - [x] 15.1 Create new endpoint: `GET /auth/runtime-endpoint` - - Extract provider ID from current user's JWT claims or user record - - Fetch provider from DynamoDB - - Return runtime endpoint URL - - Return 404 if provider not found or runtime not ready - - [x] 15.2 Add authentication middleware (require valid JWT) - - [x] 15.3 Add error handling for missing runtime - -### Phase 8: Monitoring and Observability - -- [ ] 16. Add CloudWatch Metrics - - [ ] 16.1 Create custom metrics in Runtime Updater Lambda - - `UpdateSuccess`: Count of successful runtime updates - - `UpdateFailure`: Count of failed runtime updates - - `UpdateDuration`: Time taken to update all runtimes - - `RuntimeCount`: Total number of active runtimes - - [ ] 16.2 Namespace: `AgentCore/RuntimeUpdates` - -- [ ] 17. Create CloudWatch Dashboard - - [ ] 17.1 Add runtime update success rate graph - - [ ] 17.2 Add runtime update duration graph - - [ ] 17.3 Add runtime count by status - - [ ] 17.4 Add failed update details - -- [ ] 18. Configure CloudWatch Alarms - - [ ] 18.1 Create alarm for runtime update failures - - Trigger when `UpdateFailure > 0` - - Send SNS notification - - [ ] 18.2 Create alarm for high update duration - - Trigger when `UpdateDuration > 30 minutes` - - Send SNS notification - - [ ] 18.3 Create alarm for runtime creation failures - - Trigger on Lambda errors in Runtime Provisioner - - Send SNS notification - -### Phase 9: Testing and Validation - -- [ ] 19. Test Runtime Provisioning - - [ ] 19.1 Create test auth provider via admin UI - - Verify DynamoDB Stream triggers Lambda - - Verify runtime is created in AWS - - Verify runtime ARN stored in DynamoDB - - Verify runtime status changes: PENDING → CREATING → READY - - [ ] 19.2 Test runtime provisioning failure scenarios - - Invalid JWT configuration (bad discovery URL) - - Invalid client ID - - Network connectivity issues - - Verify error message stored in DynamoDB - - Verify SNS alert sent - -- [ ] 20. Test Runtime Updates - - [ ] 20.1 Push new Docker image to ECR - - Verify SSM parameter updated - - Verify EventBridge triggers Lambda - - Verify all runtimes updated in parallel - - Verify DynamoDB status updated - - [ ] 20.2 Test runtime update failure scenarios - - Runtime not found (deleted externally) - - Network connectivity issues - - Verify retry logic (3 attempts) - - Verify SNS alert sent - -- [ ] 21. Test End-to-End Authentication Flow - - [ ] 21.1 Authenticate with test provider - - Verify JWT token received - - Verify provider ID extracted from token - - [ ] 21.2 Fetch runtime endpoint URL - - Verify correct endpoint URL returned - - Verify 404 if provider not found - - [ ] 21.3 Call runtime endpoint directly - - Verify JWT validated by runtime - - Verify request processed successfully - - [ ] 21.4 Test with multiple providers - - Create 2-3 test providers - - Verify each has its own runtime - - Verify users can authenticate with any provider - -- [ ] 22. Test Provider Deletion - - [ ] 22.1 Delete test provider via admin UI - - Verify DynamoDB Stream triggers Lambda - - Verify runtime deleted in AWS - - Verify SSM parameters cleaned up - - Verify DynamoDB record deleted - -- [ ] 23. Validate Configuration Removal - - [ ] 23.1 Search codebase for Entra references - - Run: `grep -r "ENTRA_CLIENT_ID\|ENTRA_TENANT_ID\|ENTRA_REDIRECT_URI\|ENTRA_CLIENT_SECRET" .` - - Verify no matches found (except in documentation) - - [ ] 23.2 Verify GitHub Variables and Secrets deleted - - [ ] 23.3 Verify all auth providers managed via database - - [ ] 23.4 Test end-to-end authentication flow (no Entra hardcoded config) - -### Phase 10: Documentation and Cleanup - -- [ ] 24. Update Documentation - - [ ] 24.1 Update README with new provider management process - - [ ] 24.2 Create operational runbook for runtime management - - [ ] 24.3 Create troubleshooting guide for common issues - - [ ] 24.4 Document monitoring and alerting setup - -- [ ] 25. Cleanup and Optimization - - [ ] 25.1 Remove unused SSM parameters (old Entra configuration) - - [ ] 25.2 Remove unused Secrets Manager secrets (old Entra client secret) - - [ ] 25.3 Verify no orphaned resources in AWS - - [ ] 25.4 Optimize Lambda memory and timeout settings based on actual usage - -## Success Criteria - -- [ ] Runtime provisioning success rate > 95% -- [ ] Runtime update success rate > 98% -- [ ] Average provisioning time < 5 minutes -- [ ] Average update time < 5 minutes per runtime -- [ ] Zero authentication failures due to routing issues -- [ ] Admin UI shows real-time runtime status -- [ ] SNS alerts sent for all failures -- [ ] CloudWatch dashboard operational -- [ ] All runtimes share Memory, Gateway, Code Interpreter, Browser -- [ ] Users from any provider can access AI agent -- [ ] No references to hardcoded Entra ID configuration in codebase - -## Notes - -- Tasks should be executed in order (phases are sequential) -- Each phase should be tested before moving to the next -- Maintain a rollback plan for each deployment -- Schedule deployments during low-usage periods -- Communicate expected downtime to users (5-10 minutes during Phase 2) -- **Architectural Decision**: Lambda functions are integrated into the App API stack rather than a separate RuntimeProvisionerStack to avoid unnecessary cross-stack dependencies. The App API stack already depends on the Inference API stack for shared resource ARNs, making it the natural location for runtime management logic. diff --git a/.kiro/specs/nodejs24-actions-upgrade/.config.kiro b/.kiro/specs/nodejs24-actions-upgrade/.config.kiro deleted file mode 100644 index d7017dfb..00000000 --- a/.kiro/specs/nodejs24-actions-upgrade/.config.kiro +++ /dev/null @@ -1 +0,0 @@ -{"specId": "0c4a9b5c-8748-43ae-a5f2-636d49862ad4", "workflowType": "requirements-first", "specType": "feature"} \ No newline at end of file diff --git a/.kiro/specs/nodejs24-actions-upgrade/design.md b/.kiro/specs/nodejs24-actions-upgrade/design.md deleted file mode 100644 index 00cbad2c..00000000 --- a/.kiro/specs/nodejs24-actions-upgrade/design.md +++ /dev/null @@ -1,139 +0,0 @@ -# Design Document: Node.js 24 GitHub Actions Upgrade - -## Overview - -This feature upgrades all third-party GitHub Actions across 10 workflow files and 1 composite action from Node.js 20-based versions to Node.js 24-compatible versions. The change is a mechanical version-tag bump in YAML `uses:` clauses plus adding the `FORCE_JAVASCRIPT_ACTIONS_TO_NODE24: true` environment variable to each workflow for early opt-in validation. - -No application code, shell scripts, CDK stacks, or runtime behavior changes. The workflows remain thin wrappers around `scripts/` — only the action version tags and a single env var are touched. - -### Motivation - -GitHub will force Node.js 24 as the JavaScript Actions runtime on June 2nd, 2026. Every workflow run currently emits deprecation warnings for actions still on Node.js 20. Upgrading now eliminates warnings and validates compatibility ahead of the deadline. - -## Architecture - -The change has no architectural impact. The existing workflow architecture (modular, job-centric, artifact-driven, script-based) is preserved exactly. The only modification is the version suffix on `uses:` references and a new top-level `env:` entry. - -```mermaid -graph LR - subgraph "Change Scope" - A["uses: actions/checkout@v4"] -->|bump| B["uses: actions/checkout@v5"] - C["uses: actions/cache/*@v4"] -->|bump| D["uses: actions/cache/*@v5"] - E["uses: actions/upload-artifact@v4"] -->|bump| F["uses: actions/upload-artifact@v5"] - G["uses: actions/download-artifact@v4"] -->|bump| H["uses: actions/download-artifact@v5"] - I["uses: actions/setup-python@v5"] -->|bump| J["uses: actions/setup-python@v6"] - K["uses: actions/setup-node@v4"] -->|bump| L["uses: actions/setup-node@v5"] - M["uses: docker/setup-buildx-action@v3"] -->|bump| N["uses: docker/setup-buildx-action@v4"] - O["uses: docker/build-push-action@v6"] -->|bump| P["uses: docker/build-push-action@v7"] - Q["uses: aws-actions/configure-aws-credentials@v4"] -->|bump| R["uses: aws-actions/configure-aws-credentials@v5"] - end -``` - -## Components and Interfaces - -### Version Mapping Table - -| Action | Current Version | Target Version | Files Affected | -|--------|----------------|----------------|----------------| -| `actions/checkout` | `@v4` | `@v5` | All 10 workflows | -| `actions/cache/save` | `@v4` | `@v5` | infrastructure, inference-api, app-api, frontend, gateway, rag-ingestion, sagemaker-fine-tuning, nightly | -| `actions/cache/restore` | `@v4` | `@v5` | infrastructure, inference-api, app-api, frontend, gateway, rag-ingestion, sagemaker-fine-tuning, nightly | -| `actions/cache` | `@v4` | `@v5` | nightly, gateway | -| `actions/upload-artifact` | `@v4` | `@v5` | infrastructure, inference-api, app-api, frontend, gateway, rag-ingestion, sagemaker-fine-tuning, nightly | -| `actions/download-artifact` | `@v4` | `@v5` | infrastructure, inference-api, app-api, frontend, gateway, rag-ingestion, sagemaker-fine-tuning, nightly | -| `actions/setup-python` | `@v5` | `@v6` | nightly | -| `actions/setup-node` | `@v4` | `@v5` | version-check | -| `docker/setup-buildx-action` | `@v3` | `@v4` | app-api, inference-api, rag-ingestion, nightly | -| `docker/build-push-action` | `@v6` | `@v7` | app-api, inference-api, rag-ingestion | -| `aws-actions/configure-aws-credentials` | `@v4` | `@v5` | composite action (2 occurrences) | - -### Files to Modify - -**Workflow files** (add `FORCE_JAVASCRIPT_ACTIONS_TO_NODE24: true` to top-level `env:` + bump action versions): -1. `.github/workflows/infrastructure.yml` -2. `.github/workflows/app-api.yml` -3. `.github/workflows/inference-api.yml` -4. `.github/workflows/frontend.yml` -5. `.github/workflows/gateway.yml` -6. `.github/workflows/rag-ingestion.yml` -7. `.github/workflows/sagemaker-fine-tuning.yml` -8. `.github/workflows/nightly.yml` -9. `.github/workflows/version-check.yml` -10. `.github/workflows/bootstrap-data-seeding.yml` - -**Composite action** (bump action versions only — no top-level `env:` in composite actions): -11. `.github/actions/configure-aws-credentials/action.yml` - -### Constraints - -- `version-check.yml`: After upgrading `actions/setup-node@v4` → `@v5`, the `node-version: '22'` parameter must be preserved. The action version controls the Node.js runtime for the action itself; the `node-version` input controls which Node.js is installed for the project. -- Composite actions (`using: 'composite'`) do not support top-level `env:` blocks, so `FORCE_JAVASCRIPT_ACTIONS_TO_NODE24` is only added to the 10 workflow files. -- All `with:` parameters (paths, keys, retention-days, platforms, build-args, etc.) remain unchanged. - -## Data Models - -No data model changes. This feature modifies only YAML configuration files. The data flowing through workflows (artifacts, caches, Docker images, CDK outputs) is unchanged. - - -## Correctness Properties - -*A property is a characteristic or behavior that should hold true across all valid executions of a system — essentially, a formal statement about what the system should do. Properties serve as the bridge between human-readable specifications and machine-verifiable correctness guarantees.* - -### Property 1: Zero deprecated action version references - -*For any* YAML file in `.github/workflows/` or `.github/actions/`, the file shall contain zero occurrences of any of the following deprecated version tags: `actions/checkout@v4`, `actions/cache@v4`, `actions/cache/save@v4`, `actions/cache/restore@v4`, `actions/upload-artifact@v4`, `actions/download-artifact@v4`, `actions/setup-python@v5`, `actions/setup-node@v4`, `docker/setup-buildx-action@v3`, `docker/build-push-action@v6`, or `aws-actions/configure-aws-credentials@v4`. - -**Validates: Requirements 1.1, 1.2, 1.3, 1.4, 1.5, 1.6, 2.1, 2.2, 3.1, 4.1, 4.2, 4.3, 7.1, 7.2, 7.3, 7.4, 7.5, 7.6** - -### Property 2: Node.js 24 opt-in flag present in all workflows - -*For any* workflow file in `.github/workflows/`, the top-level `env:` block shall contain the key `FORCE_JAVASCRIPT_ACTIONS_TO_NODE24` set to `true`. - -**Validates: Requirements 5.1** - -### Property 3: Workflow structure preservation - -*For any* workflow file, all YAML content outside of action version tags in `uses:` clauses and the added `FORCE_JAVASCRIPT_ACTIONS_TO_NODE24` env entry shall be identical before and after the upgrade. This includes `on:` triggers, `needs:` dependency chains, `with:` parameters, `concurrency:` groups, `permissions:` declarations, and `environment:` selection logic. - -**Validates: Requirements 6.1, 6.2, 6.3, 6.4, 6.5, 6.6, 6.7** - -## Error Handling - -This feature has minimal error surface since it is a static YAML edit with no runtime logic: - -- **Invalid version tag**: If a target version (e.g., `@v5`) does not exist on the action's repository at the time of workflow execution, GitHub Actions will fail the job with a clear "Unable to resolve action" error. Mitigation: verify each target version exists before merging. -- **Breaking API changes**: A major version bump could introduce breaking changes to action inputs/outputs. Mitigation: review each action's release notes for breaking changes. The actions in scope (`actions/checkout`, `actions/cache`, etc.) historically maintain backward compatibility across major versions for core `with:` parameters. -- **Composite action compatibility**: The composite action does not have its own `env:` block, so the `FORCE_JAVASCRIPT_ACTIONS_TO_NODE24` flag propagates from the calling workflow. No special handling needed. - -## Testing Strategy - -### Verification Approach - -Since this is a YAML-only change with no application logic, testing focuses on static validation rather than runtime behavior. - -### Unit Tests (specific examples) - -- Verify `version-check.yml` still has `node-version: '22'` in the `actions/setup-node` step after upgrade. -- Verify the composite action file has exactly 2 occurrences of `aws-actions/configure-aws-credentials@v5`. -- Verify `bootstrap-data-seeding.yml` (which has no existing top-level `env:` block) correctly receives the `FORCE_JAVASCRIPT_ACTIONS_TO_NODE24: true` entry. - -### Property Tests - -Property-based testing library: Since the files under test are YAML, a shell-based grep/scan approach or a lightweight YAML parser in Python (using `hypothesis` which is already in the project) is appropriate. - -Each property test should run against the full set of 11 target files (10 workflows + 1 composite action) and verify the property holds for every file and every action reference within each file. - -- **Property 1 test**: Parse all YAML files, extract every `uses:` value, and assert none match the deprecated version patterns. Minimum 100 iterations not applicable here since the input space is the fixed set of files, but the test should exhaustively check all files. - - Tag: **Feature: nodejs24-actions-upgrade, Property 1: Zero deprecated action version references** - -- **Property 2 test**: Parse all 10 workflow YAML files, extract the top-level `env:` block, and assert `FORCE_JAVASCRIPT_ACTIONS_TO_NODE24: true` is present. - - Tag: **Feature: nodejs24-actions-upgrade, Property 2: Node.js 24 opt-in flag present in all workflows** - -- **Property 3 test**: For each workflow file, compare the pre-upgrade and post-upgrade YAML with version tags and the new env var normalized out, and assert equality. - - Tag: **Feature: nodejs24-actions-upgrade, Property 3: Workflow structure preservation** - -### Dual Testing Note - -- Unit tests cover specific edge cases (node-version preservation, composite action occurrence count, env var in files without existing env block). -- Property tests cover universal invariants across all files (no deprecated refs, flag present everywhere, structure preserved). -- Both are complementary: unit tests catch concrete regressions, property tests verify general correctness across the full file set. diff --git a/.kiro/specs/nodejs24-actions-upgrade/requirements.md b/.kiro/specs/nodejs24-actions-upgrade/requirements.md deleted file mode 100644 index 06b65778..00000000 --- a/.kiro/specs/nodejs24-actions-upgrade/requirements.md +++ /dev/null @@ -1,93 +0,0 @@ -# Requirements Document - -## Introduction - -GitHub is deprecating Node.js 20 as the runtime for JavaScript-based GitHub Actions. Starting June 2nd, 2026, Node.js 24 becomes the forced default. Every workflow run currently emits deprecation warnings for actions still running on Node.js 20. This feature upgrades all third-party actions across the repository's 10 workflows and 1 custom composite action to versions that ship with Node.js 24 support, and enables the `FORCE_JAVASCRIPT_ACTIONS_TO_NODE24` environment variable to opt in early and validate compatibility before the deadline. - -## Glossary - -- **Workflow**: A GitHub Actions YAML file in `.github/workflows/` that defines a CI/CD pipeline. -- **Composite_Action**: A reusable action defined with `using: 'composite'` in `.github/actions/`, which delegates to shell steps and other actions but does not declare its own Node.js runtime. -- **Third_Party_Action**: A GitHub Action published by an external organization (e.g., `actions/checkout`, `docker/setup-buildx-action`) referenced by `owner/name@version` in workflow `uses:` clauses. -- **Action_Version_Tag**: The `@vN` suffix on a `uses:` reference that pins to a major version of a third-party action (e.g., `@v4`, `@v5`). -- **Node24_Opt_In_Flag**: The `FORCE_JAVASCRIPT_ACTIONS_TO_NODE24` environment variable that, when set to `true`, forces all JavaScript actions to run on Node.js 24 before the June 2nd, 2026 deadline. -- **Deprecation_Warning**: The annotation GitHub emits on every workflow run stating "Node.js 20 actions are deprecated." - -## Requirements - -### Requirement 1: Upgrade GitHub Official Actions to Node.js 24-Compatible Versions - -**User Story:** As a DevOps engineer, I want all GitHub official actions upgraded to versions that support Node.js 24, so that workflows stop emitting deprecation warnings and are ready for the June 2nd forced switch. - -#### Acceptance Criteria - -1. WHEN a workflow references `actions/checkout`, THE Workflow SHALL use `actions/checkout@v5` or a later Node.js 24-compatible version. -2. WHEN a workflow references `actions/cache@v4`, `actions/cache/save@v4`, or `actions/cache/restore@v4`, THE Workflow SHALL use the equivalent `@v5` (or later Node.js 24-compatible) version of each cache action. -3. WHEN a workflow references `actions/upload-artifact@v4`, THE Workflow SHALL use `actions/upload-artifact@v5` or a later Node.js 24-compatible version. -4. WHEN a workflow references `actions/download-artifact@v4`, THE Workflow SHALL use `actions/download-artifact@v5` or a later Node.js 24-compatible version. -5. WHEN a workflow references `actions/setup-python@v5`, THE Workflow SHALL use `actions/setup-python@v6` or a later Node.js 24-compatible version if the current version does not support Node.js 24, or retain `@v5` if it already ships with Node.js 24 support. -6. WHEN a workflow references `actions/setup-node@v4`, THE Workflow SHALL use `actions/setup-node@v5` or a later Node.js 24-compatible version. - -### Requirement 2: Upgrade Docker Actions to Node.js 24-Compatible Versions - -**User Story:** As a DevOps engineer, I want Docker-related actions upgraded to Node.js 24-compatible versions, so that container build workflows are compatible with the new runtime. - -#### Acceptance Criteria - -1. WHEN a workflow references `docker/setup-buildx-action@v3`, THE Workflow SHALL use `docker/setup-buildx-action@v4` or a later Node.js 24-compatible version. -2. WHEN a workflow references `docker/build-push-action@v6`, THE Workflow SHALL use `docker/build-push-action@v7` or a later Node.js 24-compatible version if the current version does not support Node.js 24, or retain `@v6` if it already ships with Node.js 24 support. - -### Requirement 3: Upgrade AWS Actions to Node.js 24-Compatible Versions - -**User Story:** As a DevOps engineer, I want the AWS credential configuration action upgraded to a Node.js 24-compatible version, so that all AWS authentication steps work under the new runtime. - -#### Acceptance Criteria - -1. WHEN the Composite_Action references `aws-actions/configure-aws-credentials@v4`, THE Composite_Action SHALL use `aws-actions/configure-aws-credentials@v5` or a later Node.js 24-compatible version. - -### Requirement 4: Apply Upgrades Across All Workflows - -**User Story:** As a DevOps engineer, I want every occurrence of each action updated consistently across all 10 workflows and the composite action, so that no workflow is left running deprecated Node.js 20 actions. - -#### Acceptance Criteria - -1. THE Upgrade SHALL update action references in all 10 workflow files: `infrastructure.yml`, `app-api.yml`, `inference-api.yml`, `frontend.yml`, `gateway.yml`, `rag-ingestion.yml`, `sagemaker-fine-tuning.yml`, `nightly.yml`, `version-check.yml`, and `bootstrap-data-seeding.yml`. -2. THE Upgrade SHALL update action references in the Composite_Action file `.github/actions/configure-aws-credentials/action.yml`. -3. IF a workflow file contains multiple references to the same action at the old version, THEN THE Upgrade SHALL update every occurrence in that file. - -### Requirement 5: Enable Node.js 24 Opt-In for Early Validation - -**User Story:** As a DevOps engineer, I want to opt in to Node.js 24 early using the `FORCE_JAVASCRIPT_ACTIONS_TO_NODE24` flag, so that I can validate all workflows run correctly on Node.js 24 before GitHub forces the switch. - -#### Acceptance Criteria - -1. THE Upgrade SHALL add `FORCE_JAVASCRIPT_ACTIONS_TO_NODE24: true` as a top-level `env:` variable in each of the 10 workflow files. -2. WHEN the Node24_Opt_In_Flag is set to `true`, THE Workflow SHALL force all JavaScript-based actions in that run to execute on the Node.js 24 runtime. -3. WHILE the Node24_Opt_In_Flag is set to `true` in all workflows, THE Repository SHALL produce zero Deprecation_Warning annotations on workflow runs. - -### Requirement 6: Preserve Existing Workflow Behavior - -**User Story:** As a DevOps engineer, I want the upgrade to preserve all existing workflow behavior (triggers, job structure, caching, artifact passing, environment selection, concurrency controls), so that the upgrade is a safe, non-breaking change. - -#### Acceptance Criteria - -1. THE Upgrade SHALL preserve all `on:` trigger configurations (push, pull_request, workflow_dispatch, schedule, workflow_call) in every workflow. -2. THE Upgrade SHALL preserve all job dependency chains (`needs:` declarations) in every workflow. -3. THE Upgrade SHALL preserve all `with:` parameters (paths, keys, retention-days, restore-keys, platforms, build-args, outputs) passed to each action. -4. THE Upgrade SHALL preserve all `concurrency:` group configurations in every workflow. -5. THE Upgrade SHALL preserve all `permissions:` declarations in every workflow. -6. THE Upgrade SHALL preserve all `environment:` selection logic in every workflow. -7. WHEN `actions/setup-node@v4` is upgraded in `version-check.yml`, THE Workflow SHALL continue to set `node-version: '22'` for the project build tools. - -### Requirement 7: Verify No Deprecated Node.js 20 Action References Remain - -**User Story:** As a DevOps engineer, I want to confirm that no workflow or composite action still references a Node.js 20-only action version after the upgrade, so that the repository is fully prepared for the June 2nd deadline. - -#### Acceptance Criteria - -1. WHEN the upgrade is complete, THE Repository SHALL contain zero references to `actions/checkout@v4` across all workflow and action YAML files. -2. WHEN the upgrade is complete, THE Repository SHALL contain zero references to `actions/cache@v4`, `actions/cache/save@v4`, or `actions/cache/restore@v4` across all workflow and action YAML files. -3. WHEN the upgrade is complete, THE Repository SHALL contain zero references to `actions/upload-artifact@v4` or `actions/download-artifact@v4` across all workflow and action YAML files. -4. WHEN the upgrade is complete, THE Repository SHALL contain zero references to `actions/setup-node@v4` across all workflow and action YAML files. -5. WHEN the upgrade is complete, THE Repository SHALL contain zero references to `docker/setup-buildx-action@v3` across all workflow and action YAML files. -6. WHEN the upgrade is complete, THE Repository SHALL contain zero references to `aws-actions/configure-aws-credentials@v4` across all workflow and action YAML files. diff --git a/.kiro/specs/nodejs24-actions-upgrade/tasks.md b/.kiro/specs/nodejs24-actions-upgrade/tasks.md deleted file mode 100644 index d556e4df..00000000 --- a/.kiro/specs/nodejs24-actions-upgrade/tasks.md +++ /dev/null @@ -1,146 +0,0 @@ -# Implementation Plan: Node.js 24 GitHub Actions Upgrade - -## Overview - -Mechanical upgrade of GitHub Actions third-party action version tags from Node.js 20 to Node.js 24 compatible versions across 10 workflow files and 1 composite action. Each workflow gets action version bumps plus the `FORCE_JAVASCRIPT_ACTIONS_TO_NODE24: true` env var. The composite action gets version bumps only. Property-based tests validate correctness using Python's `hypothesis` library. - -## Tasks - -- [x] 1. Upgrade composite action (dependency for all workflows) - - [x] 1.1 Update `.github/actions/configure-aws-credentials/action.yml` to use `aws-actions/configure-aws-credentials@v5` - - Replace both occurrences of `aws-actions/configure-aws-credentials@v4` with `@v5` (OIDC step and Access Keys step) - - Preserve all `with:` parameters, `if:` conditions, and step names - - Do NOT add `FORCE_JAVASCRIPT_ACTIONS_TO_NODE24` (composite actions don't support top-level `env:`) - - _Requirements: 3.1, 4.2_ - -- [x] 2. Upgrade infrastructure and CDK-only workflows - - [x] 2.1 Update `.github/workflows/infrastructure.yml` - - Bump `actions/checkout@v4` → `@v5` (all occurrences) - - Bump `actions/cache/save@v4` → `@v5`, `actions/cache/restore@v4` → `@v5` - - Bump `actions/upload-artifact@v4` → `@v5`, `actions/download-artifact@v4` → `@v5` - - Add `FORCE_JAVASCRIPT_ACTIONS_TO_NODE24: true` to the top-level `env:` block - - Preserve all `with:` parameters, `on:` triggers, `needs:`, `concurrency:`, `permissions:`, `environment:` logic - - _Requirements: 1.1, 1.2, 1.3, 1.4, 4.1, 4.3, 5.1, 6.1, 6.2, 6.3, 6.4, 6.5, 6.6_ - - - [x] 2.2 Update `.github/workflows/sagemaker-fine-tuning.yml` - - Bump `actions/checkout@v4` → `@v5` (all occurrences) - - Bump `actions/cache/save@v4` → `@v5`, `actions/cache/restore@v4` → `@v5` - - Bump `actions/upload-artifact@v4` → `@v5`, `actions/download-artifact@v4` → `@v5` - - Add `FORCE_JAVASCRIPT_ACTIONS_TO_NODE24: true` to the top-level `env:` block - - _Requirements: 1.1, 1.2, 1.3, 1.4, 4.1, 4.3, 5.1, 6.1, 6.2, 6.3, 6.4, 6.5, 6.6_ - - - [x] 2.3 Update `.github/workflows/version-check.yml` - - Bump `actions/checkout@v4` → `@v5` - - Bump `actions/setup-node@v4` → `@v5` - - CRITICAL: Preserve `node-version: '22'` in the `actions/setup-node` step — this controls the installed Node.js version, not the action runtime - - Add `FORCE_JAVASCRIPT_ACTIONS_TO_NODE24: true` as a new top-level `env:` block (this file currently has no top-level `env:`) - - _Requirements: 1.1, 1.6, 4.1, 5.1, 6.3, 6.7_ - - - [x] 2.4 Update `.github/workflows/bootstrap-data-seeding.yml` - - Bump `actions/checkout@v4` → `@v5` - - Add `FORCE_JAVASCRIPT_ACTIONS_TO_NODE24: true` as a new top-level `env:` block (this file currently has no top-level `env:`) - - _Requirements: 1.1, 4.1, 5.1_ - -- [x] 3. Checkpoint - Verify composite action and simple workflows - - Ensure all modified files are valid YAML - - Grep for any remaining `@v4` references in the files updated so far - - Ensure all tests pass, ask the user if questions arise. - -- [x] 4. Upgrade Docker-build workflows - - [x] 4.1 Update `.github/workflows/app-api.yml` - - Bump `actions/checkout@v4` → `@v5` (all occurrences) - - Bump `actions/cache/save@v4` → `@v5`, `actions/cache/restore@v4` → `@v5` - - Bump `actions/upload-artifact@v4` → `@v5`, `actions/download-artifact@v4` → `@v5` - - Bump `docker/setup-buildx-action@v3` → `@v4` - - Bump `docker/build-push-action@v6` → `@v7` - - Add `FORCE_JAVASCRIPT_ACTIONS_TO_NODE24: true` to the top-level `env:` block - - _Requirements: 1.1, 1.2, 1.3, 1.4, 2.1, 2.2, 4.1, 4.3, 5.1, 6.1, 6.2, 6.3, 6.4, 6.5, 6.6_ - - - [x] 4.2 Update `.github/workflows/inference-api.yml` - - Bump `actions/checkout@v4` → `@v5` (all occurrences) - - Bump `actions/cache/save@v4` → `@v5`, `actions/cache/restore@v4` → `@v5` - - Bump `actions/upload-artifact@v4` → `@v5`, `actions/download-artifact@v4` → `@v5` - - Bump `docker/setup-buildx-action@v3` → `@v4` - - Bump `docker/build-push-action@v6` → `@v7` - - Add `FORCE_JAVASCRIPT_ACTIONS_TO_NODE24: true` to the top-level `env:` block - - _Requirements: 1.1, 1.2, 1.3, 1.4, 2.1, 2.2, 4.1, 4.3, 5.1, 6.1, 6.2, 6.3, 6.4, 6.5, 6.6_ - - - [x] 4.3 Update `.github/workflows/rag-ingestion.yml` - - Bump `actions/checkout@v4` → `@v5` (all occurrences) - - Bump `actions/cache/save@v4` → `@v5`, `actions/cache/restore@v4` → `@v5` - - Bump `actions/upload-artifact@v4` → `@v5`, `actions/download-artifact@v4` → `@v5` - - Bump `docker/setup-buildx-action@v3` → `@v4` - - Bump `docker/build-push-action@v6` → `@v7` - - Add `FORCE_JAVASCRIPT_ACTIONS_TO_NODE24: true` to the top-level `env:` block - - _Requirements: 1.1, 1.2, 1.3, 1.4, 2.1, 2.2, 4.1, 4.3, 5.1, 6.1, 6.2, 6.3, 6.4, 6.5, 6.6_ - -- [x] 5. Upgrade remaining workflows (frontend, gateway, nightly) - - [x] 5.1 Update `.github/workflows/frontend.yml` - - Bump `actions/checkout@v4` → `@v5` (all occurrences) - - Bump `actions/cache/save@v4` → `@v5`, `actions/cache/restore@v4` → `@v5` - - Bump `actions/upload-artifact@v4` → `@v5`, `actions/download-artifact@v4` → `@v5` - - Add `FORCE_JAVASCRIPT_ACTIONS_TO_NODE24: true` to the top-level `env:` block - - _Requirements: 1.1, 1.2, 1.3, 1.4, 4.1, 4.3, 5.1, 6.1, 6.2, 6.3, 6.4, 6.5, 6.6_ - - - [x] 5.2 Update `.github/workflows/gateway.yml` - - Bump `actions/checkout@v4` → `@v5` (all occurrences) - - Bump `actions/cache/save@v4` → `@v5`, `actions/cache@v4` → `@v5` - - Bump `actions/upload-artifact@v4` → `@v5`, `actions/download-artifact@v4` → `@v5` - - Add `FORCE_JAVASCRIPT_ACTIONS_TO_NODE24: true` to the top-level `env:` block - - _Requirements: 1.1, 1.2, 1.3, 1.4, 4.1, 4.3, 5.1, 6.1, 6.2, 6.3, 6.4, 6.5, 6.6_ - - - [x] 5.3 Update `.github/workflows/nightly.yml` - - Bump `actions/checkout@v4` → `@v5` (all occurrences) - - Bump `actions/cache/save@v4` → `@v5`, `actions/cache/restore@v4` → `@v5`, `actions/cache@v4` → `@v5` - - Bump `actions/upload-artifact@v4` → `@v5`, `actions/download-artifact@v4` → `@v5` - - Bump `actions/setup-python@v5` → `@v6` - - Bump `docker/setup-buildx-action@v3` → `@v4` - - Add `FORCE_JAVASCRIPT_ACTIONS_TO_NODE24: true` to the top-level `env:` block - - _Requirements: 1.1, 1.2, 1.3, 1.4, 1.5, 2.1, 4.1, 4.3, 5.1, 6.1, 6.2, 6.3, 6.4, 6.5, 6.6_ - -- [x] 6. Checkpoint - Verify all files upgraded - - Run grep across all `.github/workflows/*.yml` and `.github/actions/**/*.yml` for deprecated version patterns - - Confirm zero matches for: `actions/checkout@v4`, `actions/cache@v4`, `actions/cache/save@v4`, `actions/cache/restore@v4`, `actions/upload-artifact@v4`, `actions/download-artifact@v4`, `actions/setup-python@v5`, `actions/setup-node@v4`, `docker/setup-buildx-action@v3`, `docker/build-push-action@v6`, `aws-actions/configure-aws-credentials@v4` - - Ensure all tests pass, ask the user if questions arise. - - _Requirements: 7.1, 7.2, 7.3, 7.4, 7.5, 7.6_ - -- [x] 7. Write property-based tests - - [x] 7.1 Create test file `backend/tests/test_nodejs24_actions_upgrade.py` with shared fixtures - - Create a pytest fixture that loads all 11 target YAML files (10 workflows + 1 composite action) - - Define the complete list of deprecated version patterns and target version patterns as constants - - Define the list of workflow files (excluding composite action) for env var tests - - _Requirements: 4.1, 4.2_ - - - [x] 7.2 Write property test: Zero deprecated action version references (Property 1) - - **Property 1: Zero deprecated action version references** - - Use `hypothesis` with `@given(sampled_from(all_target_files))` to select a file - - Parse YAML, extract all `uses:` values, assert none match deprecated patterns - - Exhaustively verify across all 11 files - - **Validates: Requirements 1.1, 1.2, 1.3, 1.4, 1.5, 1.6, 2.1, 2.2, 3.1, 4.1, 4.2, 4.3, 7.1, 7.2, 7.3, 7.4, 7.5, 7.6** - - - [x] 7.3 Write property test: Node.js 24 opt-in flag present in all workflows (Property 2) - - **Property 2: Node.js 24 opt-in flag present in all workflows** - - Use `hypothesis` with `@given(sampled_from(workflow_files))` to select a workflow file (10 files, excluding composite action) - - Parse YAML, check top-level `env:` block contains `FORCE_JAVASCRIPT_ACTIONS_TO_NODE24: true` - - **Validates: Requirements 5.1** - - - [x] 7.4 Write property test: Workflow structure preservation (Property 3) - - **Property 3: Workflow structure preservation** - - Use `hypothesis` with `@given(sampled_from(workflow_files))` to select a workflow file - - Parse YAML, verify `on:` triggers, `jobs:` keys, `needs:` chains, `concurrency:`, `permissions:`, and `environment:` are present and structurally intact - - Verify `version-check.yml` still has `node-version: '22'` in the `setup-node` step - - **Validates: Requirements 6.1, 6.2, 6.3, 6.4, 6.5, 6.6, 6.7** - -- [x] 8. Final checkpoint - Ensure all tests pass - - Run `python -m pytest backend/tests/test_nodejs24_actions_upgrade.py -v` to verify all property tests pass - - Ensure all tests pass, ask the user if questions arise. - -## Notes - -- Tasks marked with `*` are optional and can be skipped for faster MVP -- Each task references specific requirements for traceability -- The composite action is upgraded first since workflows depend on it -- `version-check.yml` and `bootstrap-data-seeding.yml` need special handling: they have no existing top-level `env:` block, so one must be created -- `gateway.yml` uses `actions/cache@v4` (not `cache/save` or `cache/restore`) in some jobs — all variants must be bumped -- Property tests use Python `hypothesis` library (already installed in the project) -- Git commands run locally on the host machine, NOT in a dev container diff --git a/.kiro/specs/rag-ingestion-stack/DEPLOYMENT_GUIDE.md b/.kiro/specs/rag-ingestion-stack/DEPLOYMENT_GUIDE.md deleted file mode 100644 index e0f50605..00000000 --- a/.kiro/specs/rag-ingestion-stack/DEPLOYMENT_GUIDE.md +++ /dev/null @@ -1,464 +0,0 @@ -# RAG Ingestion Stack - Deployment Guide - -## Overview - -This guide provides step-by-step instructions for deploying the RAG Ingestion Stack to AWS. The implementation is complete, and all code has been written. This guide covers the remaining manual deployment and verification steps. - -## Implementation Status - -✅ **All implementation tasks complete (Tasks 1-11)** - -The following have been implemented: -- CDK stack code (`infrastructure/lib/rag-ingestion-stack.ts`) -- Configuration management (`infrastructure/lib/config.ts`) -- CI/CD workflow (`.github/workflows/rag-ingestion.yml`) -- Shell scripts (`scripts/stack-rag-ingestion/`) -- Unit tests (`infrastructure/test/rag-ingestion-stack.test.ts`) -- Property-based tests (all 6 properties implemented) -- Stack registration in CDK app - -## Prerequisites - -Before deploying, ensure you have: - -### 1. AWS Infrastructure -- ✅ Infrastructure Stack deployed (provides VPC and network resources) -- ✅ AWS account with appropriate permissions -- ✅ AWS CLI configured with credentials - -### 2. GitHub Configuration - -**GitHub Variables** (Settings → Secrets and variables → Actions → Variables): -``` -CDK_PROJECT_PREFIX = bsu-agentcore (or your project prefix) -CDK_VPC_CIDR = 10.0.0.0/16 (or your VPC CIDR) -CDK_RAG_ENABLED = true -CDK_RAG_CORS_ORIGINS = https://your-frontend-domain.com -AWS_REGION = us-west-2 (or your region) -``` - -**GitHub Secrets** (Settings → Secrets and variables → Actions → Secrets): -``` -CDK_AWS_ACCOUNT = 123456789012 (your AWS account ID) -AWS_ROLE_ARN = arn:aws:iam::123456789012:role/GitHubActionsRole (if using OIDC) -AWS_ACCESS_KEY_ID = AKIA... (your AWS access key) -AWS_SECRET_ACCESS_KEY = ... (your AWS secret key) -``` - -### 3. Local Environment (for testing) -```bash -# Install dependencies -cd infrastructure -npm install - -cd ../backend -uv sync - -# Set environment variables -export CDK_PROJECT_PREFIX="bsu-agentcore" -export CDK_AWS_REGION="us-west-2" -export CDK_AWS_ACCOUNT="123456789012" -export CDK_RAG_ENABLED="true" -export CDK_RAG_CORS_ORIGINS="https://your-frontend.com" -``` - -## Deployment Steps - -### Step 1: Test CI/CD Pipeline (Task 12) - -**Purpose:** Verify the workflow runs successfully without deploying to AWS. - -1. **Create a feature branch:** - ```bash - git checkout -b feature/rag-ingestion-test - ``` - -2. **Push to GitHub:** - ```bash - git push origin feature/rag-ingestion-test - ``` - -3. **Create a Pull Request** to trigger the workflow - -4. **Monitor the workflow** in GitHub Actions: - - Go to Actions tab in GitHub - - Watch the "RagIngestionStack.BuildTest.Deploy" workflow - - Verify all jobs pass: - - ✅ install - - ✅ build-docker - - ✅ build-cdk - - ✅ test-docker - - ✅ test-cdk - - ✅ synth-cdk - - ✅ push-to-ecr - - ⏭️ deploy-infrastructure (skipped for PR) - -5. **Expected Results:** - - Docker image builds successfully (ARM64 architecture) - - CDK templates synthesize without errors - - All tests pass - - Image pushed to ECR - - Deployment skipped (only runs on main branch) - -**Troubleshooting:** -- If build-docker fails: Check Dockerfile.rag-ingestion syntax -- If test-cdk fails: Check CloudFormation template validity -- If push-to-ecr fails: Verify AWS credentials and ECR permissions - -### Step 2: Deploy to AWS (Task 13) - -**Purpose:** Deploy the RAG Ingestion Stack to AWS. - -1. **Merge the PR to main:** - ```bash - git checkout main - git merge feature/rag-ingestion-test - git push origin main - ``` - -2. **Monitor the deployment workflow:** - - Go to Actions tab in GitHub - - Watch the workflow triggered by the push to main - - This time, the deploy-infrastructure job will run - -3. **Verify deployment succeeds:** - - Check the workflow completes successfully - - Review the deployment summary in GitHub Actions - - Download the deployment outputs artifact - -4. **Check CloudFormation in AWS Console:** - - Go to CloudFormation service - - Find stack: `{ProjectPrefix}-RagIngestionStack` - - Status should be: `CREATE_COMPLETE` or `UPDATE_COMPLETE` - - Review the Resources tab - -**Alternative: Manual Deployment** - -If you prefer to deploy manually: - -```bash -# From project root -cd infrastructure - -# Synthesize the stack -bash ../scripts/stack-rag-ingestion/synth.sh - -# Deploy the stack -bash ../scripts/stack-rag-ingestion/deploy.sh -``` - -### Step 3: Verify Deployed Resources (Task 14) - -**Purpose:** Confirm all AWS resources were created correctly. - -1. **S3 Documents Bucket:** - ```bash - aws s3 ls | grep rag-documents - # Expected: bsu-agentcore-rag-documents - - aws s3api get-bucket-versioning --bucket ${CDK_PROJECT_PREFIX}-rag-documents - # Expected: Status: Enabled - ``` - -2. **DynamoDB Assistants Table:** - ```bash - aws dynamodb describe-table --table-name ${CDK_PROJECT_PREFIX}-rag-assistants - # Verify: TableStatus: ACTIVE - # Verify: 3 Global Secondary Indexes - ``` - -3. **Lambda Function:** - ```bash - aws lambda get-function --function-name ${CDK_PROJECT_PREFIX}-rag-ingestion - # Verify: State: Active - # Verify: Architecture: arm64 - # Verify: MemorySize: 10240 - # Verify: Timeout: 900 - ``` - -4. **S3 Vectors (if available in your region):** - ```bash - # Note: S3 Vectors may not be available in all regions yet - # Check AWS Console for S3 Vectors service - ``` - -5. **SSM Parameters:** - ```bash - aws ssm get-parameters-by-path --path /${CDK_PROJECT_PREFIX}/rag/ --recursive - # Expected: 7 parameters - # - documents-bucket-name - # - documents-bucket-arn - # - assistants-table-name - # - assistants-table-arn - # - vector-bucket-name - # - vector-index-name - # - ingestion-lambda-arn - ``` - -6. **CloudWatch Logs:** - ```bash - aws logs describe-log-groups --log-group-name-prefix /aws/lambda/${CDK_PROJECT_PREFIX}-rag-ingestion - # Verify log group exists - ``` - -### Step 4: Test Lambda Function (Task 15) - -**Purpose:** Verify the Lambda function can process documents successfully. - -1. **Create a test document:** - ```bash - echo "This is a test document for RAG ingestion." > test-document.txt - ``` - -2. **Upload to S3 with correct prefix:** - ```bash - # Note: Use "assistants/" prefix to trigger Lambda - aws s3 cp test-document.txt s3://${CDK_PROJECT_PREFIX}-rag-documents/assistants/test-assistant-id/test-doc-id/test-document.txt - ``` - -3. **Monitor Lambda execution:** - ```bash - # Wait a few seconds for Lambda to trigger - sleep 10 - - # Check CloudWatch Logs - aws logs tail /aws/lambda/${CDK_PROJECT_PREFIX}-rag-ingestion --follow - ``` - -4. **Verify Lambda processed the document:** - - Check logs for successful execution - - Look for embedding generation messages - - Verify no errors in logs - -5. **Verify embeddings stored:** - ```bash - # Check DynamoDB for metadata - aws dynamodb scan --table-name ${CDK_PROJECT_PREFIX}-rag-assistants --limit 10 - # Look for items related to test-assistant-id - ``` - -6. **Query vector store (if available):** - ```bash - # This depends on S3 Vectors API availability - # Check AWS documentation for S3 Vectors query commands - ``` - -**Expected Results:** -- Lambda invoked successfully -- Document processed without errors -- Embeddings generated using Bedrock Titan -- Metadata stored in DynamoDB -- Vectors stored in S3 Vectors - -**Troubleshooting:** -- If Lambda doesn't trigger: Check S3 event notification configuration -- If Lambda fails: Check CloudWatch Logs for error details -- If Bedrock fails: Verify IAM permissions for bedrock:InvokeModel -- If vector store fails: Verify S3 Vectors permissions - -### Step 5: Final Verification (Task 16) - -**Purpose:** Ensure the new stack doesn't interfere with existing resources. - -1. **Verify existing AppApiStack resources unchanged:** - ```bash - # Check existing assistants bucket (if it exists) - aws s3 ls | grep assistants-documents - - # Check existing assistants table (if it exists) - aws dynamodb describe-table --table-name ${CDK_PROJECT_PREFIX}-assistants 2>/dev/null || echo "Table doesn't exist (expected)" - ``` - -2. **Verify no naming conflicts:** - ```bash - # List all resources with project prefix - aws resourcegroupstaggingapi get-resources --tag-filters Key=Project,Values=${CDK_PROJECT_PREFIX} - - # Verify new resources use "rag-" prefix - # Verify old resources use "assistants-" prefix (if they exist) - ``` - -3. **Verify existing RAG functionality still works (if applicable):** - - If you have existing RAG implementation in AppApiStack - - Test that it still processes documents correctly - - Verify no disruption to existing services - -4. **Test independent operation:** - - Upload document to new RAG stack - - Verify it processes independently - - Verify no cross-contamination with old stack - -5. **Document any issues:** - - Create a verification report - - Note any unexpected behavior - - Document any configuration changes needed - -## Post-Deployment Configuration - -### Update cdk.context.json (Optional) - -Add explicit RAG configuration to `infrastructure/cdk.context.json`: - -```json -{ - "ragIngestion": { - "enabled": true, - "corsOrigins": "https://your-frontend.com,https://your-admin.com", - "lambdaMemorySize": 10240, - "lambdaTimeout": 900, - "embeddingModel": "amazon.titan-embed-text-v2", - "vectorDimension": 1024, - "vectorDistanceMetric": "cosine" - } -} -``` - -### Configure Monitoring (Recommended) - -1. **Create CloudWatch Dashboard:** - ```bash - # Create a dashboard for RAG metrics - # Include: Lambda invocations, errors, duration - # Include: DynamoDB read/write capacity - # Include: S3 bucket requests - ``` - -2. **Set up CloudWatch Alarms:** - ```bash - # Lambda error rate > 5% - # Lambda duration > 10 minutes - # DynamoDB throttling - ``` - -3. **Enable X-Ray tracing (optional):** - ```bash - aws lambda update-function-configuration \ - --function-name ${CDK_PROJECT_PREFIX}-rag-ingestion \ - --tracing-config Mode=Active - ``` - -## Rollback Procedure - -If deployment fails or issues arise: - -### Automatic Rollback -CloudFormation automatically rolls back on deployment failure. No action needed. - -### Manual Rollback -```bash -# Delete the stack -aws cloudformation delete-stack --stack-name ${CDK_PROJECT_PREFIX}-RagIngestionStack - -# Wait for deletion to complete -aws cloudformation wait stack-delete-complete --stack-name ${CDK_PROJECT_PREFIX}-RagIngestionStack - -# Verify resources deleted -aws s3 ls | grep rag-documents # Should not exist -aws dynamodb list-tables | grep rag-assistants # Should not exist -``` - -### Rollback Considerations -- S3 bucket has RETAIN policy - must be deleted manually if needed -- DynamoDB table has RETAIN policy in prod - must be deleted manually -- ECR images remain - can be deleted manually if needed - -## Troubleshooting Guide - -### Common Issues - -#### 1. Stack Synthesis Fails -**Symptom:** `cdk synth` fails with errors - -**Solutions:** -- Check TypeScript compilation: `npm run build` -- Verify config.ts has all required fields -- Check SSM parameters exist (from Infrastructure Stack) - -#### 2. Docker Build Fails -**Symptom:** Docker build fails in CI/CD - -**Solutions:** -- Check Dockerfile.rag-ingestion syntax -- Verify base image is accessible -- Check Python dependencies in pyproject.toml - -#### 3. Lambda Function Fails -**Symptom:** Lambda invocations fail with errors - -**Solutions:** -- Check CloudWatch Logs for error details -- Verify environment variables are set correctly -- Check IAM permissions -- Verify Bedrock model is available in region - -#### 4. S3 Event Notification Not Working -**Symptom:** Lambda doesn't trigger on S3 upload - -**Solutions:** -- Verify S3 event notification is configured -- Check Lambda permission for S3 to invoke -- Verify prefix filter is "assistants/" -- Check Lambda function is active - -#### 5. Vector Store Errors -**Symptom:** Vector operations fail - -**Solutions:** -- Verify S3 Vectors is available in your region -- Check IAM permissions for s3vectors:* actions -- Verify vector bucket and index exist -- Check vector dimension matches Titan embeddings (1024) - -## Success Criteria - -✅ **Deployment Successful** when: -- CloudFormation stack status is CREATE_COMPLETE -- All resources created in AWS -- Lambda function can process documents -- Embeddings stored in vector store -- Metadata stored in DynamoDB -- SSM parameters exported correctly -- No interference with existing resources - -## Next Steps - -After successful deployment: - -1. **Integration with AppApiStack (Future Phase):** - - Update AppApiStack to use new RAG resources via SSM - - Test application with new RAG stack - - Migrate traffic to new stack - - Remove old RAG resources from AppApiStack - -2. **Performance Optimization:** - - Monitor Lambda execution times - - Optimize chunk size for embeddings - - Tune Lambda memory allocation - - Implement caching if needed - -3. **Cost Optimization:** - - Review Lambda invocation costs - - Optimize DynamoDB capacity - - Implement S3 lifecycle policies - - Monitor Bedrock API costs - -4. **Security Hardening:** - - Review IAM permissions (principle of least privilege) - - Enable VPC for Lambda (if needed) - - Implement encryption at rest and in transit - - Set up AWS WAF rules (if exposing API) - -## Support and Documentation - -- **Requirements:** `.kiro/specs/rag-ingestion-stack/requirements.md` -- **Design:** `.kiro/specs/rag-ingestion-stack/design.md` -- **Tasks:** `.kiro/specs/rag-ingestion-stack/tasks.md` -- **Verification:** `.kiro/specs/rag-ingestion-stack/task-7-verification-results.md` - -For issues or questions, refer to the design document or create a GitHub issue. - ---- - -**Last Updated:** 2025-01-27 -**Status:** Ready for Deployment -**Version:** 1.0.0 diff --git a/.kiro/specs/rag-ingestion-stack/IMPLEMENTATION_SUMMARY.md b/.kiro/specs/rag-ingestion-stack/IMPLEMENTATION_SUMMARY.md deleted file mode 100644 index f3315e17..00000000 --- a/.kiro/specs/rag-ingestion-stack/IMPLEMENTATION_SUMMARY.md +++ /dev/null @@ -1,413 +0,0 @@ -# RAG Ingestion Stack - Implementation Summary - -## Executive Summary - -The RAG Ingestion Stack implementation is **100% complete** for all coding tasks (Tasks 1-11). The remaining tasks (12-16) are manual deployment and verification steps that require AWS access and operational execution. - -## Implementation Status - -### ✅ Completed Tasks (1-11) - -| Task | Status | Description | -|------|--------|-------------| -| 1 | ✅ Complete | RAG Ingestion configuration added to config.ts | -| 2 | ✅ Complete | RagIngestionStack CDK code created | -| 3 | ✅ Complete | Stack registered in CDK app | -| 4 | ✅ Complete | Shell scripts created for CI/CD | -| 5 | ✅ Complete | load-env.sh updated for RAG configuration | -| 6 | ✅ Complete | GitHub Actions workflow created | -| 7 | ✅ Complete | Stack synthesis verified locally | -| 8 | ✅ Complete | CDK unit tests written | -| 9 | ✅ Complete | Property-based tests written | -| 10 | ✅ Complete | cdk.context.json updated | -| 11 | ✅ Complete | GitHub repository settings documented | - -### 📋 Remaining Tasks (12-16) - Manual Deployment - -| Task | Status | Description | Action Required | -|------|--------|-------------|-----------------| -| 12 | 📋 Pending | Test CI/CD pipeline | Create PR, monitor workflow | -| 13 | 📋 Pending | Deploy to AWS | Merge to main, monitor deployment | -| 14 | 📋 Pending | Verify deployed resources | Check AWS Console, run verification commands | -| 15 | 📋 Pending | Test Lambda function | Upload test document, verify processing | -| 16 | 📋 Pending | Final verification | Verify no interference with existing resources | - -## What Was Built - -### 1. CDK Infrastructure Code - -**File:** `infrastructure/lib/rag-ingestion-stack.ts` (450+ lines) - -**Resources Created:** -- S3 Documents Bucket (with CORS, versioning, encryption) -- S3 Vectors Bucket and Index (for embeddings storage) -- DynamoDB Assistants Table (with 3 GSIs) -- Lambda Function (Docker-based, ARM64, 10GB memory) -- IAM Roles and Policies (least-privilege permissions) -- S3 Event Notifications (trigger Lambda on document upload) -- 7 SSM Parameters (for cross-stack communication) -- 5 CloudFormation Outputs - -**Key Features:** -- Independent deployment (no cross-stack references) -- Reuses existing Dockerfile and Lambda code -- Distinct resource names (rag-* prefix) -- Follows all project DevOps conventions - -### 2. Configuration Management - -**File:** `infrastructure/lib/config.ts` - -**Added:** -- `RagIngestionConfig` interface -- Configuration loading with environment variable precedence -- Default values for all settings -- Validation and type safety - -**Configuration Options:** -- `enabled`: Enable/disable RAG stack -- `corsOrigins`: CORS origins for S3 bucket -- `lambdaMemorySize`: Lambda memory (default: 10240 MB) -- `lambdaTimeout`: Lambda timeout (default: 900 seconds) -- `embeddingModel`: Bedrock model (default: amazon.titan-embed-text-v2) -- `vectorDimension`: Embedding dimension (default: 1024) -- `vectorDistanceMetric`: Distance metric (default: cosine) - -### 3. CI/CD Workflow - -**File:** `.github/workflows/rag-ingestion.yml` (300+ lines) - -**Jobs:** -1. **install** - Install and cache dependencies -2. **build-docker** - Build Docker image (ARM64) -3. **build-cdk** - Compile TypeScript -4. **test-docker** - Validate Docker image -5. **test-cdk** - Validate CloudFormation templates -6. **synth-cdk** - Synthesize templates -7. **push-to-ecr** - Push image to ECR -8. **deploy-infrastructure** - Deploy stack to AWS - -**Features:** -- Parallel execution for efficiency -- Artifact-based job handover -- ARM64-native runners for Lambda builds -- Conditional deployment (only on main branch) -- Comprehensive error handling - -### 4. Shell Scripts - -**Directory:** `scripts/stack-rag-ingestion/` - -**Scripts Created:** -- `install.sh` - Install dependencies -- `build.sh` - Build Docker image -- `build-cdk.sh` - Compile TypeScript -- `synth.sh` - Synthesize CDK templates -- `deploy.sh` - Deploy stack -- `test-docker.sh` - Test Docker image -- `test-cdk.sh` - Test CloudFormation templates -- `push-to-ecr.sh` - Push to ECR -- `tag-latest.sh` - Tag as latest - -**Features:** -- Runnable locally and in CI -- Consistent error handling -- Logging and status messages -- Environment variable validation - -### 5. Unit Tests - -**File:** `infrastructure/test/rag-ingestion-stack.test.ts` - -**Test Coverage:** -- S3 bucket configuration (encryption, versioning, CORS) -- DynamoDB table configuration (keys, GSIs, billing) -- Lambda function configuration (memory, timeout, env vars) -- IAM permissions (S3, DynamoDB, Bedrock, S3 Vectors) -- SSM parameter exports (all 7 parameters) -- CloudFormation outputs (all 5 outputs) - -**File:** `infrastructure/test/config.test.ts` - -**Test Coverage:** -- Configuration loading from environment variables -- Configuration fallback to context values -- Configuration defaults -- Configuration validation - -### 6. Property-Based Tests - -**File:** `infrastructure/test/rag-ingestion-stack.test.ts` - -**Properties Tested:** -1. **CloudFormation Template Completeness** - All required resources present -2. **No Cross-Stack References** - No Fn::ImportValue to AppApiStack -3. **SSM Parameter Exports** - All 7 parameters exported correctly -4. **Configuration Loading** - Precedence: env > context > default -5. **Resource Naming Uniqueness** - All resources use "rag-" prefix - -**Test Configuration:** -- Minimum 100 iterations per property -- Random valid configurations generated -- Comprehensive coverage of edge cases - -## Architecture Overview - -``` -┌─────────────────────────────────────────────────────────────┐ -│ Infrastructure Stack │ -│ (VPC, Subnets, ALB, ECS Cluster) │ -└─────────────────────────────────────────────────────────────┘ - │ - │ SSM Parameters - ▼ -┌─────────────────────────────────────────────────────────────┐ -│ RAG Ingestion Stack (NEW) │ -│ │ -│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │ -│ │ S3 Documents │ │ S3 Vectors │ │ DynamoDB │ │ -│ │ Bucket │ │ Bucket+Index │ │ Assistants │ │ -│ └──────────────┘ └──────────────┘ └──────────────┘ │ -│ │ ▲ ▲ │ -│ │ S3 Event │ Write │ Write │ -│ ▼ │ │ │ -│ ┌──────────────────────────────────────────────────┐ │ -│ │ Lambda Function (Docker, ARM64) │ │ -│ │ - Process documents │ │ -│ │ - Generate embeddings (Bedrock Titan) │ │ -│ │ - Store vectors and metadata │ │ -│ └──────────────────────────────────────────────────┘ │ -│ │ │ -│ │ Invoke Model │ -│ ▼ │ -│ ┌──────────────┐ │ -│ │ Bedrock │ │ -│ │ Titan Embed │ │ -│ └──────────────┘ │ -└─────────────────────────────────────────────────────────────┘ - │ - │ SSM Parameters (7) - ▼ -┌─────────────────────────────────────────────────────────────┐ -│ App API Stack (UNCHANGED) │ -│ (Can optionally import new RAG resources via SSM) │ -└─────────────────────────────────────────────────────────────┘ -``` - -## Key Design Decisions - -### 1. Carbon Copy Implementation -- Reuses existing `backend/Dockerfile.rag-ingestion` -- Reuses existing Lambda handler code -- Identical functionality to AppApiStack RAG implementation -- Enables side-by-side verification before migration - -### 2. Independent Deployment -- No direct CloudFormation cross-stack references -- Uses SSM Parameter Store for loose coupling -- Can be deployed without modifying AppApiStack -- Can be deleted without affecting AppApiStack - -### 3. Distinct Resource Names -- All resources use "rag-" prefix -- Avoids conflicts with existing "assistants-" resources -- Enables parallel operation of old and new stacks -- Clear separation for monitoring and cost tracking - -### 4. DevOps Best Practices -- Script-based automation (logic in scripts, not YAML) -- Artifact-driven job handover -- ARM64-native builds for Lambda -- Comprehensive testing (unit + property-based) -- Environment variable configuration - -### 5. Security and Compliance -- Least-privilege IAM permissions -- S3 bucket encryption (S3-managed) -- DynamoDB encryption (AWS-managed) -- No public access to S3 buckets -- VPC integration (optional, can be added) - -## Testing Strategy - -### Unit Tests -- Verify specific CloudFormation resource configurations -- Test individual script functions -- Validate configuration loading with specific inputs -- Test error handling for known edge cases - -### Property-Based Tests -- Verify CloudFormation template structure across all valid configurations -- Test configuration loading across all valid environment variable combinations -- Verify resource naming patterns across all valid project prefixes -- Test script execution across different environments - -### Integration Tests (Manual) -- Test full deployment cycle -- Verify Lambda can process documents -- Verify embeddings stored in vector store -- Verify metadata stored in DynamoDB -- Test cross-stack communication via SSM - -## Deployment Readiness - -### ✅ Ready for Deployment - -**Code Quality:** -- All TypeScript compiles without errors -- All tests pass (unit + property-based) -- CloudFormation template synthesizes successfully -- No linting errors - -**Documentation:** -- Requirements document complete -- Design document complete -- Implementation tasks complete -- Deployment guide created -- Verification checklist provided - -**Configuration:** -- All configuration options documented -- Environment variables defined -- GitHub Actions workflow configured -- Scripts tested locally - -### 📋 Prerequisites for Deployment - -**AWS Infrastructure:** -- Infrastructure Stack must be deployed first -- VPC and network resources must exist -- SSM parameters from Infrastructure Stack must be available - -**GitHub Configuration:** -- GitHub Variables must be set (CDK_PROJECT_PREFIX, CDK_RAG_ENABLED, etc.) -- GitHub Secrets must be set (AWS credentials) -- Repository must have Actions enabled - -**AWS Permissions:** -- IAM permissions to create CloudFormation stacks -- IAM permissions to create S3 buckets, DynamoDB tables, Lambda functions -- IAM permissions to push to ECR -- IAM permissions to write SSM parameters - -## Next Steps - -### Immediate Actions (Manual) - -1. **Test CI/CD Pipeline (Task 12)** - - Create feature branch - - Push to GitHub - - Monitor workflow execution - - Verify all jobs pass - -2. **Deploy to AWS (Task 13)** - - Merge to main branch - - Monitor deployment workflow - - Verify CloudFormation stack created - -3. **Verify Resources (Task 14)** - - Check S3 bucket exists - - Check DynamoDB table exists - - Check Lambda function exists - - Check SSM parameters exported - -4. **Test Lambda (Task 15)** - - Upload test document - - Verify Lambda triggered - - Check CloudWatch Logs - - Verify embeddings stored - -5. **Final Verification (Task 16)** - - Verify no interference with existing resources - - Document any issues - - Create verification report - -### Future Enhancements - -**Phase 2: Verification** -- Deploy both stacks in parallel -- Test both implementations with same data -- Verify identical behavior -- Compare performance metrics - -**Phase 3: Migration** -- Update AppApiStack to use new RAG resources via SSM -- Deploy AppApiStack with new configuration -- Verify application works with new resources -- Remove old RAG resources from AppApiStack -- Clean up old resources - -**Phase 4: Optimization** -- Monitor Lambda execution times -- Optimize chunk size for embeddings -- Tune Lambda memory allocation -- Implement caching if needed -- Set up CloudWatch dashboards and alarms - -## Success Metrics - -### Deployment Success -- ✅ CloudFormation stack status: CREATE_COMPLETE -- ✅ All resources created in AWS -- ✅ Lambda function can process documents -- ✅ Embeddings stored in vector store -- ✅ Metadata stored in DynamoDB -- ✅ SSM parameters exported correctly -- ✅ No interference with existing resources - -### Operational Success -- Lambda invocation success rate > 95% -- Lambda execution time < 5 minutes (average) -- No errors in CloudWatch Logs -- Cost within budget -- No security vulnerabilities - -## Files Created/Modified - -### New Files Created (15) - -**CDK Infrastructure:** -1. `infrastructure/lib/rag-ingestion-stack.ts` - Main stack definition - -**CI/CD:** -2. `.github/workflows/rag-ingestion.yml` - GitHub Actions workflow - -**Scripts:** -3. `scripts/stack-rag-ingestion/install.sh` -4. `scripts/stack-rag-ingestion/build.sh` -5. `scripts/stack-rag-ingestion/build-cdk.sh` -6. `scripts/stack-rag-ingestion/synth.sh` -7. `scripts/stack-rag-ingestion/deploy.sh` -8. `scripts/stack-rag-ingestion/test-docker.sh` -9. `scripts/stack-rag-ingestion/test-cdk.sh` -10. `scripts/stack-rag-ingestion/push-to-ecr.sh` -11. `scripts/stack-rag-ingestion/tag-latest.sh` - -**Tests:** -12. `infrastructure/test/rag-ingestion-stack.test.ts` - Unit and property tests -13. `infrastructure/test/config.test.ts` - Configuration tests - -**Documentation:** -14. `.kiro/specs/rag-ingestion-stack/DEPLOYMENT_GUIDE.md` -15. `.kiro/specs/rag-ingestion-stack/IMPLEMENTATION_SUMMARY.md` (this file) - -### Modified Files (3) - -1. `infrastructure/lib/config.ts` - Added RagIngestionConfig -2. `infrastructure/bin/infrastructure.ts` - Registered RagIngestionStack -3. `scripts/common/load-env.sh` - Added RAG configuration exports - -## Conclusion - -The RAG Ingestion Stack implementation is **complete and ready for deployment**. All coding tasks have been finished, tested, and verified. The remaining tasks are manual deployment and verification steps that require AWS access. - -The implementation follows all project conventions, includes comprehensive testing, and provides a solid foundation for the RAG ingestion pipeline. The stack can be deployed independently without affecting existing resources, enabling safe verification before migration. - -**Recommendation:** Proceed with Task 12 (Test CI/CD Pipeline) by creating a feature branch and pushing to GitHub to trigger the workflow. - ---- - -**Implementation Date:** 2025-01-27 -**Status:** ✅ Complete (Coding Tasks) -**Next Phase:** 📋 Deployment and Verification -**Version:** 1.0.0 diff --git a/.kiro/specs/rag-ingestion-stack/MIGRATION_GUIDE.md b/.kiro/specs/rag-ingestion-stack/MIGRATION_GUIDE.md deleted file mode 100644 index 976589f9..00000000 --- a/.kiro/specs/rag-ingestion-stack/MIGRATION_GUIDE.md +++ /dev/null @@ -1,311 +0,0 @@ -# RAG Ingestion Stack Migration Guide - -## Overview - -This guide explains how to switch the App API and Frontend from using the **old RAG resources** (in AppApiStack) to the **new RAG resources** (in RagIngestionStack). - -## Current Architecture - -### Old RAG Resources (AppApiStack) -- **S3 Bucket**: `${projectPrefix}-assistants-documents` -- **DynamoDB Table**: `${projectPrefix}-assistants` -- **Vector Store Bucket**: `${projectPrefix}-assistants-vector-store-v1` -- **Vector Store Index**: `${projectPrefix}-assistants-vector-index-v1` -- **Lambda Function**: `AssistantsDocumentsIngestionlambdaFunction` - -### New RAG Resources (RagIngestionStack) -- **S3 Bucket**: `${projectPrefix}-rag-documents` -- **DynamoDB Table**: `${projectPrefix}-rag-assistants` -- **Vector Store Bucket**: `${projectPrefix}-rag-vector-store-v1` -- **Vector Store Index**: `${projectPrefix}-rag-vector-index-v1` -- **Lambda Function**: `RagIngestionLambda` - -## What Needs to Change - -The App API (ECS Fargate service) uses these environment variables that point to the old resources: - -```typescript -// Current (OLD) - Hardcoded to AppApiStack resources -S3_ASSISTANTS_DOCUMENTS_BUCKET_NAME: assistantsDocumentsBucket.bucketName, -DYNAMODB_ASSISTANTS_TABLE_NAME: assistantsTable.tableName, -S3_ASSISTANTS_VECTOR_STORE_BUCKET_NAME: assistantsVectorStoreBucketName, -S3_ASSISTANTS_VECTOR_STORE_INDEX_NAME: assistantsVectorIndexName, -``` - -These need to be changed to import from SSM parameters exported by RagIngestionStack. - -## Migration Steps - -### Step 1: Update AppApiStack to Import RAG Resources from SSM - -**File**: `infrastructure/lib/app-api-stack.ts` - -**Location**: Around line 1140 in the ECS task definition environment variables - -**Change FROM:** -```typescript -S3_ASSISTANTS_DOCUMENTS_BUCKET_NAME: assistantsDocumentsBucket.bucketName, -DYNAMODB_ASSISTANTS_TABLE_NAME: assistantsTable.tableName, -S3_ASSISTANTS_VECTOR_STORE_BUCKET_NAME: assistantsVectorStoreBucketName, -S3_ASSISTANTS_VECTOR_STORE_INDEX_NAME: assistantsVectorIndexName, -``` - -**Change TO:** -```typescript -// Import RAG resource names from RagIngestionStack via SSM -S3_ASSISTANTS_DOCUMENTS_BUCKET_NAME: ssm.StringParameter.valueForStringParameter( - this, - `/${config.projectPrefix}/rag/documents-bucket-name` -), -DYNAMODB_ASSISTANTS_TABLE_NAME: ssm.StringParameter.valueForStringParameter( - this, - `/${config.projectPrefix}/rag/assistants-table-name` -), -S3_ASSISTANTS_VECTOR_STORE_BUCKET_NAME: ssm.StringParameter.valueForStringParameter( - this, - `/${config.projectPrefix}/rag/vector-bucket-name` -), -S3_ASSISTANTS_VECTOR_STORE_INDEX_NAME: ssm.StringParameter.valueForStringParameter( - this, - `/${config.projectPrefix}/rag/vector-index-name` -), -``` - -### Step 2: Update IAM Permissions for ECS Task - -The ECS task role needs permissions to access the **new** RAG resources. - -**File**: `infrastructure/lib/app-api-stack.ts` - -**Location**: After the task definition, around line 1180 - -**Add these permission grants:** - -```typescript -// Import new RAG resources for permission grants -const ragDocumentsBucketName = ssm.StringParameter.valueForStringParameter( - this, - `/${config.projectPrefix}/rag/documents-bucket-name` -); -const ragDocumentsBucketArn = ssm.StringParameter.valueForStringParameter( - this, - `/${config.projectPrefix}/rag/documents-bucket-arn` -); -const ragAssistantsTableName = ssm.StringParameter.valueForStringParameter( - this, - `/${config.projectPrefix}/rag/assistants-table-name` -); -const ragAssistantsTableArn = ssm.StringParameter.valueForStringParameter( - this, - `/${config.projectPrefix}/rag/assistants-table-arn` -); -const ragVectorBucketName = ssm.StringParameter.valueForStringParameter( - this, - `/${config.projectPrefix}/rag/vector-bucket-name` -); - -// Import S3 bucket for permissions -const ragDocumentsBucket = s3.Bucket.fromBucketAttributes(this, "ImportedRagDocumentsBucket", { - bucketName: ragDocumentsBucketName, - bucketArn: ragDocumentsBucketArn, -}); - -// Import DynamoDB table for permissions -const ragAssistantsTable = dynamodb.Table.fromTableAttributes(this, "ImportedRagAssistantsTable", { - tableName: ragAssistantsTableName, - tableArn: ragAssistantsTableArn, -}); - -// Grant permissions to ECS task role -ragDocumentsBucket.grantReadWrite(taskDefinition.taskRole); -ragAssistantsTable.grantReadWriteData(taskDefinition.taskRole); - -// Grant S3 Vectors permissions -taskDefinition.taskRole.addToPrincipalPolicy( - new iam.PolicyStatement({ - effect: iam.Effect.ALLOW, - actions: [ - "s3vectors:ListVectorBuckets", - "s3vectors:GetVectorBucket", - "s3vectors:GetIndex", - "s3vectors:PutVectors", - "s3vectors:ListVectors", - "s3vectors:ListIndexes", - "s3vectors:GetVector", - "s3vectors:GetVectors", - "s3vectors:DeleteVector", - ], - resources: [ - `arn:aws:s3vectors:${config.awsRegion}:${config.awsAccount}:bucket/${ragVectorBucketName}`, - `arn:aws:s3vectors:${config.awsRegion}:${config.awsAccount}:bucket/${ragVectorBucketName}/index/*`, - ], - }) -); -``` - -### Step 3: Deploy Updated AppApiStack - -```bash -# Synthesize the updated stack -cd infrastructure -npm run build -cdk synth AppApiStack - -# Deploy the updated stack -cdk deploy AppApiStack --require-approval never -``` - -This will: -1. Update the ECS task definition with new environment variables -2. Grant permissions to access new RAG resources -3. Trigger a rolling deployment of the ECS service - -### Step 4: Verify the Migration - -#### 4.1 Check ECS Task Environment Variables - -```bash -# Get the task ARN -aws ecs list-tasks --cluster ${PROJECT_PREFIX}-ecs-cluster --service-name ${PROJECT_PREFIX}-app-api - -# Describe the task to see environment variables -aws ecs describe-tasks --cluster ${PROJECT_PREFIX}-ecs-cluster --tasks -``` - -Verify the environment variables point to the new resources: -- `S3_ASSISTANTS_DOCUMENTS_BUCKET_NAME` should be `${projectPrefix}-rag-documents` -- `DYNAMODB_ASSISTANTS_TABLE_NAME` should be `${projectPrefix}-rag-assistants` - -#### 4.2 Test RAG Functionality - -1. **Upload a document** via the frontend -2. **Check CloudWatch Logs** for the new Lambda function: - ```bash - aws logs tail /aws/lambda/${PROJECT_PREFIX}-rag-ingestion --follow - ``` -3. **Verify document processing**: - - Document appears in S3 bucket - - Metadata appears in DynamoDB table - - Embeddings stored in vector store -4. **Test search/retrieval** in the frontend - -#### 4.3 Monitor for Errors - -```bash -# Check ECS service logs -aws logs tail /ecs/${PROJECT_PREFIX}/app-api --follow - -# Check Lambda logs -aws logs tail /aws/lambda/${PROJECT_PREFIX}-rag-ingestion --follow -``` - -### Step 5: Clean Up Old RAG Resources (After Verification) - -**⚠️ ONLY DO THIS AFTER CONFIRMING EVERYTHING WORKS!** - -Once you've verified the new RAG stack works correctly, you can remove the old resources from AppApiStack. - -**File**: `infrastructure/lib/app-api-stack.ts` - -**Remove these sections:** - -1. **Assistants Table** (around line 130-200) -2. **Assistants Documents Bucket** (around line 200-220) -3. **Assistants Vector Store Bucket and Index** (around line 220-260) -4. **Assistants Documents Ingestion Lambda** (around line 260-320) -5. **Lambda permissions and S3 event notifications** (around line 320-360) - -**Then redeploy:** -```bash -cdk deploy AppApiStack --require-approval never -``` - -This will remove the old resources from CloudFormation, but they'll be retained in AWS (due to `RETAIN` removal policy). - -### Step 6: Manual Cleanup (Optional) - -If you want to completely remove the old resources: - -```bash -# Delete old S3 bucket (must be empty first) -aws s3 rm s3://${PROJECT_PREFIX}-assistants-documents --recursive -aws s3 rb s3://${PROJECT_PREFIX}-assistants-documents - -# Delete old DynamoDB table -aws dynamodb delete-table --table-name ${PROJECT_PREFIX}-assistants - -# Delete old Lambda function -aws lambda delete-function --function-name ${PROJECT_PREFIX}-assistants-documents-ingestion - -# Delete old Vector Store (if needed) -# Note: S3 Vectors may require special cleanup commands -``` - -## Rollback Plan - -If something goes wrong, you can quickly rollback: - -### Option 1: Revert AppApiStack Changes - -```bash -# Revert the code changes in app-api-stack.ts -git checkout HEAD -- infrastructure/lib/app-api-stack.ts - -# Redeploy -cdk deploy AppApiStack --require-approval never -``` - -### Option 2: Use Old Resources Temporarily - -The old resources still exist, so you can temporarily point back to them by reverting the environment variable changes. - -## Frontend Changes - -**The frontend doesn't need any changes!** - -The frontend talks to the App API via REST endpoints. As long as the App API is configured correctly (Step 1-3 above), the frontend will automatically use the new RAG resources. - -## Summary Checklist - -- [ ] Step 1: Update AppApiStack environment variables to import from SSM -- [ ] Step 2: Add IAM permissions for new RAG resources -- [ ] Step 3: Deploy updated AppApiStack -- [ ] Step 4: Verify ECS task environment variables -- [ ] Step 4: Test document upload and processing -- [ ] Step 4: Test search/retrieval functionality -- [ ] Step 4: Monitor logs for errors -- [ ] Step 5: Remove old RAG resources from AppApiStack (after verification) -- [ ] Step 6: Manual cleanup of old AWS resources (optional) - -## Troubleshooting - -### Issue: ECS tasks fail to start - -**Cause**: Missing IAM permissions for new resources - -**Solution**: Check CloudWatch Logs for permission errors, add missing permissions to task role - -### Issue: Documents not processing - -**Cause**: Lambda not triggered or failing - -**Solution**: -1. Check S3 event notifications are configured -2. Check Lambda CloudWatch Logs for errors -3. Verify Lambda has permissions to access resources - -### Issue: Search returns no results - -**Cause**: Embeddings not stored in vector store - -**Solution**: -1. Check Lambda logs for embedding generation errors -2. Verify vector store bucket and index exist -3. Check IAM permissions for S3 Vectors operations - -## Support - -If you encounter issues during migration, check: -1. CloudWatch Logs for ECS tasks and Lambda functions -2. CloudFormation stack events for deployment errors -3. IAM permissions for missing access rights diff --git a/.kiro/specs/rag-ingestion-stack/MIGRATION_IMPLEMENTATION.md b/.kiro/specs/rag-ingestion-stack/MIGRATION_IMPLEMENTATION.md deleted file mode 100644 index cf81f81b..00000000 --- a/.kiro/specs/rag-ingestion-stack/MIGRATION_IMPLEMENTATION.md +++ /dev/null @@ -1,310 +0,0 @@ -# RAG Ingestion Stack Migration - Implementation Complete - -## Changes Made - -I've successfully updated the AppApiStack to use the new RAG resources from RagIngestionStack. Here's what was changed: - -### 1. Updated Environment Variables (Line ~1142) - -**Changed FROM** (hardcoded local resources): -```typescript -S3_ASSISTANTS_DOCUMENTS_BUCKET_NAME: assistantsDocumentsBucket.bucketName, -DYNAMODB_ASSISTANTS_TABLE_NAME: assistantsTable.tableName, -S3_ASSISTANTS_VECTOR_STORE_BUCKET_NAME: assistantsVectorStoreBucketName, -S3_ASSISTANTS_VECTOR_STORE_INDEX_NAME: assistantsVectorIndexName, -``` - -**Changed TO** (imported from RagIngestionStack via SSM): -```typescript -// RAG resources - imported from RagIngestionStack via SSM -S3_ASSISTANTS_DOCUMENTS_BUCKET_NAME: ssm.StringParameter.valueForStringParameter( - this, - `/${config.projectPrefix}/rag/documents-bucket-name` -), -DYNAMODB_ASSISTANTS_TABLE_NAME: ssm.StringParameter.valueForStringParameter( - this, - `/${config.projectPrefix}/rag/assistants-table-name` -), -S3_ASSISTANTS_VECTOR_STORE_BUCKET_NAME: ssm.StringParameter.valueForStringParameter( - this, - `/${config.projectPrefix}/rag/vector-bucket-name` -), -S3_ASSISTANTS_VECTOR_STORE_INDEX_NAME: ssm.StringParameter.valueForStringParameter( - this, - `/${config.projectPrefix}/rag/vector-index-name` -), -``` - -### 2. Added IAM Permissions (Line ~1180) - -Added a new section to grant the ECS task role permissions to access the new RAG resources: - -```typescript -// ============================================================ -// Grant permissions for NEW RAG resources (from RagIngestionStack) -// ============================================================ - -// Import RAG resource identifiers from SSM -const ragDocumentsBucketName = ssm.StringParameter.valueForStringParameter( - this, - `/${config.projectPrefix}/rag/documents-bucket-name` -); -const ragDocumentsBucketArn = ssm.StringParameter.valueForStringParameter( - this, - `/${config.projectPrefix}/rag/documents-bucket-arn` -); -const ragAssistantsTableName = ssm.StringParameter.valueForStringParameter( - this, - `/${config.projectPrefix}/rag/assistants-table-name` -); -const ragAssistantsTableArn = ssm.StringParameter.valueForStringParameter( - this, - `/${config.projectPrefix}/rag/assistants-table-arn` -); -const ragVectorBucketName = ssm.StringParameter.valueForStringParameter( - this, - `/${config.projectPrefix}/rag/vector-bucket-name` -); - -// Import S3 bucket for permissions -const ragDocumentsBucket = s3.Bucket.fromBucketAttributes(this, "ImportedRagDocumentsBucket", { - bucketName: ragDocumentsBucketName, - bucketArn: ragDocumentsBucketArn, -}); - -// Import DynamoDB table for permissions -const ragAssistantsTable = dynamodb.Table.fromTableAttributes(this, "ImportedRagAssistantsTable", { - tableName: ragAssistantsTableName, - tableArn: ragAssistantsTableArn, -}); - -// Grant permissions to ECS task role for RAG resources -ragDocumentsBucket.grantReadWrite(taskDefinition.taskRole); -ragAssistantsTable.grantReadWriteData(taskDefinition.taskRole); - -// Grant S3 Vectors permissions for RAG vector store -taskDefinition.taskRole.addToPrincipalPolicy( - new iam.PolicyStatement({ - effect: iam.Effect.ALLOW, - actions: [ - "s3vectors:ListVectorBuckets", - "s3vectors:GetVectorBucket", - "s3vectors:GetIndex", - "s3vectors:PutVectors", - "s3vectors:ListVectors", - "s3vectors:ListIndexes", - "s3vectors:GetVector", - "s3vectors:GetVectors", - "s3vectors:DeleteVector", - ], - resources: [ - `arn:aws:s3vectors:${config.awsRegion}:${config.awsAccount}:bucket/${ragVectorBucketName}`, - `arn:aws:s3vectors:${config.awsRegion}:${config.awsAccount}:bucket/${ragVectorBucketName}/index/*`, - ], - }) -); -``` - -## What This Achieves - -1. **ECS tasks now use the new RAG resources** - Environment variables point to the new S3 bucket, DynamoDB table, and vector store -2. **Proper IAM permissions** - ECS task role can read/write to the new resources -3. **No code changes in the application** - The Python code uses the same environment variable names, so no changes needed -4. **Old resources remain untouched** - The old RAG resources in AppApiStack are still defined but no longer used - -## Next Steps - What You Need to Do - -### Step 1: Build and Deploy - -```bash -cd infrastructure -npm run build -cdk synth AppApiStack -cdk deploy AppApiStack --require-approval never -``` - -This will: -- Update the ECS task definition with new environment variables -- Grant IAM permissions to the new resources -- Trigger a rolling deployment of the ECS service (zero downtime) - -### Step 2: Verify the Deployment - -#### Check ECS Task Environment Variables - -```bash -# Set your project prefix -export PROJECT_PREFIX="bsu-agentcore" # or your actual prefix - -# Get the running task ARN -TASK_ARN=$(aws ecs list-tasks \ - --cluster ${PROJECT_PREFIX}-ecs-cluster \ - --service-name ${PROJECT_PREFIX}-app-api \ - --query 'taskArns[0]' \ - --output text) - -# Describe the task to see environment variables -aws ecs describe-tasks \ - --cluster ${PROJECT_PREFIX}-ecs-cluster \ - --tasks ${TASK_ARN} \ - --query 'tasks[0].containers[0].environment' \ - --output table -``` - -Look for these environment variables and verify they point to the new resources: -- `S3_ASSISTANTS_DOCUMENTS_BUCKET_NAME` should be `${PROJECT_PREFIX}-rag-documents` -- `DYNAMODB_ASSISTANTS_TABLE_NAME` should be `${PROJECT_PREFIX}-rag-assistants` -- `S3_ASSISTANTS_VECTOR_STORE_BUCKET_NAME` should be `${PROJECT_PREFIX}-rag-vector-store-v1` -- `S3_ASSISTANTS_VECTOR_STORE_INDEX_NAME` should be `${PROJECT_PREFIX}-rag-vector-index-v1` - -### Step 3: Test RAG Functionality - -1. **Upload a document** via the frontend: - - Go to the assistants section - - Create or select an assistant - - Upload a test document (PDF, DOCX, etc.) - -2. **Monitor the new Lambda function**: - ```bash - # Watch Lambda logs in real-time - aws logs tail /aws/lambda/${PROJECT_PREFIX}-rag-ingestion --follow - ``` - -3. **Verify document processing**: - ```bash - # Check if document appears in new S3 bucket - aws s3 ls s3://${PROJECT_PREFIX}-rag-documents/assistants/ - - # Check if metadata appears in new DynamoDB table - aws dynamodb scan \ - --table-name ${PROJECT_PREFIX}-rag-assistants \ - --max-items 5 - ``` - -4. **Test search/retrieval** in the frontend: - - Ask the assistant a question about the uploaded document - - Verify it can retrieve relevant information - -### Step 4: Monitor for Errors - -```bash -# Monitor ECS service logs -aws logs tail /ecs/${PROJECT_PREFIX}/app-api --follow - -# Monitor Lambda logs -aws logs tail /aws/lambda/${PROJECT_PREFIX}-rag-ingestion --follow -``` - -Look for any errors related to: -- S3 access denied -- DynamoDB access denied -- S3 Vectors access denied -- Missing environment variables - -### Step 5: Clean Up Old Resources (After Verification) - -**⚠️ ONLY DO THIS AFTER CONFIRMING EVERYTHING WORKS FOR AT LEAST 24 HOURS!** - -Once you've verified the new RAG stack works correctly and you're confident, you can remove the old RAG resource definitions from AppApiStack. - -The old resources to remove from `infrastructure/lib/app-api-stack.ts`: - -1. **Assistants Table** (around line 130-200) -2. **Assistants Documents Bucket** (around line 200-220) -3. **Assistants Vector Store Bucket and Index** (around line 220-260) -4. **Assistants Documents Ingestion Lambda** (around line 260-320) -5. **Lambda permissions and S3 event notifications** (around line 320-360) - -After removing these, redeploy: -```bash -cdk deploy AppApiStack --require-approval never -``` - -The resources will be removed from CloudFormation but retained in AWS (due to RETAIN removal policy). - -## Rollback Plan - -If something goes wrong, you can quickly rollback: - -```bash -# Revert the changes -git checkout HEAD -- infrastructure/lib/app-api-stack.ts - -# Rebuild and redeploy -cd infrastructure -npm run build -cdk deploy AppApiStack --require-approval never -``` - -This will restore the ECS tasks to use the old RAG resources. - -## Troubleshooting - -### Issue: ECS tasks fail to start after deployment - -**Symptoms**: Tasks keep restarting, health checks fail - -**Diagnosis**: -```bash -# Check task logs -aws logs tail /ecs/${PROJECT_PREFIX}/app-api --follow -``` - -**Common causes**: -1. Missing SSM parameters (RagIngestionStack not deployed) -2. IAM permission errors -3. Invalid resource names - -**Solution**: Check CloudWatch Logs for specific error messages - -### Issue: Documents upload but don't process - -**Symptoms**: Documents appear in S3 but Lambda doesn't trigger - -**Diagnosis**: -```bash -# Check if Lambda exists -aws lambda get-function --function-name ${PROJECT_PREFIX}-rag-ingestion - -# Check S3 event notifications -aws s3api get-bucket-notification-configuration \ - --bucket ${PROJECT_PREFIX}-rag-documents -``` - -**Solution**: Verify RagIngestionStack deployed successfully and S3 event notifications are configured - -### Issue: Lambda processes but embeddings not stored - -**Symptoms**: Lambda runs successfully but search returns no results - -**Diagnosis**: -```bash -# Check Lambda logs for S3 Vectors errors -aws logs tail /aws/lambda/${PROJECT_PREFIX}-rag-ingestion --follow -``` - -**Common causes**: -1. S3 Vectors permissions missing -2. Vector store bucket/index doesn't exist -3. Bedrock permissions missing - -**Solution**: Check IAM permissions and verify vector store resources exist - -## Success Criteria - -- [ ] AppApiStack deploys successfully -- [ ] ECS tasks start and pass health checks -- [ ] Environment variables point to new RAG resources -- [ ] Documents can be uploaded via frontend -- [ ] Lambda processes documents successfully -- [ ] Embeddings are stored in vector store -- [ ] Search/retrieval works in frontend -- [ ] No errors in CloudWatch Logs - -## Summary - -The migration is **code-complete**! The AppApiStack now imports RAG resources from RagIngestionStack via SSM parameters and has the necessary IAM permissions. - -**What's left**: You need to deploy the updated AppApiStack and verify it works. The deployment is safe and can be rolled back if needed. - -**No frontend changes required** - the frontend will automatically use the new resources once the App API is updated. diff --git a/.kiro/specs/rag-ingestion-stack/READY_TO_DEPLOY.md b/.kiro/specs/rag-ingestion-stack/READY_TO_DEPLOY.md deleted file mode 100644 index 29aa1576..00000000 --- a/.kiro/specs/rag-ingestion-stack/READY_TO_DEPLOY.md +++ /dev/null @@ -1,238 +0,0 @@ -# ✅ RAG Migration - Ready to Deploy - -## Summary - -The migration from old RAG resources (in AppApiStack) to new RAG resources (in RagIngestionStack) is **code-complete** and ready for deployment. - -## What Was Done - -### 1. Code Changes ✅ -- **Updated `infrastructure/lib/app-api-stack.ts`**: - - Changed environment variables to import from SSM parameters - - Added IAM permissions for new RAG resources - - No TypeScript errors - -### 2. Verification Script ✅ -- **Created `scripts/verify-rag-migration.sh`**: - - Automated verification of the migration - - Checks SSM parameters, ECS tasks, environment variables - - Verifies resources exist - -### 3. Documentation ✅ -- **MIGRATION_GUIDE.md**: Detailed step-by-step guide -- **MIGRATION_IMPLEMENTATION.md**: What was changed and why -- **READY_TO_DEPLOY.md**: This file - deployment instructions - -## What You Need to Do - -### Step 1: Deploy the Updated AppApiStack - -```bash -# Navigate to infrastructure directory -cd infrastructure - -# Build TypeScript -npm run build - -# Synthesize CloudFormation template -cdk synth AppApiStack - -# Deploy (this will update the ECS service with zero downtime) -cdk deploy AppApiStack --require-approval never -``` - -**Expected output:** -- CloudFormation will update the ECS task definition -- ECS will perform a rolling deployment (old tasks stay running until new ones are healthy) -- Takes ~5-10 minutes - -### Step 2: Verify the Deployment - -Run the verification script: - -```bash -bash scripts/verify-rag-migration.sh -``` - -This will check: -- ✅ RagIngestionStack is deployed -- ✅ SSM parameters exist -- ✅ AppApiStack is deployed -- ✅ ECS tasks are running -- ✅ Environment variables point to new resources -- ✅ New resources exist in AWS - -**Expected output:** -``` -[SUCCESS] ========================================== -[SUCCESS] RAG Migration Verification PASSED! -[SUCCESS] ========================================== -``` - -### Step 3: Test RAG Functionality - -#### 3.1 Upload a Document - -1. Open the frontend in your browser -2. Navigate to the Assistants section -3. Create or select an assistant -4. Upload a test document (PDF, DOCX, TXT, etc.) - -#### 3.2 Monitor Lambda Processing - -In a separate terminal, watch the Lambda logs: - -```bash -# Set your project prefix -export PROJECT_PREFIX="bsu-agentcore" # or your actual prefix - -# Watch Lambda logs in real-time -aws logs tail /aws/lambda/${PROJECT_PREFIX}-rag-ingestion --follow -``` - -You should see: -- Document download from S3 -- Document processing with Docling -- Chunk generation -- Embedding generation -- Vector storage - -#### 3.3 Test Search/Retrieval - -1. In the frontend, ask the assistant a question about the uploaded document -2. Verify it retrieves relevant information from the document -3. Check that responses are accurate - -### Step 4: Monitor for 24-48 Hours - -Keep an eye on: - -```bash -# ECS service logs -aws logs tail /ecs/${PROJECT_PREFIX}/app-api --follow - -# Lambda logs -aws logs tail /aws/lambda/${PROJECT_PREFIX}-rag-ingestion --follow -``` - -Look for any errors related to: -- S3 access denied -- DynamoDB access denied -- S3 Vectors access denied -- Missing environment variables - -## Rollback Plan (If Needed) - -If something goes wrong, you can quickly rollback: - -```bash -# Revert the code changes -git checkout HEAD -- infrastructure/lib/app-api-stack.ts - -# Rebuild and redeploy -cd infrastructure -npm run build -cdk deploy AppApiStack --require-approval never -``` - -This will restore the ECS tasks to use the old RAG resources. - -## After Successful Verification - -Once you've confirmed everything works for 24-48 hours, you can: - -1. **Remove old RAG resource definitions** from `infrastructure/lib/app-api-stack.ts`: - - Assistants Table (line ~130-200) - - Assistants Documents Bucket (line ~200-220) - - Assistants Vector Store (line ~220-260) - - Assistants Ingestion Lambda (line ~260-320) - - Lambda permissions (line ~320-360) - -2. **Redeploy AppApiStack**: - ```bash - cdk deploy AppApiStack --require-approval never - ``` - -3. **Optional: Manually delete old resources** from AWS Console (they'll be retained due to RETAIN policy) - -## Troubleshooting - -### Issue: Deployment fails with "Parameter not found" - -**Cause**: RagIngestionStack not deployed or SSM parameters missing - -**Solution**: -```bash -# Verify RagIngestionStack is deployed -aws cloudformation describe-stacks --stack-name RagIngestionStack - -# If not deployed, deploy it first -cdk deploy RagIngestionStack -``` - -### Issue: ECS tasks fail health checks - -**Cause**: Application errors, missing permissions, or invalid environment variables - -**Solution**: -```bash -# Check ECS task logs -aws logs tail /ecs/${PROJECT_PREFIX}/app-api --follow - -# Check for specific error messages -``` - -### Issue: Documents upload but don't process - -**Cause**: Lambda not triggered or failing - -**Solution**: -```bash -# Check Lambda exists -aws lambda get-function --function-name ${PROJECT_PREFIX}-rag-ingestion - -# Check S3 event notifications -aws s3api get-bucket-notification-configuration --bucket ${PROJECT_PREFIX}-rag-documents - -# Check Lambda logs -aws logs tail /aws/lambda/${PROJECT_PREFIX}-rag-ingestion --follow -``` - -## Success Criteria - -- [x] Code changes complete -- [ ] AppApiStack deployed successfully -- [ ] Verification script passes -- [ ] Documents can be uploaded -- [ ] Lambda processes documents -- [ ] Search/retrieval works -- [ ] No errors in logs for 24-48 hours -- [ ] Old resources removed from code -- [ ] Old resources cleaned up in AWS (optional) - -## Questions? - -If you encounter any issues: - -1. Check the logs (ECS and Lambda) -2. Run the verification script -3. Review the MIGRATION_GUIDE.md for detailed troubleshooting -4. Rollback if needed (safe and quick) - -## Ready to Go! 🚀 - -Everything is prepared. Just run: - -```bash -cd infrastructure -npm run build -cdk deploy AppApiStack --require-approval never -``` - -Then verify with: - -```bash -bash scripts/verify-rag-migration.sh -``` - -Good luck! The migration is safe, tested, and can be rolled back if needed. diff --git a/.kiro/specs/rag-ingestion-stack/design.md b/.kiro/specs/rag-ingestion-stack/design.md deleted file mode 100644 index 409db95c..00000000 --- a/.kiro/specs/rag-ingestion-stack/design.md +++ /dev/null @@ -1,1171 +0,0 @@ -# Design Document: RAG Ingestion Stack - -## Overview - -This design document specifies the architecture for extracting the RAG (Retrieval-Augmented Generation) ingestion pipeline into an independent CDK stack. The new `RagIngestionStack` will be a carbon copy of the existing AppApiStack RAG implementation, reusing the same Dockerfile and code, but deployed as a separate modular stack with its own CI/CD pipeline. - -### Design Goals - -1. **Modularity**: Create a single-responsibility stack that owns all RAG ingestion resources -2. **Independence**: Enable independent deployment without affecting AppApiStack -3. **Code Reuse**: Reuse existing Dockerfile and Lambda handler code without modifications -4. **Loose Coupling**: Use SSM Parameter Store for cross-stack communication -5. **DevOps Compliance**: Follow all project DevOps conventions and patterns -6. **Non-Interference**: Deploy alongside existing RAG resources without conflicts - -### Key Principles - -- **Carbon Copy Implementation**: Functionally identical to existing AppApiStack RAG implementation -- **Distinct Resource Names**: All resources use unique names to avoid conflicts -- **Shared Code**: Reuse `backend/Dockerfile.rag-ingestion` and Lambda handler -- **SSM-Based Integration**: Export resource names via SSM for future integration -- **Parallel Deployment**: Can coexist with existing AppApiStack RAG resources - -## Architecture - -### High-Level Architecture - -```mermaid -graph TB - subgraph "Infrastructure Stack" - VPC[VPC] - Subnets[Private Subnets] - end - - subgraph "RAG Ingestion Stack (NEW)" - DocBucket[Documents Bucket
rag-documents] - VectorBucket[Vector Store Bucket
rag-vector-store] - VectorIndex[Vector Index
rag-vector-index] - AssistTable[Assistants Table
rag-assistants] - Lambda[Ingestion Lambda
rag-ingestion] - ECR[ECR Repository
rag-ingestion] - end - - subgraph "App API Stack (UNCHANGED)" - ExistingDocBucket[Documents Bucket
assistants-documents] - ExistingVectorBucket[Vector Store
assistants-vector-store] - ExistingTable[Assistants Table
assistants] - ExistingLambda[Ingestion Lambda
assistants-ingestion] - ECS[ECS Service] - end - - subgraph "SSM Parameter Store" - SSM1[/rag/documents-bucket-name] - SSM2[/rag/assistants-table-name] - SSM3[/rag/vector-bucket-name] - SSM4[/rag/vector-index-name] - SSM5[/rag/ingestion-lambda-arn] - SSM6[/rag-ingestion/image-tag] - end - - subgraph "AWS Bedrock" - Titan[Titan Embeddings Model] - end - - DocBucket -->|S3 Event| Lambda - Lambda -->|Read| DocBucket - Lambda -->|Write| AssistTable - Lambda -->|Write Vectors| VectorBucket - Lambda -->|Query| VectorIndex - Lambda -->|Invoke| Titan - ECR -->|Pull Image| Lambda - - Lambda -.->|Exports| SSM1 - Lambda -.->|Exports| SSM2 - Lambda -.->|Exports| SSM3 - Lambda -.->|Exports| SSM4 - Lambda -.->|Exports| SSM5 - - VPC -.->|Network| Lambda - - ExistingDocBucket -->|S3 Event| ExistingLambda - ExistingLambda -->|Read| ExistingDocBucket - ExistingLambda -->|Write| ExistingTable - ExistingLambda -->|Write Vectors| ExistingVectorBucket - ECS -->|Uses| ExistingTable - ECS -->|Uses| ExistingDocBucket - ECS -->|Uses| ExistingVectorBucket - - style Lambda fill:#90EE90 - style DocBucket fill:#90EE90 - style VectorBucket fill:#90EE90 - style VectorIndex fill:#90EE90 - style AssistTable fill:#90EE90 - style ECR fill:#90EE90 - style ExistingDocBucket fill:#FFE4B5 - style ExistingVectorBucket fill:#FFE4B5 - style ExistingTable fill:#FFE4B5 - style ExistingLambda fill:#FFE4B5 -``` - -### Stack Dependencies - -```mermaid -graph LR - Infrastructure[Infrastructure Stack] --> RAG[RAG Ingestion Stack] - Infrastructure --> AppAPI[App API Stack] - - style RAG fill:#90EE90 - style AppAPI fill:#FFE4B5 -``` - -**Deployment Order:** -1. Infrastructure Stack (VPC, Subnets, ALB, ECS Cluster) -2. RAG Ingestion Stack (parallel with App API Stack) -3. App API Stack (parallel with RAG Ingestion Stack) - -### Resource Naming Strategy - -All new resources use the prefix "rag-" to distinguish from existing "assistants-" resources: - -| Resource Type | Existing Name | New Name | -|--------------|---------------|----------| -| S3 Bucket | `assistants-documents` | `rag-documents` | -| Vector Bucket | `assistants-vector-store-v1` | `rag-vector-store-v1` | -| Vector Index | `assistants-vector-index-v1` | `rag-vector-index-v1` | -| DynamoDB Table | `assistants` | `rag-assistants` | -| Lambda Function | `assistants-documents-ingestion` | `rag-ingestion` | -| ECR Repository | N/A (in app-api repo) | `rag-ingestion` | - -## Components and Interfaces - -### 1. CDK Stack: RagIngestionStack - -**File:** `infrastructure/lib/rag-ingestion-stack.ts` - -**Purpose:** Define all RAG ingestion AWS resources as Infrastructure as Code - -**Interface:** -```typescript -export interface RagIngestionStackProps extends cdk.StackProps { - config: AppConfig; -} - -export class RagIngestionStack extends cdk.Stack { - public readonly documentsBucket: s3.Bucket; - public readonly assistantsTable: dynamodb.Table; - public readonly ingestionLambda: lambda.DockerImageFunction; - - constructor(scope: Construct, id: string, props: RagIngestionStackProps); -} -``` - -**Responsibilities:** -- Import VPC and network resources from Infrastructure Stack via SSM -- Create S3 Documents Bucket with CORS configuration -- Create S3 Vectors Bucket and Index (CfnResource) -- Create DynamoDB Assistants Table with GSIs -- Create Lambda function using Docker image from ECR -- Configure IAM permissions for Lambda -- Configure S3 event notifications -- Export resource names to SSM Parameter Store -- Apply standard tags and naming conventions - -**Dependencies:** -- Infrastructure Stack (VPC, Subnets via SSM) -- ECR Repository (created by CI/CD pipeline) -- SSM Parameter for image tag - -### 2. Configuration: RagIngestionConfig - -**File:** `infrastructure/lib/config.ts` - -**Purpose:** Centralize all RAG-specific configuration - -**Interface:** -```typescript -export interface RagIngestionConfig { - enabled: boolean; // Enable/disable RAG stack - corsOrigins: string; // Comma-separated CORS origins - lambdaMemorySize: number; // Lambda memory in MB (default: 10240) - lambdaTimeout: number; // Lambda timeout in seconds (default: 900) - embeddingModel: string; // Bedrock model ID (default: "amazon.titan-embed-text-v2") - vectorDimension: number; // Embedding dimension (default: 1024) - vectorDistanceMetric: string; // Distance metric (default: "cosine") -} - -export interface AppConfig { - // ... existing fields - ragIngestion: RagIngestionConfig; -} -``` - -**Configuration Loading:** -```typescript -ragIngestion: { - enabled: parseBooleanEnv(process.env.CDK_RAG_ENABLED) ?? - scope.node.tryGetContext('ragIngestion')?.enabled ?? true, - corsOrigins: process.env.CDK_RAG_CORS_ORIGINS || - scope.node.tryGetContext('ragIngestion')?.corsOrigins, - lambdaMemorySize: parseIntEnv(process.env.CDK_RAG_LAMBDA_MEMORY) || - scope.node.tryGetContext('ragIngestion')?.lambdaMemorySize || 10240, - lambdaTimeout: parseIntEnv(process.env.CDK_RAG_LAMBDA_TIMEOUT) || - scope.node.tryGetContext('ragIngestion')?.lambdaTimeout || 900, - embeddingModel: process.env.CDK_RAG_EMBEDDING_MODEL || - scope.node.tryGetContext('ragIngestion')?.embeddingModel || - "amazon.titan-embed-text-v2", - vectorDimension: parseIntEnv(process.env.CDK_RAG_VECTOR_DIMENSION) || - scope.node.tryGetContext('ragIngestion')?.vectorDimension || 1024, - vectorDistanceMetric: process.env.CDK_RAG_DISTANCE_METRIC || - scope.node.tryGetContext('ragIngestion')?.vectorDistanceMetric || - "cosine", -} -``` - -### 3. CI/CD Workflow - -**File:** `.github/workflows/rag-ingestion.yml` - -**Purpose:** Automated build, test, and deployment pipeline - -**Jobs:** - -1. **install**: Install and cache dependencies - - Install system dependencies - - Install Python packages - - Install Node.js packages - - Cache for reuse - -2. **build-docker**: Build Docker image - - Build from `backend/Dockerfile.rag-ingestion` - - Tag with git commit SHA - - Export as tar artifact - - Output: `image-tag` - -3. **build-cdk**: Compile TypeScript - - Compile CDK TypeScript code - - Validate syntax - -4. **test-docker**: Validate Docker image - - Load image from artifact - - Verify Lambda handler exists - - Verify Python packages installed - - Test container startup - -5. **test-cdk**: Validate CloudFormation - - Validate template syntax - - Verify resources present - - Check IAM permissions - -6. **synth-cdk**: Synthesize templates - - Run on ARM64 runner (ubuntu-24.04-arm) - - Synthesize CloudFormation templates - - Upload templates as artifact - -7. **push-to-ecr**: Push to ECR - - Create ECR repository if needed - - Push Docker image - - Store image tag in SSM - -8. **deploy-infrastructure**: Deploy stack - - Run on ARM64 runner - - Deploy using synthesized templates - - Output deployment results - -**Workflow Triggers:** -- Push to main branch (paths: backend/src/rag/, backend/Dockerfile.rag-ingestion, infrastructure/lib/rag-ingestion-stack.ts, scripts/stack-rag-ingestion/, .github/workflows/rag-ingestion.yml) -- Pull requests (same paths) -- Manual workflow_dispatch - -**Environment Variables:** -```yaml -env: - CDK_AWS_REGION: ${{ vars.AWS_REGION }} - CDK_PROJECT_PREFIX: ${{ vars.CDK_PROJECT_PREFIX }} - CDK_VPC_CIDR: ${{ vars.CDK_VPC_CIDR }} - CDK_RAG_ENABLED: ${{ vars.CDK_RAG_ENABLED }} - CDK_RAG_CORS_ORIGINS: ${{ vars.CDK_RAG_CORS_ORIGINS }} - CDK_AWS_ACCOUNT: ${{ secrets.CDK_AWS_ACCOUNT }} - AWS_ROLE_ARN: ${{ secrets.AWS_ROLE_ARN }} - AWS_ACCESS_KEY_ID: ${{ secrets.AWS_ACCESS_KEY_ID }} - AWS_SECRET_ACCESS_KEY: ${{ secrets.AWS_SECRET_ACCESS_KEY }} -``` - -### 4. Shell Scripts - -**Directory:** `scripts/stack-rag-ingestion/` - -**Scripts:** - -1. **install.sh**: Install dependencies - - Install Python packages from pyproject.toml - - Install Node.js packages from package.json - - Verify installations - -2. **build.sh**: Build Docker image - - Build from backend/Dockerfile.rag-ingestion - - Tag with IMAGE_TAG environment variable - - Validate build success - -3. **build-cdk.sh**: Compile TypeScript - - Run `npm run build` in infrastructure/ - - Validate compilation - -4. **synth.sh**: Synthesize CDK - - Source load-env.sh - - Build context parameters - - Run `cdk synth RagIngestionStack` - - Output to infrastructure/cdk.out/ - -5. **deploy.sh**: Deploy stack - - Source load-env.sh - - Check for pre-synthesized templates - - Bootstrap CDK if needed - - Deploy RagIngestionStack - - Output deployment results - -6. **test-docker.sh**: Test Docker image - - Load image from tar or local - - Run container - - Verify Lambda handler - - Verify Python packages - -7. **test-cdk.sh**: Test CloudFormation - - Validate template syntax - - Check required resources - - Verify SSM exports - -8. **push-to-ecr.sh**: Push to ECR - - Create ECR repository if needed - - Authenticate to ECR - - Tag image - - Push to ECR - - Store image tag in SSM - -9. **tag-latest.sh**: Tag as latest - - Tag current image as latest - - Push latest tag to ECR - -**Common Utilities:** -- All scripts source `scripts/common/load-env.sh` -- Use `build_cdk_context_params()` for consistent context -- Follow `set -euo pipefail` error handling -- Use logging functions: `log_info`, `log_error`, `log_success` - -### 5. Lambda Function: RAG Ingestion - -**Docker Image:** `backend/Dockerfile.rag-ingestion` (REUSED, not modified) - -**Handler:** Existing Lambda handler code (REUSED, not modified) - -**Configuration:** -- Architecture: ARM64 (Graviton2) -- Memory: 10240 MB (10 GB) -- Timeout: 900 seconds (15 minutes) -- Runtime: Python 3.11 (via Docker) - -**Environment Variables:** -```typescript -environment: { - S3_ASSISTANTS_DOCUMENTS_BUCKET_NAME: documentsBucket.bucketName, - DYNAMODB_ASSISTANTS_TABLE_NAME: assistantsTable.tableName, - S3_ASSISTANTS_VECTOR_STORE_BUCKET_NAME: vectorBucketName, - S3_ASSISTANTS_VECTOR_STORE_INDEX_NAME: vectorIndexName, - BEDROCK_REGION: config.awsRegion, -} -``` - -**IAM Permissions:** -- S3: Read from Documents Bucket -- DynamoDB: Read/Write to Assistants Table -- S3 Vectors: PutVectors, GetVectors, ListVectors, DeleteVector -- Bedrock: InvokeModel for Titan embeddings - -**Trigger:** -- S3 Event: ObjectCreated on Documents Bucket with prefix "assistants/" - -### 6. S3 Documents Bucket - -**Resource Type:** `AWS::S3::Bucket` - -**Configuration:** -- Bucket Name: `${projectPrefix}-rag-documents` -- Encryption: S3_MANAGED -- Public Access: BLOCK_ALL -- Versioning: Enabled -- Removal Policy: RETAIN -- Auto Delete Objects: false - -**CORS Configuration:** -```typescript -cors: [{ - allowedOrigins: config.ragIngestion.corsOrigins.split(',').map(o => o.trim()), - allowedMethods: [s3.HttpMethods.GET, s3.HttpMethods.PUT, s3.HttpMethods.HEAD], - allowedHeaders: ['Content-Type', 'Content-Length', 'x-amz-*'], - exposedHeaders: ['ETag', 'Content-Length', 'Content-Type'], - maxAge: 3600, -}] -``` - -**Event Notifications:** -- Trigger Lambda on ObjectCreated with prefix "assistants/" - -### 7. S3 Vectors Bucket and Index - -**Vector Bucket:** -- Resource Type: `AWS::S3Vectors::VectorBucket` -- Bucket Name: `${projectPrefix}-rag-vector-store-v1` - -**Vector Index:** -- Resource Type: `AWS::S3Vectors::Index` -- Index Name: `${projectPrefix}-rag-vector-index-v1` -- Data Type: float32 -- Dimension: 1024 (Titan V2) -- Distance Metric: cosine -- Metadata Configuration: - - Filterable: assistant_id, document_id, source - - Non-Filterable: text - -### 8. DynamoDB Assistants Table - -**Configuration:** -- Table Name: `${projectPrefix}-rag-assistants` -- Partition Key: PK (String) -- Sort Key: SK (String) -- Billing Mode: PAY_PER_REQUEST -- Point-in-Time Recovery: Enabled -- Encryption: AWS_MANAGED - -**Global Secondary Indexes:** - -1. **OwnerStatusIndex** - - Partition Key: GSI_PK (String) - - Sort Key: GSI_SK (String) - - Projection: ALL - -2. **VisibilityStatusIndex** - - Partition Key: GSI2_PK (String) - - Sort Key: GSI2_SK (String) - - Projection: ALL - -3. **SharedWithIndex** - - Partition Key: GSI3_PK (String) - - Sort Key: GSI3_SK (String) - - Projection: ALL - -### 9. SSM Parameter Exports - -**Parameters Created:** - -| Parameter Name | Value | Description | -|----------------|-------|-------------| -| `/${projectPrefix}/rag/documents-bucket-name` | Documents Bucket Name | S3 bucket for document uploads | -| `/${projectPrefix}/rag/documents-bucket-arn` | Documents Bucket ARN | S3 bucket ARN | -| `/${projectPrefix}/rag/assistants-table-name` | Assistants Table Name | DynamoDB table name | -| `/${projectPrefix}/rag/assistants-table-arn` | Assistants Table ARN | DynamoDB table ARN | -| `/${projectPrefix}/rag/vector-bucket-name` | Vector Bucket Name | S3 Vectors bucket name | -| `/${projectPrefix}/rag/vector-index-name` | Vector Index Name | S3 Vectors index name | -| `/${projectPrefix}/rag/ingestion-lambda-arn` | Lambda ARN | Ingestion Lambda ARN | -| `/${projectPrefix}/rag-ingestion/image-tag` | Docker Image Tag | Current deployed image tag | - -### 10. ECR Repository - -**Repository Name:** `${projectPrefix}-rag-ingestion` - -**Creation:** Created by CI/CD pipeline (push-to-ecr.sh) - -**Image Tags:** -- Git commit SHA (e.g., `abc1234`) -- `latest` (updated after successful deployment) - -**Lifecycle Policy:** (Optional, can be added later) -- Keep last 10 images -- Expire untagged images after 7 days - -## Data Models - -### DynamoDB Assistants Table Schema - -**Base Table:** -``` -PK: String (Partition Key) -SK: String (Sort Key) -``` - -**Item Types:** - -1. **Assistant Metadata:** -``` -PK: "ASSISTANT#{assistantId}" -SK: "META" -assistantId: String -name: String -description: String -ownerId: String -visibility: String ("private" | "shared" | "public") -status: String ("active" | "archived") -createdAt: ISO8601 Timestamp -updatedAt: ISO8601 Timestamp -GSI_PK: "OWNER#{ownerId}" -GSI_SK: "STATUS#{status}#CREATED#{createdAt}" -GSI2_PK: "VISIBILITY#{visibility}" -GSI2_SK: "STATUS#{status}#CREATED#{createdAt}" -``` - -2. **Shared Access:** -``` -PK: "ASSISTANT#{assistantId}" -SK: "SHARED#{userId}" -userId: String -permission: String ("read" | "write") -sharedAt: ISO8601 Timestamp -GSI3_PK: "USER#{userId}" -GSI3_SK: "ASSISTANT#{assistantId}" -``` - -### S3 Vectors Metadata Schema - -**Vector Metadata:** -```json -{ - "assistant_id": "string", - "document_id": "string", - "source": "string", - "text": "string (non-filterable)", - "chunk_index": "number", - "total_chunks": "number" -} -``` - -**Vector ID Format:** `{assistant_id}#{document_id}#{chunk_index}` - -### S3 Documents Bucket Key Structure - -**Document Upload Path:** -``` -assistants/{assistant_id}/{document_id}/{filename} -``` - -**Example:** -``` -assistants/asst_abc123/doc_xyz789/research_paper.pdf -``` - -## Correctness Properties - -*A property is a characteristic or behavior that should hold true across all valid executions of a system—essentially, a formal statement about what the system should do. Properties serve as the bridge between human-readable specifications and machine-verifiable correctness guarantees.* - - -### Property 1: CloudFormation Template Completeness - -*For any* synthesized CloudFormation template for RagIngestionStack, the template should contain all required AWS resources: S3 Documents Bucket, S3 Vectors Bucket, S3 Vectors Index, DynamoDB Assistants Table, Lambda Function, and all required IAM roles and policies. - -**Validates: Requirements 2.1, 2.2, 2.3, 2.4, 2.5, 2.7, 2.8, 9.1-9.14, 10.1-10.8, 11.1-11.10, 12.1-12.12** - -### Property 2: No Cross-Stack References - -*For any* synthesized CloudFormation template for RagIngestionStack, the template should not contain any direct CloudFormation cross-stack references (Fn::ImportValue) to AppApiStack resources. - -**Validates: Requirements 1.3** - -### Property 3: SSM Parameter Exports - -*For any* synthesized CloudFormation template for RagIngestionStack, the template should create SSM parameters for all exported resource names and ARNs (documents bucket, assistants table, vector bucket, vector index, ingestion lambda) with the correct parameter name pattern `/${projectPrefix}/rag/*`. - -**Validates: Requirements 3.1, 3.2, 3.3, 3.4, 3.5, 3.6, 3.7** - -### Property 4: Configuration Loading - -*For any* set of environment variables and context values, the loadConfig function should correctly load RagIngestionConfig with environment variables taking precedence over context values, and context values taking precedence over defaults. - -**Validates: Requirements 4.1-4.10** - -### Property 5: Script Execution - -*For any* script in `scripts/stack-rag-ingestion/`, when executed with valid environment variables, the script should complete successfully (exit code 0) and produce expected outputs or side effects. - -**Validates: Requirements 7.1-7.14** - -### Property 6: Resource Naming Uniqueness - -*For any* resource created by RagIngestionStack, the resource name should use the "rag-" prefix and should be distinct from any existing AppApiStack resource names (which use "assistants-" prefix), ensuring no naming conflicts. - -**Validates: Requirements 20.1-20.10, 21.1-21.18** - -### Property 7: Docker Image Reuse - -*For any* Docker build of the RAG ingestion Lambda, the build should use the existing `backend/Dockerfile.rag-ingestion` without modifications, and the resulting image should contain the same Lambda handler code as the existing AppApiStack implementation. - -**Validates: Requirements 21.4, 21.5, 21.18** - -## Error Handling - -### CDK Stack Errors - -**Missing SSM Parameters:** -- **Scenario:** Infrastructure Stack not deployed, SSM parameters don't exist -- **Handling:** CDK synthesis will fail with clear error message indicating missing parameters -- **Recovery:** Deploy Infrastructure Stack first - -**Invalid Configuration:** -- **Scenario:** Invalid CORS origins, invalid memory size, invalid timeout -- **Handling:** CDK validation will fail during synthesis with descriptive error -- **Recovery:** Fix configuration values in environment variables or context - -**Resource Name Conflicts:** -- **Scenario:** Resource names already exist (unlikely with "rag-" prefix) -- **Handling:** CloudFormation deployment will fail with resource already exists error -- **Recovery:** Delete conflicting resources or use different project prefix - -### Lambda Function Errors - -**Document Processing Failures:** -- **Scenario:** Invalid document format, corrupted file, unsupported file type -- **Handling:** Lambda logs error, returns failure, document remains in S3 -- **Recovery:** Manual intervention to fix or remove document - -**Bedrock API Errors:** -- **Scenario:** Rate limiting, service unavailable, invalid model ID -- **Handling:** Lambda retries with exponential backoff, logs error if all retries fail -- **Recovery:** Automatic retry on next invocation, or manual re-upload - -**Vector Store Errors:** -- **Scenario:** Vector write failure, index not ready, quota exceeded -- **Handling:** Lambda logs error, document metadata marked as failed in DynamoDB -- **Recovery:** Retry mechanism or manual reprocessing - -**DynamoDB Errors:** -- **Scenario:** Throttling, item size too large, conditional check failure -- **Handling:** Lambda retries with exponential backoff, logs error -- **Recovery:** Automatic retry or manual intervention - -### CI/CD Pipeline Errors - -**Docker Build Failures:** -- **Scenario:** Dockerfile syntax error, missing dependencies, build timeout -- **Handling:** Build job fails, workflow stops, error logged -- **Recovery:** Fix Dockerfile or dependencies, re-run workflow - -**CDK Synthesis Failures:** -- **Scenario:** TypeScript compilation error, invalid CDK code, missing dependencies -- **Handling:** Synth job fails, workflow stops, error logged -- **Recovery:** Fix TypeScript code, re-run workflow - -**Deployment Failures:** -- **Scenario:** CloudFormation rollback, resource limit exceeded, permission denied -- **Handling:** Deploy job fails, CloudFormation rolls back, error logged -- **Recovery:** Fix issue, re-run deployment - -**Test Failures:** -- **Scenario:** Docker image validation fails, CloudFormation template invalid -- **Handling:** Test job fails, workflow stops before deployment -- **Recovery:** Fix issue, re-run workflow - -### Cross-Stack Integration Errors - -**SSM Parameter Not Found:** -- **Scenario:** AppApiStack tries to import RAG resources before RagIngestionStack deployed -- **Handling:** SSM parameter read returns empty or throws error -- **Recovery:** Deploy RagIngestionStack first, or make import optional - -**Resource Access Denied:** -- **Scenario:** AppApiStack ECS task tries to access RAG resources without permissions -- **Handling:** AWS API returns access denied error -- **Recovery:** Grant appropriate IAM permissions to ECS task role - -## Testing Strategy - -### Dual Testing Approach - -This feature requires both unit tests and property-based tests for comprehensive coverage: - -**Unit Tests:** -- Verify specific CloudFormation resource configurations -- Test individual script functions -- Validate configuration loading with specific inputs -- Test error handling for known edge cases - -**Property-Based Tests:** -- Verify CloudFormation template structure across all valid configurations -- Test configuration loading across all valid environment variable combinations -- Verify resource naming patterns across all valid project prefixes -- Test script execution across different environments - -### Unit Testing - -**CDK Stack Tests:** -```typescript -// infrastructure/test/rag-ingestion-stack.test.ts - -describe('RagIngestionStack', () => { - test('creates S3 documents bucket with correct configuration', () => { - // Verify bucket encryption, versioning, CORS - }); - - test('creates DynamoDB table with correct GSIs', () => { - // Verify table keys, GSIs, billing mode - }); - - test('creates Lambda function with correct configuration', () => { - // Verify memory, timeout, environment variables - }); - - test('exports all required SSM parameters', () => { - // Verify SSM parameter names and values - }); - - test('configures IAM permissions correctly', () => { - // Verify Lambda role has required permissions - }); -}); -``` - -**Configuration Tests:** -```typescript -// infrastructure/test/config.test.ts - -describe('RagIngestionConfig', () => { - test('loads from environment variables', () => { - // Set env vars, verify config loaded correctly - }); - - test('falls back to context values', () => { - // No env vars, verify context values used - }); - - test('uses defaults when not specified', () => { - // No env vars or context, verify defaults used - }); -}); -``` - -**Script Tests:** -```bash -# scripts/stack-rag-ingestion/test.sh - -# Test that scripts can be sourced without errors -test_script_syntax() { - bash -n install.sh - bash -n build.sh - bash -n synth.sh - bash -n deploy.sh -} - -# Test that scripts fail on missing environment variables -test_missing_env_vars() { - unset CDK_PROJECT_PREFIX - ! bash synth.sh # Should fail -} -``` - -### Property-Based Testing - -**Property Test Configuration:** -- Minimum 100 iterations per property test -- Each test references its design document property -- Tag format: **Feature: rag-ingestion-stack, Property {number}: {property_text}** - -**Property Test 1: CloudFormation Template Completeness** -```typescript -// Feature: rag-ingestion-stack, Property 1: CloudFormation Template Completeness -// For any synthesized CloudFormation template for RagIngestionStack, -// the template should contain all required AWS resources - -import * as fc from 'fast-check'; - -fc.assert( - fc.property( - fc.record({ - projectPrefix: fc.stringMatching(/^[a-z][a-z0-9-]{1,20}$/), - awsRegion: fc.constantFrom('us-east-1', 'us-west-2', 'eu-west-1'), - corsOrigins: fc.array(fc.webUrl(), { minLength: 1, maxLength: 5 }), - }), - (config) => { - const template = synthesizeStack(config); - - // Verify all required resources present - expect(template.Resources).toHaveProperty('DocumentsBucket'); - expect(template.Resources).toHaveProperty('VectorBucket'); - expect(template.Resources).toHaveProperty('VectorIndex'); - expect(template.Resources).toHaveProperty('AssistantsTable'); - expect(template.Resources).toHaveProperty('IngestionLambda'); - - // Verify resource types - expect(template.Resources.DocumentsBucket.Type).toBe('AWS::S3::Bucket'); - expect(template.Resources.VectorBucket.Type).toBe('AWS::S3Vectors::VectorBucket'); - expect(template.Resources.VectorIndex.Type).toBe('AWS::S3Vectors::Index'); - expect(template.Resources.AssistantsTable.Type).toBe('AWS::DynamoDB::Table'); - expect(template.Resources.IngestionLambda.Type).toBe('AWS::Lambda::Function'); - } - ), - { numRuns: 100 } -); -``` - -**Property Test 2: No Cross-Stack References** -```typescript -// Feature: rag-ingestion-stack, Property 2: No Cross-Stack References -// For any synthesized CloudFormation template for RagIngestionStack, -// the template should not contain any direct CloudFormation cross-stack references - -fc.assert( - fc.property( - fc.record({ - projectPrefix: fc.stringMatching(/^[a-z][a-z0-9-]{1,20}$/), - awsRegion: fc.constantFrom('us-east-1', 'us-west-2'), - }), - (config) => { - const template = synthesizeStack(config); - const templateString = JSON.stringify(template); - - // Verify no Fn::ImportValue references - expect(templateString).not.toContain('Fn::ImportValue'); - expect(templateString).not.toContain('ImportValue'); - - // Verify no references to AppApiStack - expect(templateString).not.toContain('AppApiStack'); - } - ), - { numRuns: 100 } -); -``` - -**Property Test 3: SSM Parameter Exports** -```typescript -// Feature: rag-ingestion-stack, Property 3: SSM Parameter Exports -// For any synthesized CloudFormation template for RagIngestionStack, -// the template should create SSM parameters for all exported resource names - -fc.assert( - fc.property( - fc.record({ - projectPrefix: fc.stringMatching(/^[a-z][a-z0-9-]{1,20}$/), - }), - (config) => { - const template = synthesizeStack(config); - - // Find all SSM parameter resources - const ssmParams = Object.values(template.Resources) - .filter((r: any) => r.Type === 'AWS::SSM::Parameter'); - - // Verify required parameters exist - const paramNames = ssmParams.map((p: any) => p.Properties.Name); - expect(paramNames).toContain(`/${config.projectPrefix}/rag/documents-bucket-name`); - expect(paramNames).toContain(`/${config.projectPrefix}/rag/documents-bucket-arn`); - expect(paramNames).toContain(`/${config.projectPrefix}/rag/assistants-table-name`); - expect(paramNames).toContain(`/${config.projectPrefix}/rag/assistants-table-arn`); - expect(paramNames).toContain(`/${config.projectPrefix}/rag/vector-bucket-name`); - expect(paramNames).toContain(`/${config.projectPrefix}/rag/vector-index-name`); - expect(paramNames).toContain(`/${config.projectPrefix}/rag/ingestion-lambda-arn`); - } - ), - { numRuns: 100 } -); -``` - -**Property Test 4: Configuration Loading** -```typescript -// Feature: rag-ingestion-stack, Property 4: Configuration Loading -// For any set of environment variables and context values, -// the loadConfig function should correctly load RagIngestionConfig - -fc.assert( - fc.property( - fc.record({ - envEnabled: fc.option(fc.boolean()), - contextEnabled: fc.option(fc.boolean()), - envCorsOrigins: fc.option(fc.array(fc.webUrl()).map(urls => urls.join(','))), - contextCorsOrigins: fc.option(fc.array(fc.webUrl()).map(urls => urls.join(','))), - }), - (testCase) => { - // Set environment variables - if (testCase.envEnabled !== null) { - process.env.CDK_RAG_ENABLED = String(testCase.envEnabled); - } - if (testCase.envCorsOrigins !== null) { - process.env.CDK_RAG_CORS_ORIGINS = testCase.envCorsOrigins; - } - - // Create context - const context = { - ragIngestion: { - enabled: testCase.contextEnabled, - corsOrigins: testCase.contextCorsOrigins, - } - }; - - const config = loadConfig(context); - - // Verify precedence: env > context > default - if (testCase.envEnabled !== null) { - expect(config.ragIngestion.enabled).toBe(testCase.envEnabled); - } else if (testCase.contextEnabled !== null) { - expect(config.ragIngestion.enabled).toBe(testCase.contextEnabled); - } else { - expect(config.ragIngestion.enabled).toBe(true); // default - } - - if (testCase.envCorsOrigins !== null) { - expect(config.ragIngestion.corsOrigins).toBe(testCase.envCorsOrigins); - } else if (testCase.contextCorsOrigins !== null) { - expect(config.ragIngestion.corsOrigins).toBe(testCase.contextCorsOrigins); - } - - // Cleanup - delete process.env.CDK_RAG_ENABLED; - delete process.env.CDK_RAG_CORS_ORIGINS; - } - ), - { numRuns: 100 } -); -``` - -**Property Test 6: Resource Naming Uniqueness** -```typescript -// Feature: rag-ingestion-stack, Property 6: Resource Naming Uniqueness -// For any resource created by RagIngestionStack, -// the resource name should use the "rag-" prefix and be distinct from AppApiStack resources - -fc.assert( - fc.property( - fc.record({ - projectPrefix: fc.stringMatching(/^[a-z][a-z0-9-]{1,20}$/), - }), - (config) => { - const template = synthesizeStack(config); - - // Get all resource names - const resourceNames = Object.values(template.Resources) - .map((r: any) => { - // Extract name from different resource types - if (r.Properties.BucketName) return r.Properties.BucketName; - if (r.Properties.TableName) return r.Properties.TableName; - if (r.Properties.FunctionName) return r.Properties.FunctionName; - if (r.Properties.VectorBucketName) return r.Properties.VectorBucketName; - return null; - }) - .filter(name => name !== null); - - // Verify all names use "rag-" prefix - resourceNames.forEach(name => { - expect(name).toMatch(new RegExp(`${config.projectPrefix}-rag-`)); - }); - - // Verify no names use "assistants-" prefix (old naming) - resourceNames.forEach(name => { - expect(name).not.toMatch(/assistants-/); - }); - } - ), - { numRuns: 100 } -); -``` - -### Integration Testing - -**Stack Deployment Test:** -```bash -# Test full deployment cycle -1. Deploy Infrastructure Stack -2. Deploy RAG Ingestion Stack -3. Verify all resources created -4. Upload test document to S3 -5. Verify Lambda triggered -6. Verify embeddings stored in vector store -7. Verify metadata in DynamoDB -8. Clean up test resources -``` - -**Cross-Stack Integration Test:** -```bash -# Test SSM parameter integration -1. Deploy RAG Ingestion Stack -2. Read SSM parameters -3. Verify parameter values match deployed resources -4. Test that AppApiStack can read parameters (future) -``` - -### Test Execution - -**Local Testing:** -```bash -# Run CDK tests -cd infrastructure -npm test - -# Run script tests -cd scripts/stack-rag-ingestion -bash test.sh - -# Synthesize locally -bash synth.sh -``` - -**CI/CD Testing:** -- All tests run automatically on pull requests -- Tests must pass before deployment -- Property tests run with 100 iterations minimum -- Test results uploaded as artifacts - -### Test Coverage Goals - -- CDK Stack: 90% code coverage -- Configuration: 100% code coverage -- Scripts: 80% code coverage -- Property Tests: All 7 properties implemented -- Integration Tests: Full deployment cycle - -## Implementation Notes - -### Phase 1: Infrastructure Setup (This Spec) - -1. Create RagIngestionStack CDK code -2. Add RagIngestionConfig to config.ts -3. Create CI/CD workflow -4. Create shell scripts -5. Deploy and verify - -### Phase 2: Verification (Future) - -1. Deploy both stacks in parallel -2. Test both implementations with same data -3. Verify identical behavior -4. Compare performance metrics - -### Phase 3: Migration (Future) - -1. Update AppApiStack to use new RAG resources via SSM -2. Deploy AppApiStack with new configuration -3. Verify application works with new resources -4. Remove old RAG resources from AppApiStack -5. Clean up old resources - -### Deployment Checklist - -**Prerequisites:** -- [ ] Infrastructure Stack deployed -- [ ] GitHub Variables configured (CDK_RAG_ENABLED, CDK_RAG_CORS_ORIGINS) -- [ ] GitHub Secrets configured (AWS credentials) -- [ ] cdk.context.json updated with ragIngestion config - -**Deployment Steps:** -1. [ ] Merge PR to main branch -2. [ ] Workflow triggers automatically -3. [ ] Monitor workflow execution -4. [ ] Verify all jobs pass -5. [ ] Check CloudFormation stack created -6. [ ] Verify resources in AWS Console -7. [ ] Test Lambda function with sample document -8. [ ] Verify SSM parameters created - -**Verification:** -- [ ] S3 bucket created with correct name -- [ ] DynamoDB table created with GSIs -- [ ] Lambda function deployed with correct config -- [ ] Vector store bucket and index created -- [ ] SSM parameters exported -- [ ] Lambda can process documents -- [ ] Embeddings stored in vector store -- [ ] Metadata stored in DynamoDB - -### Rollback Plan - -**If deployment fails:** -1. CloudFormation automatically rolls back -2. Review CloudFormation events for error details -3. Fix issue in code -4. Re-run workflow - -**If Lambda function fails:** -1. Check CloudWatch Logs for errors -2. Verify IAM permissions -3. Verify environment variables -4. Test with sample document -5. Update Lambda code if needed -6. Redeploy stack - -**If integration issues:** -1. Verify SSM parameters exist -2. Verify parameter values correct -3. Verify IAM permissions for cross-stack access -4. Test parameter reads manually - -### Monitoring and Observability - -**CloudWatch Metrics:** -- Lambda invocations -- Lambda errors -- Lambda duration -- DynamoDB read/write capacity -- S3 bucket requests - -**CloudWatch Logs:** -- Lambda function logs -- CloudFormation deployment logs -- CDK synthesis logs - -**Alarms:** -- Lambda error rate > 5% -- Lambda duration > 10 minutes -- DynamoDB throttling -- S3 4xx/5xx errors - -**Dashboards:** -- RAG Ingestion Pipeline Overview -- Lambda Performance Metrics -- Resource Utilization - -### Security Considerations - -**IAM Permissions:** -- Lambda function has least-privilege permissions -- No wildcard permissions -- Scoped to specific resources - -**Data Encryption:** -- S3 bucket uses S3-managed encryption -- DynamoDB uses AWS-managed encryption -- Data in transit uses TLS - -**Network Security:** -- Lambda runs in VPC (optional, can be added later) -- Security groups restrict access -- No public endpoints - -**Secrets Management:** -- No secrets in code or environment variables -- AWS credentials via IAM roles -- Bedrock API access via IAM - -### Cost Optimization - -**Lambda:** -- ARM64 architecture (20% cheaper) -- Right-sized memory allocation -- Timeout prevents runaway costs - -**DynamoDB:** -- On-demand billing for variable workload -- Point-in-time recovery for data protection - -**S3:** -- Lifecycle policies for old documents (future) -- Intelligent tiering for cost optimization (future) - -**S3 Vectors:** -- Pay per vector stored and queried -- Optimize vector dimension if possible - -### Future Enhancements - -**Performance:** -- Batch processing for multiple documents -- Parallel chunk processing -- Caching for frequently accessed embeddings - -**Features:** -- Support for more document types -- Custom embedding models -- Vector search API -- Document versioning - -**Operations:** -- Automated testing of deployed Lambda -- Canary deployments -- Blue/green deployments -- Automated rollback on errors - -**Integration:** -- AppApiStack migration to new resources -- Shared resource access patterns -- Multi-tenant isolation diff --git a/.kiro/specs/rag-ingestion-stack/requirements.md b/.kiro/specs/rag-ingestion-stack/requirements.md deleted file mode 100644 index d0084d12..00000000 --- a/.kiro/specs/rag-ingestion-stack/requirements.md +++ /dev/null @@ -1,389 +0,0 @@ -# Requirements Document: RAG Ingestion Stack - -## Introduction - -This document specifies the requirements for creating a new independent RAG (Retrieval-Augmented Generation) ingestion stack that is a carbon copy of the existing AppApiStack RAG implementation, but deployed as a separate, modular stack. The new stack will reuse the same Dockerfile (`backend/Dockerfile.rag-ingestion`) and implementation code, establishing an identical parallel deployment that can be verified before migrating away from the AppApiStack implementation. - -**Implementation Strategy:** -- Create NEW stack with IDENTICAL functionality to existing RAG implementation -- Reuse SAME Dockerfile and code (no code changes) -- Deploy as SEPARATE stack with DISTINCT resource names -- Existing AppApiStack RAG resources remain UNCHANGED and OPERATIONAL -- Once verified, existing RAG resources can be removed from AppApiStack in a future phase - -**Important:** This spec creates NEW resources in a NEW stack using the SAME implementation. The existing RAG resources in AppApiStack will remain operational and unchanged. No resources will be removed from AppApiStack as part of this work. - -## Glossary - -- **RAG_Ingestion_Stack**: The new independent CDK stack that owns all RAG-related AWS resources -- **App_API_Stack**: The existing application backend stack that currently contains RAG resources -- **Infrastructure_Stack**: The foundation stack that provides VPC, ALB, and ECS cluster -- **SSM_Parameter_Store**: AWS Systems Manager Parameter Store used for cross-stack resource references -- **Vector_Store**: AWS S3 Vectors service for storing and querying embeddings -- **Ingestion_Lambda**: Docker-based Lambda function that processes documents and generates embeddings -- **Documents_Bucket**: S3 bucket where users upload documents for RAG processing -- **Assistants_Table**: DynamoDB table storing assistant metadata -- **CI_CD_Pipeline**: GitHub Actions workflow for automated build, test, and deployment -- **ECR_Repository**: Amazon Elastic Container Registry for storing Docker images -- **ARM64_Lambda**: Lambda function running on ARM64 (Graviton2) architecture -- **Bedrock_Embeddings**: AWS Bedrock Titan embedding model for generating vector embeddings - -## Requirements - -### Requirement 1: Independent Stack Creation - -**User Story:** As a DevOps engineer, I want the RAG ingestion pipeline in its own CDK stack, so that I can deploy and manage it independently from the application API. - -#### Acceptance Criteria - -1. THE RAG_Ingestion_Stack SHALL be defined in a separate TypeScript file `infrastructure/lib/rag-ingestion-stack.ts` -2. THE RAG_Ingestion_Stack SHALL import network resources from Infrastructure_Stack via SSM_Parameter_Store -3. THE RAG_Ingestion_Stack SHALL NOT have direct CloudFormation cross-stack references to App_API_Stack -4. WHEN RAG_Ingestion_Stack is deployed, THEN it SHALL create all RAG-related resources independently -5. THE RAG_Ingestion_Stack SHALL be registered in `infrastructure/bin/infrastructure.ts` for CDK synthesis - -### Requirement 2: New Resource Creation - -**User Story:** As a cloud architect, I want new RAG resources created in RagIngestionStack, so that the target architecture is established without disrupting existing functionality. - -#### Acceptance Criteria - -1. THE RAG_Ingestion_Stack SHALL create a NEW Documents_Bucket (S3 bucket for document uploads) -2. THE RAG_Ingestion_Stack SHALL create a NEW Vector_Store bucket and index (S3 Vectors resources) -3. THE RAG_Ingestion_Stack SHALL create a NEW Assistants_Table (DynamoDB table) -4. THE RAG_Ingestion_Stack SHALL create a NEW Ingestion_Lambda function (Docker-based Lambda) -5. THE RAG_Ingestion_Stack SHALL configure all IAM permissions for its resources -6. THE RAG_Ingestion_Stack SHALL configure S3 event notifications to trigger its Ingestion_Lambda -7. THE RAG_Ingestion_Stack SHALL configure CORS settings on its Documents_Bucket matching original configuration -8. THE App_API_Stack SHALL continue to own and operate its existing RAG resources unchanged -9. THE existing RAG resources in App_API_Stack SHALL remain functional during and after deployment -10. THE new RAG resources SHALL use distinct names to avoid conflicts (e.g., suffix "-v2" or "-new") - -### Requirement 3: Cross-Stack Communication via SSM - -**User Story:** As a systems architect, I want resource references shared via SSM Parameter Store, so that stacks remain loosely coupled and independently deployable. - -#### Acceptance Criteria - -1. THE RAG_Ingestion_Stack SHALL export Documents_Bucket name to SSM at `/${projectPrefix}/rag/documents-bucket-name` -2. THE RAG_Ingestion_Stack SHALL export Documents_Bucket ARN to SSM at `/${projectPrefix}/rag/documents-bucket-arn` -3. THE RAG_Ingestion_Stack SHALL export Assistants_Table name to SSM at `/${projectPrefix}/rag/assistants-table-name` -4. THE RAG_Ingestion_Stack SHALL export Assistants_Table ARN to SSM at `/${projectPrefix}/rag/assistants-table-arn` -5. THE RAG_Ingestion_Stack SHALL export Vector_Store bucket name to SSM at `/${projectPrefix}/rag/vector-bucket-name` -6. THE RAG_Ingestion_Stack SHALL export Vector_Store index name to SSM at `/${projectPrefix}/rag/vector-index-name` -7. THE RAG_Ingestion_Stack SHALL export Ingestion_Lambda ARN to SSM at `/${projectPrefix}/rag/ingestion-lambda-arn` -8. WHEN App_API_Stack needs RAG resource names, THEN it SHALL import them from SSM_Parameter_Store -9. THE App_API_Stack SHALL NOT hardcode any RAG resource names or ARNs - -### Requirement 4: Configuration Management - -**User Story:** As a developer, I want RAG-specific configuration centralized in config.ts, so that all settings are discoverable and follow project conventions. - -#### Acceptance Criteria - -1. THE config.ts SHALL define a RagIngestionConfig interface with all RAG-specific settings -2. THE RagIngestionConfig SHALL include enabled flag (boolean) -3. THE RagIngestionConfig SHALL include corsOrigins (comma-separated string) -4. THE RagIngestionConfig SHALL include lambdaMemorySize (number, default 10240 MB) -5. THE RagIngestionConfig SHALL include lambdaTimeout (number, default 900 seconds) -6. THE RagIngestionConfig SHALL include embeddingModel (string, default "amazon.titan-embed-text-v2") -7. THE RagIngestionConfig SHALL include vectorDimension (number, default 1024) -8. THE loadConfig function SHALL load RagIngestionConfig from environment variables with context fallback -9. WHEN environment variable CDK_RAG_ENABLED is set, THEN it SHALL override context value -10. WHEN environment variable CDK_RAG_CORS_ORIGINS is set, THEN it SHALL override context value - -### Requirement 5: Docker Build and ECR Management - -**User Story:** As a CI/CD engineer, I want to reuse the existing RAG Lambda Dockerfile, so that the implementation is identical to the current working version. - -#### Acceptance Criteria - -1. THE CI_CD_Pipeline SHALL build Docker image from EXISTING `backend/Dockerfile.rag-ingestion` -2. THE CI_CD_Pipeline SHALL NOT modify the Dockerfile -3. THE CI_CD_Pipeline SHALL tag Docker image with git commit SHA -4. THE CI_CD_Pipeline SHALL export Docker image as tar artifact for job handover -5. THE CI_CD_Pipeline SHALL push Docker image to a NEW ECR_Repository -6. THE CI_CD_Pipeline SHALL create ECR_Repository if it does not exist -7. THE CI_CD_Pipeline SHALL store image tag in SSM at `/${projectPrefix}/rag-ingestion/image-tag` -8. WHEN CDK synthesizes RAG_Ingestion_Stack, THEN it SHALL read image tag from SSM_Parameter_Store -9. THE Docker build SHALL use ARM64_Lambda architecture (ubuntu-24.04-arm runner) -10. THE ECR_Repository SHALL be named `${projectPrefix}-rag-ingestion` (distinct from existing repo) -11. THE Dockerfile SHALL remain shared between old and new implementations - -### Requirement 6: CI/CD Workflow Structure - -**User Story:** As a DevOps engineer, I want a modular GitHub Actions workflow for RAG ingestion, so that it follows project conventions and enables parallel execution. - -#### Acceptance Criteria - -1. THE CI_CD_Pipeline SHALL be defined in `.github/workflows/rag-ingestion.yml` -2. THE CI_CD_Pipeline SHALL have an install job that caches dependencies -3. THE CI_CD_Pipeline SHALL have a build-docker job that builds and exports the Docker image -4. THE CI_CD_Pipeline SHALL have a build-cdk job that compiles TypeScript CDK code -5. THE CI_CD_Pipeline SHALL have a test-docker job that validates the Docker image -6. THE CI_CD_Pipeline SHALL have a test-cdk job that validates CloudFormation templates -7. THE CI_CD_Pipeline SHALL have a synth-cdk job that synthesizes CloudFormation templates -8. THE CI_CD_Pipeline SHALL have a push-to-ecr job that pushes Docker image to ECR -9. THE CI_CD_Pipeline SHALL have a deploy-infrastructure job that deploys the CDK stack -10. WHEN build-docker and build-cdk jobs complete, THEN test jobs SHALL run in parallel -11. WHEN all tests pass, THEN synth-cdk and push-to-ecr jobs SHALL run in parallel -12. WHEN synth-cdk and push-to-ecr complete, THEN deploy-infrastructure job SHALL run - -### Requirement 7: Script-Based Automation - -**User Story:** As a developer, I want all CI/CD logic in shell scripts, so that I can reproduce builds and deployments locally. - -#### Acceptance Criteria - -1. THE scripts SHALL be located in `scripts/stack-rag-ingestion/` directory -2. THE scripts SHALL include `install.sh` for dependency installation -3. THE scripts SHALL include `build.sh` for Docker image building -4. THE scripts SHALL include `build-cdk.sh` for TypeScript compilation -5. THE scripts SHALL include `synth.sh` for CDK template synthesis -6. THE scripts SHALL include `deploy.sh` for CDK stack deployment -7. THE scripts SHALL include `test-docker.sh` for Docker image validation -8. THE scripts SHALL include `test-cdk.sh` for CloudFormation template validation -9. THE scripts SHALL include `push-to-ecr.sh` for ECR image push -10. THE scripts SHALL include `tag-latest.sh` for tagging latest image -11. WHEN any script is executed, THEN it SHALL source `scripts/common/load-env.sh` for configuration -12. WHEN any script fails, THEN it SHALL exit with non-zero status code -13. THE scripts SHALL use `set -euo pipefail` for error handling -14. THE scripts SHALL be executable locally and in CI environments - -### Requirement 8: Deployment Order and Dependencies - -**User Story:** As a deployment engineer, I want clear deployment dependencies, so that stacks deploy in the correct order without failures. - -#### Acceptance Criteria - -1. THE RAG_Ingestion_Stack SHALL depend on Infrastructure_Stack (VPC, subnets) -2. THE RAG_Ingestion_Stack SHALL NOT depend on App_API_Stack -3. THE App_API_Stack SHALL NOT depend on RAG_Ingestion_Stack -4. WHEN Infrastructure_Stack is deployed, THEN RAG_Ingestion_Stack MAY be deployed -5. WHEN RAG_Ingestion_Stack is deployed, THEN App_API_Stack MAY be deployed in parallel -6. THE deployment order SHALL be: Infrastructure_Stack → (RAG_Ingestion_Stack || App_API_Stack) - -### Requirement 9: Lambda Function Configuration - -**User Story:** As a backend engineer, I want the RAG ingestion Lambda properly configured, so that it can process documents efficiently and reliably. - -#### Acceptance Criteria - -1. THE Ingestion_Lambda SHALL use Docker container image from ECR -2. THE Ingestion_Lambda SHALL use ARM64_Lambda architecture -3. THE Ingestion_Lambda SHALL have 10GB memory allocation (10240 MB) -4. THE Ingestion_Lambda SHALL have 15-minute timeout (900 seconds) -5. THE Ingestion_Lambda SHALL have environment variable S3_ASSISTANTS_DOCUMENTS_BUCKET_NAME -6. THE Ingestion_Lambda SHALL have environment variable DYNAMODB_ASSISTANTS_TABLE_NAME -7. THE Ingestion_Lambda SHALL have environment variable S3_ASSISTANTS_VECTOR_STORE_BUCKET_NAME -8. THE Ingestion_Lambda SHALL have environment variable S3_ASSISTANTS_VECTOR_STORE_INDEX_NAME -9. THE Ingestion_Lambda SHALL have environment variable BEDROCK_REGION -10. THE Ingestion_Lambda SHALL have IAM permission to read from Documents_Bucket -11. THE Ingestion_Lambda SHALL have IAM permission to read/write to Assistants_Table -12. THE Ingestion_Lambda SHALL have IAM permission to invoke Bedrock embedding models -13. THE Ingestion_Lambda SHALL have IAM permission to write vectors to Vector_Store -14. WHEN an object is created in Documents_Bucket with prefix "assistants/", THEN Ingestion_Lambda SHALL be triggered - -### Requirement 10: Vector Store Configuration - -**User Story:** As a machine learning engineer, I want the vector store properly configured for Titan embeddings, so that semantic search works correctly. - -#### Acceptance Criteria - -1. THE Vector_Store SHALL be created as AWS::S3Vectors::VectorBucket resource -2. THE Vector_Store SHALL have a vector index as AWS::S3Vectors::Index resource -3. THE vector index SHALL use float32 data type -4. THE vector index SHALL use 1024 dimensions (Titan V2 embedding size) -5. THE vector index SHALL use cosine distance metric -6. THE vector index SHALL mark "text" metadata key as non-filterable -7. THE vector index SHALL allow filtering on "assistant_id", "document_id", and "source" metadata keys -8. THE vector index SHALL depend on Vector_Store bucket creation - -### Requirement 11: DynamoDB Table Configuration - -**User Story:** As a database administrator, I want the Assistants table properly configured, so that assistant metadata is stored efficiently. - -#### Acceptance Criteria - -1. THE Assistants_Table SHALL have partition key "PK" (String) -2. THE Assistants_Table SHALL have sort key "SK" (String) -3. THE Assistants_Table SHALL use PAY_PER_REQUEST billing mode -4. THE Assistants_Table SHALL have point-in-time recovery enabled -5. THE Assistants_Table SHALL have AWS_MANAGED encryption -6. THE Assistants_Table SHALL have OwnerStatusIndex GSI with GSI_PK and GSI_SK -7. THE Assistants_Table SHALL have VisibilityStatusIndex GSI with GSI2_PK and GSI2_SK -8. THE Assistants_Table SHALL have SharedWithIndex GSI with GSI3_PK and GSI3_SK -9. WHEN environment is "prod", THEN Assistants_Table SHALL have RETAIN removal policy -10. WHEN environment is not "prod", THEN Assistants_Table SHALL have DESTROY removal policy - -### Requirement 12: S3 Bucket Configuration - -**User Story:** As a security engineer, I want the documents bucket properly secured, so that user data is protected and accessible only via pre-signed URLs. - -#### Acceptance Criteria - -1. THE Documents_Bucket SHALL have S3_MANAGED encryption -2. THE Documents_Bucket SHALL have BLOCK_ALL public access -3. THE Documents_Bucket SHALL have versioning enabled -4. THE Documents_Bucket SHALL have RETAIN removal policy -5. THE Documents_Bucket SHALL have autoDeleteObjects disabled -6. THE Documents_Bucket SHALL have CORS configuration for browser uploads -7. THE CORS configuration SHALL allow GET, PUT, and HEAD methods -8. THE CORS configuration SHALL allow Content-Type, Content-Length, and x-amz-* headers -9. THE CORS configuration SHALL expose ETag, Content-Length, and Content-Type headers -10. THE CORS configuration SHALL have 3600 second max age -11. WHEN CDK_RAG_CORS_ORIGINS is set, THEN CORS SHALL use those origins -12. WHEN CDK_RAG_CORS_ORIGINS is not set, THEN CORS SHALL use default origins from config - -### Requirement 13: Workflow Triggers and Paths - -**User Story:** As a CI/CD engineer, I want the workflow to trigger on relevant changes, so that deployments happen automatically when needed. - -#### Acceptance Criteria - -1. THE CI_CD_Pipeline SHALL trigger on push to main branch -2. THE CI_CD_Pipeline SHALL trigger on pull requests -3. THE CI_CD_Pipeline SHALL trigger on workflow_dispatch (manual trigger) -4. WHEN files in `backend/src/rag/` change, THEN CI_CD_Pipeline SHALL run -5. WHEN files in `backend/Dockerfile.rag-ingestion` change, THEN CI_CD_Pipeline SHALL run -6. WHEN files in `infrastructure/lib/rag-ingestion-stack.ts` change, THEN CI_CD_Pipeline SHALL run -7. WHEN files in `scripts/stack-rag-ingestion/` change, THEN CI_CD_Pipeline SHALL run -8. WHEN files in `.github/workflows/rag-ingestion.yml` change, THEN CI_CD_Pipeline SHALL run -9. WHEN workflow_dispatch has skip_tests input, THEN test jobs SHALL be skipped if true -10. WHEN workflow_dispatch has skip_deploy input, THEN deploy job SHALL be skipped if true - -### Requirement 14: Environment Variable Configuration - -**User Story:** As a configuration manager, I want all configuration values passed via environment variables, so that secrets and settings are managed securely. - -#### Acceptance Criteria - -1. THE CI_CD_Pipeline SHALL define CDK_AWS_REGION from GitHub Variables -2. THE CI_CD_Pipeline SHALL define CDK_PROJECT_PREFIX from GitHub Variables -3. THE CI_CD_Pipeline SHALL define CDK_VPC_CIDR from GitHub Variables -4. THE CI_CD_Pipeline SHALL define CDK_RAG_ENABLED from GitHub Variables -5. THE CI_CD_Pipeline SHALL define CDK_RAG_CORS_ORIGINS from GitHub Variables -6. THE CI_CD_Pipeline SHALL define CDK_AWS_ACCOUNT from GitHub Secrets -7. THE CI_CD_Pipeline SHALL define AWS_ROLE_ARN from GitHub Secrets -8. THE CI_CD_Pipeline SHALL define AWS_ACCESS_KEY_ID from GitHub Secrets -9. THE CI_CD_Pipeline SHALL define AWS_SECRET_ACCESS_KEY from GitHub Secrets -10. THE CI_CD_Pipeline SHALL define CDK_REQUIRE_APPROVAL with default "never" - -### Requirement 15: AppApiStack Optional Integration - -**User Story:** As an application developer, I want the option to use new RAG resources from AppApiStack, so that I can test the new stack without breaking existing functionality. - -#### Acceptance Criteria - -1. THE App_API_Stack MAY optionally import new RAG resource names from SSM -2. THE App_API_Stack SHALL continue using its existing RAG resources by default -3. THE App_API_Stack SHALL have a configuration flag to switch between old and new RAG resources -4. WHEN using new RAG resources, THEN App_API_Stack SHALL import Documents_Bucket name from SSM at `/${projectPrefix}/rag/documents-bucket-name` -5. WHEN using new RAG resources, THEN App_API_Stack SHALL import Assistants_Table name from SSM at `/${projectPrefix}/rag/assistants-table-name` -6. WHEN using new RAG resources, THEN App_API_Stack SHALL import Vector_Store bucket name from SSM at `/${projectPrefix}/rag/vector-bucket-name` -7. WHEN using new RAG resources, THEN App_API_Stack SHALL import Vector_Store index name from SSM at `/${projectPrefix}/rag/vector-index-name` -8. THE App_API_Stack SHALL NOT be modified as part of this initial implementation -9. THE integration with App_API_Stack SHALL be deferred to a future migration phase -10. THE new RAG_Ingestion_Stack SHALL be independently testable without App_API_Stack changes - -### Requirement 16: Testing Requirements - -**User Story:** As a quality engineer, I want comprehensive tests for the RAG stack, so that deployments are validated before production. - -#### Acceptance Criteria - -1. THE test-docker job SHALL verify Docker image can start successfully -2. THE test-docker job SHALL verify Lambda handler is present in image -3. THE test-docker job SHALL verify required Python packages are installed -4. THE test-cdk job SHALL validate CloudFormation template syntax -5. THE test-cdk job SHALL verify all required resources are present in template -6. THE test-cdk job SHALL verify SSM parameter exports are correct -7. THE test-cdk job SHALL verify IAM permissions are properly configured -8. WHEN any test fails, THEN deployment SHALL NOT proceed -9. WHEN skip_tests input is true, THEN test jobs SHALL be skipped - -### Requirement 17: Artifact Management - -**User Story:** As a CI/CD engineer, I want artifacts properly managed between jobs, so that builds are reproducible and efficient. - -#### Acceptance Criteria - -1. THE install job SHALL cache Python packages with key based on pyproject.toml hash -2. THE install job SHALL cache node_modules with key based on package-lock.json hash -3. THE build-docker job SHALL export Docker image as tar artifact -4. THE build-docker job SHALL upload Docker image artifact with 1-day retention -5. THE synth-cdk job SHALL upload synthesized templates with 7-day retention -6. THE test-docker job SHALL download and load Docker image artifact -7. THE push-to-ecr job SHALL download and load Docker image artifact -8. THE deploy-infrastructure job SHALL download synthesized templates -9. WHEN artifacts are missing, THEN dependent jobs SHALL fail with clear error message - -### Requirement 18: Deployment Outputs and Monitoring - -**User Story:** As an operations engineer, I want deployment outputs captured, so that I can verify successful deployments and troubleshoot issues. - -#### Acceptance Criteria - -1. THE deploy-infrastructure job SHALL output CDK stack outputs to JSON file -2. THE deploy-infrastructure job SHALL upload deployment outputs as artifact with 30-day retention -3. THE deploy-infrastructure job SHALL create GitHub step summary with deployment details -4. THE deployment summary SHALL include AWS region -5. THE deployment summary SHALL include project prefix -6. THE deployment summary SHALL include stack name -7. THE deployment summary SHALL include Docker image tag -8. THE deployment summary SHALL include stack outputs in JSON format -9. WHEN deployment succeeds, THEN summary SHALL show success indicator -10. WHEN deployment fails, THEN error details SHALL be visible in logs - -### Requirement 19: Concurrency Control - -**User Story:** As a deployment engineer, I want deployment concurrency controlled, so that parallel deployments don't cause conflicts. - -#### Acceptance Criteria - -1. THE CI_CD_Pipeline SHALL use concurrency group "rag-ingestion-${{ github.ref }}" -2. THE CI_CD_Pipeline SHALL NOT cancel in-progress deployments -3. WHEN a deployment is running, THEN new deployments SHALL wait -4. WHEN a deployment completes, THEN queued deployments SHALL proceed - -### Requirement 20: Documentation and Naming Conventions - -**User Story:** As a new team member, I want consistent naming conventions, so that I can understand the codebase quickly. - -#### Acceptance Criteria - -1. THE CDK stack class SHALL be named "RagIngestionStack" -2. THE CDK stack file SHALL be named "rag-ingestion-stack.ts" -3. THE workflow file SHALL be named "rag-ingestion.yml" -4. THE scripts directory SHALL be named "stack-rag-ingestion" -5. THE ECR repository SHALL be named "${projectPrefix}-rag-ingestion" -6. THE SSM parameters SHALL use prefix "/${projectPrefix}/rag/" -7. THE CloudFormation outputs SHALL use prefix "RagIngestion" -8. THE resource names SHALL use getResourceName(config, "rag-*") -9. THE environment variables SHALL use prefix "CDK_RAG_" for CDK config -10. THE environment variables SHALL use prefix "ENV_RAG_" for runtime config - -### Requirement 21: Non-Interference and Code Reuse - -**User Story:** As a platform engineer, I want the new RAG stack to be a carbon copy using the same code, so that I can verify identical functionality before migration. - -#### Acceptance Criteria - -1. THE RAG_Ingestion_Stack SHALL NOT modify any existing AppApiStack resources -2. THE RAG_Ingestion_Stack SHALL NOT delete any existing AppApiStack resources -3. THE RAG_Ingestion_Stack SHALL use distinct resource names to avoid conflicts -4. THE RAG_Ingestion_Stack SHALL reuse the SAME Dockerfile as AppApiStack (`backend/Dockerfile.rag-ingestion`) -5. THE RAG_Ingestion_Stack SHALL reuse the SAME Lambda handler code as AppApiStack -6. THE RAG_Ingestion_Stack SHALL use the SAME configuration values as AppApiStack (memory, timeout, etc.) -7. THE RAG_Ingestion_Stack SHALL use the SAME IAM permissions as AppApiStack -8. THE RAG_Ingestion_Stack SHALL use the SAME environment variables as AppApiStack (with new resource names) -9. THE new Documents_Bucket SHALL have a different name than the existing assistants documents bucket -10. THE new Assistants_Table SHALL have a different name than the existing assistants table -11. THE new Vector_Store SHALL have a different name than the existing vector store -12. THE new Ingestion_Lambda SHALL have a different name than the existing ingestion lambda -13. THE new ECR_Repository SHALL have a different name than any existing repositories -14. WHEN RAG_Ingestion_Stack is deployed, THEN existing RAG functionality SHALL continue working -15. WHEN RAG_Ingestion_Stack is deleted, THEN existing RAG functionality SHALL remain unaffected -16. THE deployment of RAG_Ingestion_Stack SHALL NOT require changes to App_API_Stack -17. THE deployment of RAG_Ingestion_Stack SHALL NOT require redeployment of App_API_Stack -18. THE implementation SHALL be functionally identical to the existing AppApiStack RAG implementation diff --git a/.kiro/specs/rag-ingestion-stack/task-7-verification-results.md b/.kiro/specs/rag-ingestion-stack/task-7-verification-results.md deleted file mode 100644 index c4226e6b..00000000 --- a/.kiro/specs/rag-ingestion-stack/task-7-verification-results.md +++ /dev/null @@ -1,319 +0,0 @@ -# Task 7 Verification Results: RagIngestionStack Synthesis - -**Date:** 2025-01-XX -**Task:** Checkpoint - Verify stack can be synthesized -**Status:** ✅ PASSED - -## Summary - -The RagIngestionStack was successfully synthesized locally using `cdk synth RagIngestionStack`. The CloudFormation template was generated without errors and contains all required resources as specified in the design document. - -## Verification Checklist - -### ✅ 1. Stack Synthesis -- **Command:** `npx cdk synth RagIngestionStack --output cdk.out` -- **Result:** SUCCESS (Exit Code: 0) -- **Template Location:** `infrastructure/cdk.out/RagIngestionStack.template.json` -- **Warnings:** Minor deprecation warnings for `pointInTimeRecovery` (non-blocking) - -### ✅ 2. CloudFormation Template Generated -- **File Exists:** Yes -- **File Path:** `infrastructure/cdk.out/RagIngestionStack.template.json` -- **Template Valid:** Yes -- **Description:** "bsu-agentcore RAG Ingestion Stack - Independent RAG Pipeline" - -### ✅ 3. All Required Resources Present - -The synthesized template contains all required AWS resources: - -#### Core Resources (5/5) -1. ✅ **S3 Documents Bucket** (`AWS::S3::Bucket`) - - Resource ID: `RagDocumentsBucketBB693959` - - Bucket Name: `bsu-agentcore-rag-documents` - - Encryption: S3_MANAGED (AES256) - - Versioning: Enabled - - Public Access: BLOCK_ALL - - Removal Policy: RETAIN - -2. ✅ **S3 Vectors Bucket** (`AWS::S3Vectors::VectorBucket`) - - Resource ID: `RagVectorBucket` - - Bucket Name: `bsu-agentcore-rag-vector-store-v1` - -3. ✅ **S3 Vectors Index** (`AWS::S3Vectors::Index`) - - Resource ID: `RagVectorIndex` - - Index Name: `bsu-agentcore-rag-vector-index-v1` - - Data Type: float32 - - Dimension: 1024 - - Distance Metric: cosine - - Non-Filterable Metadata: ["text"] - -4. ✅ **DynamoDB Assistants Table** (`AWS::DynamoDB::Table`) - - Resource ID: `RagAssistantsTable7E3FB294` - - Table Name: `bsu-agentcore-rag-assistants` - - Partition Key: PK (String) - - Sort Key: SK (String) - - Billing Mode: PAY_PER_REQUEST - - Point-in-Time Recovery: Enabled - - Encryption: AWS_MANAGED - - GSIs: OwnerStatusIndex, VisibilityStatusIndex, SharedWithIndex - - Removal Policy: RETAIN (dev environment) - -5. ✅ **Lambda Function** (`AWS::Lambda::Function`) - - Resource ID: `RagIngestionLambdaD39E5146` - - Function Name: `bsu-agentcore-rag-ingestion` - - Architecture: ARM64 - - Memory: 10240 MB (10 GB) - - Timeout: 900 seconds (15 minutes) - - Package Type: Image - - Image URI: References ECR with SSM parameter for tag - -#### Supporting Resources (11/11) -6. ✅ **Lambda IAM Role** (`AWS::IAM::Role`) -7. ✅ **Lambda IAM Policy** (`AWS::IAM::Policy`) -8. ✅ **Lambda Log Group** (`AWS::Logs::LogGroup`) -9. ✅ **Lambda Permission for S3** (`AWS::Lambda::Permission`) -10. ✅ **S3 Event Notifications** (`Custom::S3BucketNotifications`) -11. ✅ **Bucket Notifications Handler Lambda** (`AWS::Lambda::Function`) -12. ✅ **Bucket Notifications Handler Role** (`AWS::IAM::Role`) -13. ✅ **Bucket Notifications Handler Policy** (`AWS::IAM::Policy`) -14. ✅ **7 SSM Parameters** (`AWS::SSM::Parameter`) - See section below - -#### CloudFormation Outputs (5/5) -15. ✅ DocumentsBucketName -16. ✅ AssistantsTableName -17. ✅ IngestionLambdaArn -18. ✅ VectorBucketName -19. ✅ VectorIndexName - -### ✅ 4. No Cross-Stack References to AppApiStack - -**Verification Method:** Searched template for "AppApiStack" and "Fn::ImportValue" - -- ❌ No references to "AppApiStack" found -- ❌ No "Fn::ImportValue" found -- ✅ Stack uses SSM parameters for cross-stack communication (loose coupling) - -**Result:** PASSED - Stack is independently deployable without AppApiStack - -### ✅ 5. SSM Parameter Exports (7/7) - -All required SSM parameters are exported: - -1. ✅ `/bsu-agentcore/rag/documents-bucket-name` - - Description: "RAG documents bucket name" - - Value: References RagDocumentsBucket - -2. ✅ `/bsu-agentcore/rag/documents-bucket-arn` - - Description: "RAG documents bucket ARN" - - Value: References RagDocumentsBucket ARN - -3. ✅ `/bsu-agentcore/rag/assistants-table-name` - - Description: "RAG assistants table name" - - Value: References RagAssistantsTable - -4. ✅ `/bsu-agentcore/rag/assistants-table-arn` - - Description: "RAG assistants table ARN" - - Value: References RagAssistantsTable ARN - -5. ✅ `/bsu-agentcore/rag/vector-bucket-name` - - Description: "RAG vector store bucket name" - - Value: "bsu-agentcore-rag-vector-store-v1" - -6. ✅ `/bsu-agentcore/rag/vector-index-name` - - Description: "RAG vector store index name" - - Value: "bsu-agentcore-rag-vector-index-v1" - -7. ✅ `/bsu-agentcore/rag/ingestion-lambda-arn` - - Description: "RAG ingestion Lambda ARN" - - Value: References RagIngestionLambda ARN - -### ✅ 6. IAM Permissions Configuration - -The Lambda function has the following IAM permissions: - -1. ✅ **S3 Documents Bucket** - Read permissions - - Actions: `s3:GetBucket*`, `s3:GetObject*`, `s3:List*` - - Resource: Documents bucket and objects - -2. ✅ **DynamoDB Assistants Table** - Read/Write permissions - - Actions: `dynamodb:BatchGetItem`, `dynamodb:BatchWriteItem`, `dynamodb:GetItem`, `dynamodb:PutItem`, `dynamodb:Query`, `dynamodb:Scan`, `dynamodb:UpdateItem`, `dynamodb:DeleteItem` - - Resource: Assistants table and indexes - -3. ✅ **S3 Vectors** - Full vector operations - - Actions: `s3vectors:PutVectors`, `s3vectors:GetVectors`, `s3vectors:ListVectors`, `s3vectors:DeleteVector`, `s3vectors:GetIndex`, `s3vectors:GetVectorBucket`, `s3vectors:ListVectorBuckets`, `s3vectors:ListIndexes` - - Resource: Vector bucket and index - -4. ✅ **Bedrock** - Invoke model for embeddings - - Actions: `bedrock:InvokeModel` - - Resource: `arn:aws:bedrock:us-west-2::foundation-model/amazon.titan-embed-text-v2*` - -### ✅ 7. S3 Event Notifications - -- ✅ Event Type: `s3:ObjectCreated:*` -- ✅ Prefix Filter: `assistants/` -- ✅ Destination: RagIngestionLambda -- ✅ Lambda Permission: Granted for S3 to invoke Lambda - -### ✅ 8. Lambda Environment Variables - -The Lambda function has all required environment variables: - -1. ✅ `S3_ASSISTANTS_DOCUMENTS_BUCKET_NAME` - References RagDocumentsBucket -2. ✅ `DYNAMODB_ASSISTANTS_TABLE_NAME` - References RagAssistantsTable -3. ✅ `S3_ASSISTANTS_VECTOR_STORE_BUCKET_NAME` - "bsu-agentcore-rag-vector-store-v1" -4. ✅ `S3_ASSISTANTS_VECTOR_STORE_INDEX_NAME` - "bsu-agentcore-rag-vector-index-v1" -5. ✅ `BEDROCK_REGION` - "us-west-2" - -### ✅ 9. Resource Naming Convention - -All resources use the "rag-" prefix as specified: - -- ✅ `bsu-agentcore-rag-documents` (S3 bucket) -- ✅ `bsu-agentcore-rag-vector-store-v1` (Vector bucket) -- ✅ `bsu-agentcore-rag-vector-index-v1` (Vector index) -- ✅ `bsu-agentcore-rag-assistants` (DynamoDB table) -- ✅ `bsu-agentcore-rag-ingestion` (Lambda function) - -**No conflicts with existing "assistants-" prefixed resources** - -### ✅ 10. SSM Parameter Imports - -The stack imports required parameters from Infrastructure Stack: - -1. ✅ `/bsu-agentcore/network/vpc-id` -2. ✅ `/bsu-agentcore/network/vpc-cidr` -3. ✅ `/bsu-agentcore/network/private-subnet-ids` -4. ✅ `/bsu-agentcore/network/availability-zones` -5. ✅ `/bsu-agentcore/rag-ingestion/image-tag` - -**Note:** These parameters must exist in SSM before deployment. They are created by: -- Infrastructure Stack (network parameters) -- CI/CD pipeline (image-tag parameter) - -## Configuration Verification - -### CDK Configuration (config.ts) -- ✅ RagIngestionConfig interface defined -- ✅ Configuration loading with env var precedence -- ✅ Default values set correctly: - - enabled: true - - lambdaMemorySize: 10240 MB - - lambdaTimeout: 900 seconds - - embeddingModel: "amazon.titan-embed-text-v2" - - vectorDimension: 1024 - - vectorDistanceMetric: "cosine" - -### Stack Registration -- ✅ RagIngestionStack imported in `infrastructure/bin/infrastructure.ts` -- ✅ Stack instantiated with config -- ✅ Conditional deployment based on `config.ragIngestion.enabled` - -## Warnings and Notes - -### Non-Blocking Warnings -1. **Deprecation Warning:** `pointInTimeRecovery` is deprecated, should use `pointInTimeRecoverySpecification` - - **Impact:** None - CDK handles this automatically - - **Action:** Can be updated in future refactoring - -2. **VPC Import Warning:** `fromVpcAttributes` with list tokens - - **Impact:** None for this stack (VPC not actively used by Lambda) - - **Action:** No action needed - this is expected behavior with SSM parameters - -### Missing Configuration (Non-Blocking) -- `ragIngestion` section not in `cdk.context.json` -- **Impact:** None - defaults are used from config.ts -- **Action:** Can be added for explicit configuration (Task 10) - -## Deployment Prerequisites - -Before deploying this stack, ensure: - -1. ✅ **Infrastructure Stack deployed** - Provides VPC and network SSM parameters -2. ⚠️ **ECR Repository created** - Must be created by CI/CD pipeline -3. ⚠️ **Docker image pushed to ECR** - Required for Lambda function -4. ⚠️ **Image tag stored in SSM** - Parameter `/bsu-agentcore/rag-ingestion/image-tag` - -**Note:** Items 2-4 are handled by the CI/CD workflow (`.github/workflows/rag-ingestion.yml`) - -## Test Results - -### Synthesis Test -- **Command:** `npx cdk synth RagIngestionStack` -- **Result:** ✅ SUCCESS -- **Exit Code:** 0 -- **Template Size:** ~830 lines -- **Resource Count:** 26 resources - -### Template Validation -- **Syntax:** ✅ Valid JSON -- **Structure:** ✅ Valid CloudFormation -- **Resources:** ✅ All required resources present -- **Outputs:** ✅ All required outputs present -- **Parameters:** ✅ All required parameters present - -## Compliance with Requirements - -### Requirements Coverage - -| Requirement | Status | Notes | -|------------|--------|-------| -| 1.1 - Separate TypeScript file | ✅ | `infrastructure/lib/rag-ingestion-stack.ts` | -| 1.2 - Import via SSM | ✅ | VPC and network resources imported | -| 1.3 - No cross-stack refs | ✅ | No Fn::ImportValue found | -| 1.4 - Independent deployment | ✅ | Stack synthesizes independently | -| 1.5 - Registered in CDK app | ✅ | Added to `infrastructure/bin/infrastructure.ts` | -| 2.1 - Documents Bucket | ✅ | Created with correct config | -| 2.2 - Vector Store | ✅ | Bucket and index created | -| 2.3 - Assistants Table | ✅ | Created with GSIs | -| 2.4 - Ingestion Lambda | ✅ | Created with Docker image | -| 2.5 - IAM Permissions | ✅ | All permissions configured | -| 2.6 - S3 Event Notifications | ✅ | Configured for assistants/ prefix | -| 2.7 - CORS Settings | ✅ | Configured (when corsOrigins set) | -| 3.1-3.7 - SSM Exports | ✅ | All 7 parameters exported | -| 4.1-4.10 - Configuration | ✅ | RagIngestionConfig implemented | -| 9.1-9.14 - Lambda Config | ✅ | All settings correct | -| 10.1-10.8 - Vector Store | ✅ | Configured correctly | -| 11.1-11.10 - DynamoDB | ✅ | Table and GSIs configured | -| 12.1-12.12 - S3 Bucket | ✅ | Security and CORS configured | -| 20.1-20.10 - Naming | ✅ | All resources use "rag-" prefix | -| 21.1-21.18 - Non-interference | ✅ | No conflicts with existing resources | - -## Recommendations - -### Immediate Actions (None Required) -The stack is ready for the next phase (Task 8: Write CDK unit tests). - -### Future Improvements -1. **Add ragIngestion to cdk.context.json** (Task 10) - - Provides explicit configuration - - Makes CORS origins configurable - -2. **Update pointInTimeRecovery usage** - - Replace deprecated property with `pointInTimeRecoverySpecification` - - Low priority - non-breaking change - -3. **Add integration tests** - - Test actual deployment to AWS - - Verify Lambda can process documents - - Validate vector store operations - -## Conclusion - -✅ **Task 7 PASSED** - -The RagIngestionStack successfully synthesizes and generates a valid CloudFormation template with all required resources. The stack: - -- Contains all 26 required AWS resources -- Exports all 7 SSM parameters for cross-stack communication -- Has no cross-stack references to AppApiStack -- Uses distinct "rag-" prefixed resource names -- Configures all IAM permissions correctly -- Sets up S3 event notifications properly -- Is independently deployable - -**Next Steps:** -- Proceed to Task 8: Write CDK unit tests -- Continue with remaining tasks in the implementation plan - -**Verified By:** Kiro AI Agent -**Verification Date:** 2025-01-XX diff --git a/.kiro/specs/rag-ingestion-stack/tasks.md b/.kiro/specs/rag-ingestion-stack/tasks.md deleted file mode 100644 index 6fcaab47..00000000 --- a/.kiro/specs/rag-ingestion-stack/tasks.md +++ /dev/null @@ -1,443 +0,0 @@ -# Implementation Plan: RAG Ingestion Stack - -## Overview - -This implementation plan creates a new independent RAG ingestion stack that is a carbon copy of the existing AppApiStack RAG implementation. The new stack will reuse the same Dockerfile and code, but deploy as a separate modular stack with distinct resource names and its own CI/CD pipeline. - -**Key Principles:** -- Reuse existing `backend/Dockerfile.rag-ingestion` without modifications -- Create new resources with "rag-" prefix (distinct from "assistants-" prefix) -- Follow project DevOps conventions (SSM parameters, script-based automation) -- Deploy independently without affecting existing AppApiStack resources - -## Tasks - -- [x] 1. Add RAG Ingestion configuration to config.ts - - Add RagIngestionConfig interface to config.ts - - Add ragIngestion field to AppConfig interface - - Implement configuration loading with env var precedence - - Add validation for RAG configuration values - - _Requirements: 4.1-4.10_ - -- [x] 2. Create RagIngestionStack CDK code - - [x] 2.1 Create infrastructure/lib/rag-ingestion-stack.ts file - - Define RagIngestionStack class extending cdk.Stack - - Define RagIngestionStackProps interface - - Import VPC and network resources from Infrastructure Stack via SSM - - Apply standard tags using applyStandardTags helper - - _Requirements: 1.1, 1.2, 1.3_ - - - [x] 2.2 Create S3 Documents Bucket - - Create S3 bucket with name `${projectPrefix}-rag-documents` - - Configure S3_MANAGED encryption - - Configure BLOCK_ALL public access - - Enable versioning - - Set RETAIN removal policy - - Configure CORS from config.ragIngestion.corsOrigins - - _Requirements: 2.1, 12.1-12.12_ - - - [x] 2.3 Create S3 Vectors Bucket and Index - - Create CfnResource for AWS::S3Vectors::VectorBucket - - Set bucket name to `${projectPrefix}-rag-vector-store-v1` - - Create CfnResource for AWS::S3Vectors::Index - - Set index name to `${projectPrefix}-rag-vector-index-v1` - - Configure float32 data type, 1024 dimensions, cosine metric - - Configure metadata (filterable: assistant_id, document_id, source; non-filterable: text) - - Add dependency: index depends on bucket - - _Requirements: 2.2, 10.1-10.8_ - - - [x] 2.4 Create DynamoDB Assistants Table - - Create DynamoDB table with name `${projectPrefix}-rag-assistants` - - Configure PK (String) and SK (String) keys - - Set PAY_PER_REQUEST billing mode - - Enable point-in-time recovery - - Set AWS_MANAGED encryption - - Add OwnerStatusIndex GSI (GSI_PK, GSI_SK) - - Add VisibilityStatusIndex GSI (GSI2_PK, GSI2_SK) - - Add SharedWithIndex GSI (GSI3_PK, GSI3_SK) - - Set removal policy based on environment (RETAIN for prod, DESTROY otherwise) - - _Requirements: 2.3, 11.1-11.10_ - - - - [x] 2.5 Create Lambda Function - - Reference ECR repository `${projectPrefix}-rag-ingestion` - - Import image tag from SSM parameter `/${projectPrefix}/rag-ingestion/image-tag` - - Create DockerImageFunction with ARM64 architecture - - Set memory to config.ragIngestion.lambdaMemorySize (10240 MB) - - Set timeout to config.ragIngestion.lambdaTimeout (900 seconds) - - Configure environment variables (S3_ASSISTANTS_DOCUMENTS_BUCKET_NAME, DYNAMODB_ASSISTANTS_TABLE_NAME, S3_ASSISTANTS_VECTOR_STORE_BUCKET_NAME, S3_ASSISTANTS_VECTOR_STORE_INDEX_NAME, BEDROCK_REGION) - - _Requirements: 2.4, 9.1-9.14_ - - - [x] 2.6 Configure IAM Permissions - - Grant Lambda read permission on Documents Bucket - - Grant Lambda read/write permission on Assistants Table - - Add IAM policy for S3 Vectors operations (PutVectors, GetVectors, ListVectors, DeleteVector) - - Add IAM policy for Bedrock InvokeModel on Titan embeddings - - _Requirements: 2.5, 9.10-9.13_ - - - [x] 2.7 Configure S3 Event Notifications - - Add S3 event notification on Documents Bucket - - Trigger Lambda on ObjectCreated events - - Filter by prefix "assistants/" - - _Requirements: 2.7, 9.14_ - - - [x] 2.8 Export SSM Parameters - - Export Documents Bucket name to `/${projectPrefix}/rag/documents-bucket-name` - - Export Documents Bucket ARN to `/${projectPrefix}/rag/documents-bucket-arn` - - Export Assistants Table name to `/${projectPrefix}/rag/assistants-table-name` - - Export Assistants Table ARN to `/${projectPrefix}/rag/assistants-table-arn` - - Export Vector Bucket name to `/${projectPrefix}/rag/vector-bucket-name` - - Export Vector Index name to `/${projectPrefix}/rag/vector-index-name` - - Export Lambda ARN to `/${projectPrefix}/rag/ingestion-lambda-arn` - - _Requirements: 3.1-3.7_ - - - [x] 2.9 Add CloudFormation Outputs - - Output Documents Bucket name - - Output Assistants Table name - - Output Lambda function ARN - - Output Vector Bucket name - - Output Vector Index name - - _Requirements: 18.1-18.10_ - -- [x] 3. Register stack in CDK app - - Import RagIngestionStack in infrastructure/bin/infrastructure.ts - - Instantiate RagIngestionStack with config - - Ensure stack is synthesized when running cdk synth - - _Requirements: 1.5_ - -- [x] 4. Create shell scripts for RAG ingestion stack - - [x] 4.1 Create scripts/stack-rag-ingestion/install.sh - - Source common/load-env.sh - - Install Python dependencies from backend/pyproject.toml - - Install Node.js dependencies from infrastructure/package.json - - Verify installations - - _Requirements: 7.1, 7.2_ - - - [x] 4.2 Create scripts/stack-rag-ingestion/build.sh - - Source common/load-env.sh - - Build Docker image from backend/Dockerfile.rag-ingestion - - Tag with IMAGE_TAG environment variable - - Validate build success - - _Requirements: 7.1, 7.3_ - - - [x] 4.3 Create scripts/stack-rag-ingestion/build-cdk.sh - - Source common/load-env.sh - - Run npm run build in infrastructure/ - - Validate TypeScript compilation - - _Requirements: 7.1, 7.4_ - - - [x] 4.4 Create scripts/stack-rag-ingestion/synth.sh - - Source common/load-env.sh - - Build CDK context parameters using build_cdk_context_params() - - Run cdk synth RagIngestionStack with context parameters - - Output to infrastructure/cdk.out/ - - _Requirements: 7.1, 7.5_ - - - [x] 4.5 Create scripts/stack-rag-ingestion/deploy.sh - - Source common/load-env.sh - - Check for pre-synthesized templates in cdk.out/ - - Bootstrap CDK if needed - - Build CDK context parameters if synthesizing during deploy - - Deploy RagIngestionStack - - Output deployment results to cdk-outputs-rag-ingestion.json - - _Requirements: 7.1, 7.6_ - - - [x] 4.6 Create scripts/stack-rag-ingestion/test-docker.sh - - Source common/load-env.sh - - Load Docker image from tar or local - - Run container - - Verify Lambda handler exists - - Verify Python packages installed - - _Requirements: 7.1, 7.7_ - - - [x] 4.7 Create scripts/stack-rag-ingestion/test-cdk.sh - - Source common/load-env.sh - - Validate CloudFormation template syntax - - Check for required resources in template - - Verify SSM parameter exports - - _Requirements: 7.1, 7.8_ - - - [x] 4.8 Create scripts/stack-rag-ingestion/push-to-ecr.sh - - Source common/load-env.sh - - Create ECR repository if it doesn't exist - - Authenticate to ECR - - Tag Docker image with ECR URI - - Push image to ECR - - Store image tag in SSM parameter `/${projectPrefix}/rag-ingestion/image-tag` - - _Requirements: 7.1, 7.9, 5.1-5.11_ - - - [x] 4.9 Create scripts/stack-rag-ingestion/tag-latest.sh - - Source common/load-env.sh - - Tag current image as latest - - Push latest tag to ECR - - _Requirements: 7.1, 7.10_ - -- [x] 5. Update common/load-env.sh for RAG configuration - - Add CDK_RAG_ENABLED export with env var and context fallback - - Add CDK_RAG_CORS_ORIGINS export with env var and context fallback - - Add CDK_RAG_LAMBDA_MEMORY export with env var and context fallback - - Add CDK_RAG_LAMBDA_TIMEOUT export with env var and context fallback - - Add context parameters for RAG config in build_cdk_context_params() - - _Requirements: 4.1-4.10_ - -- [x] 6. Create GitHub Actions workflow - - [x] 6.1 Create .github/workflows/rag-ingestion.yml - - Define workflow name and triggers (push to main, pull requests, workflow_dispatch) - - Configure path filters (backend/src/rag/, backend/Dockerfile.rag-ingestion, infrastructure/lib/rag-ingestion-stack.ts, scripts/stack-rag-ingestion/, .github/workflows/rag-ingestion.yml) - - Define environment variables (CDK_AWS_REGION, CDK_PROJECT_PREFIX, CDK_VPC_CIDR, CDK_RAG_ENABLED, CDK_RAG_CORS_ORIGINS, CDK_AWS_ACCOUNT, AWS credentials) - - Configure concurrency group "rag-ingestion-${{ github.ref }}" - - _Requirements: 6.1, 13.1-13.10, 14.1-14.10, 19.1-19.4_ - - - [x] 6.2 Add install job - - Run on ubuntu-latest - - Checkout code - - Install system dependencies (scripts/common/install-deps.sh) - - Install RAG dependencies (scripts/stack-rag-ingestion/install.sh) - - Cache Python packages - - Cache node_modules - - _Requirements: 6.2, 17.1, 17.2_ - - - [x] 6.3 Add build-docker job - - Run on ubuntu-latest - - Depend on install job - - Checkout code - - Set image tag from git commit SHA - - Set up Docker Buildx - - Build Docker image from backend/Dockerfile.rag-ingestion - - Export image as tar artifact - - Upload artifact with 1-day retention - - Output image-tag - - _Requirements: 6.3, 17.3, 17.4_ - - - [x] 6.4 Add build-cdk job - - Run on ubuntu-latest - - Depend on install job - - Checkout code - - Restore node_modules cache - - Build CDK (scripts/stack-rag-ingestion/build-cdk.sh) - - _Requirements: 6.4_ - - - [x] 6.5 Add test-docker job - - Run on ubuntu-latest - - Depend on build-docker job - - Skip if skip_tests input is true - - Checkout code - - Download Docker image artifact - - Load Docker image - - Test Docker image (scripts/stack-rag-ingestion/test-docker.sh) - - _Requirements: 6.5, 16.1-16.3, 17.6_ - - - [x] 6.6 Add test-cdk job - - Run on ubuntu-latest - - Depend on synth-cdk job - - Skip if skip_tests input is true - - Checkout code - - Restore node_modules cache - - Download synthesized templates - - Configure AWS credentials - - Install system dependencies - - Validate CloudFormation template (scripts/stack-rag-ingestion/test-cdk.sh) - - _Requirements: 6.6, 16.4-16.7_ - - - [x] 6.7 Add synth-cdk job - - Run on ubuntu-24.04-arm (ARM64 runner for Lambda builds) - - Depend on build-cdk job - - Checkout code - - Restore node_modules cache - - Configure AWS credentials - - Install system dependencies - - Set up Docker Buildx - - Synthesize CloudFormation template (scripts/stack-rag-ingestion/synth.sh) - - Upload synthesized templates with 7-day retention - - _Requirements: 6.7, 17.5_ - - - [x] 6.8 Add push-to-ecr job - - Run on ubuntu-latest - - Depend on build-docker, test-docker jobs - - Skip if any dependency failed - - Checkout code - - Download Docker image artifact - - Load Docker image - - Configure AWS credentials - - Push to ECR (scripts/stack-rag-ingestion/push-to-ecr.sh) - - Output image-tag - - _Requirements: 6.8, 17.7_ - - - [x] 6.9 Add deploy-infrastructure job - - Run on ubuntu-24.04-arm (ARM64 runner) - - Depend on test-cdk, push-to-ecr jobs - - Skip if not push to main or workflow_dispatch - - Skip if skip_deploy input is true - - Checkout code - - Restore node_modules cache - - Download synthesized templates - - Configure AWS credentials - - Install system dependencies - - Set up Docker Buildx - - Deploy infrastructure (scripts/stack-rag-ingestion/deploy.sh) - - Tag image as latest (scripts/stack-rag-ingestion/tag-latest.sh) - - Upload deployment outputs with 30-day retention - - Create deployment summary - - _Requirements: 6.9, 17.8, 18.1-18.10_ - -- [x] 7. Checkpoint - Verify stack can be synthesized - - Run cdk synth RagIngestionStack locally - - Verify CloudFormation template generated - - Check that all resources are present - - Verify no cross-stack references to AppApiStack - - Ensure all tests pass, ask the user if questions arise. - - -- [x] 8. Write CDK unit tests - - [x] 8.1 Create infrastructure/test/rag-ingestion-stack.test.ts - - Test S3 documents bucket configuration (encryption, versioning, CORS) - - Test DynamoDB table configuration (keys, GSIs, billing mode) - - Test Lambda function configuration (memory, timeout, environment variables) - - Test IAM permissions (S3, DynamoDB, Bedrock, S3 Vectors) - - Test SSM parameter exports (all 7 parameters) - - Test CloudFormation outputs - - _Requirements: 16.1-16.9_ - - - [x] 8.2 Create infrastructure/test/config.test.ts for RAG config - - Test configuration loading from environment variables - - Test configuration fallback to context values - - Test configuration defaults - - Test configuration validation - - _Requirements: 4.1-4.10_ - -- [x] 9. Write property-based tests - - [x] 9.1 Write property test for CloudFormation template completeness - - **Property 1: CloudFormation Template Completeness** - - **Validates: Requirements 2.1, 2.2, 2.3, 2.4, 2.5, 2.7, 2.8, 9.1-9.14, 10.1-10.8, 11.1-11.10, 12.1-12.12** - - Generate random valid configurations (projectPrefix, awsRegion, corsOrigins) - - Synthesize stack for each configuration - - Verify all required resources present (S3 bucket, Vector bucket, Vector index, DynamoDB table, Lambda function) - - Verify resource types correct - - Run 100 iterations - - _Requirements: 2.1-2.8, 9.1-9.14, 10.1-10.8, 11.1-11.10, 12.1-12.12_ - - - [x] 9.2 Write property test for no cross-stack references - - **Property 2: No Cross-Stack References** - - **Validates: Requirements 1.3** - - Generate random valid configurations - - Synthesize stack for each configuration - - Verify no Fn::ImportValue in template - - Verify no references to AppApiStack - - Run 100 iterations - - _Requirements: 1.3_ - - - [x] 9.3 Write property test for SSM parameter exports - - **Property 3: SSM Parameter Exports** - - **Validates: Requirements 3.1-3.7** - - Generate random valid projectPrefix values - - Synthesize stack for each configuration - - Verify all 7 SSM parameters present - - Verify parameter names follow pattern `/${projectPrefix}/rag/*` - - Run 100 iterations - - _Requirements: 3.1-3.7_ - - - [x] 9.4 Write property test for configuration loading - - **Property 4: Configuration Loading** - - **Validates: Requirements 4.1-4.10** - - Generate random combinations of environment variables and context values - - Load configuration for each combination - - Verify precedence: env > context > default - - Verify all config fields loaded correctly - - Run 100 iterations - - _Requirements: 4.1-4.10_ - - - [x] 9.5 Write property test for resource naming uniqueness - - **Property 6: Resource Naming Uniqueness** - - **Validates: Requirements 20.1-20.10, 21.1-21.18** - - Generate random valid projectPrefix values - - Synthesize stack for each configuration - - Extract all resource names from template - - Verify all names use "rag-" prefix - - Verify no names use "assistants-" prefix - - Run 100 iterations - - _Requirements: 20.1-20.10, 21.1-21.18_ - -- [x] 10. Update cdk.context.json with RAG configuration - - Add ragIngestion section to cdk.context.json - - Set enabled: true - - Set corsOrigins with appropriate values for environment - - Set lambdaMemorySize: 10240 - - Set lambdaTimeout: 900 - - Set embeddingModel: "amazon.titan-embed-text-v2" - - Set vectorDimension: 1024 - - Set vectorDistanceMetric: "cosine" - - _Requirements: 4.1-4.10_ - -- [x] 11. Configure GitHub repository settings - - Add GitHub Variable: CDK_RAG_ENABLED=true - - Add GitHub Variable: CDK_RAG_CORS_ORIGINS (comma-separated origins) - - Verify existing secrets are present (CDK_AWS_ACCOUNT, AWS_ROLE_ARN, AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY) - - _Requirements: 14.1-14.10_ - -- [x] 12. Checkpoint - Test full CI/CD pipeline - - Create feature branch - - Push changes to trigger workflow - - Monitor workflow execution - - Verify all jobs pass - - Verify Docker image builds - - Verify CDK synthesizes - - Verify tests pass - - Do NOT deploy yet (skip_deploy: true) - - Ensure all tests pass, ask the user if questions arise. - -- [x] 13. Deploy to AWS - - Merge feature branch to main - - Monitor workflow execution - - Verify deployment succeeds - - Check CloudFormation stack in AWS Console - - Verify all resources created - - _Requirements: 8.1-8.6_ - -- [x] 14. Verify deployed resources - - Check S3 bucket exists with correct name - - Check DynamoDB table exists with GSIs - - Check Lambda function exists with correct configuration - - Check Vector store bucket and index exist - - Check SSM parameters exported - - Check CloudWatch Logs group created - - _Requirements: 2.1-2.8, 3.1-3.7_ - -- [x] 15. Test Lambda function - - Upload test document to S3 bucket with prefix "assistants/" - - Verify Lambda triggered by S3 event - - Check CloudWatch Logs for Lambda execution - - Verify embeddings stored in vector store - - Verify metadata stored in DynamoDB - - Query vector store to verify search works - - _Requirements: 9.1-9.14_ - -- [x] 16. Final verification - - Verify existing AppApiStack resources unchanged - - Verify existing RAG functionality still works - - Verify new RAG stack operates independently - - Verify no naming conflicts - - Document any issues or observations - - _Requirements: 21.1-21.18_ - -## Notes - -- Tasks marked with `*` are optional and can be skipped for faster MVP -- Each task references specific requirements for traceability -- Checkpoints ensure incremental validation -- Property tests validate universal correctness properties -- Unit tests validate specific examples and edge cases -- The implementation reuses existing Dockerfile and Lambda code without modifications -- All new resources use "rag-" prefix to avoid conflicts with existing "assistants-" resources -- The stack can be deployed independently without affecting AppApiStack - -## Success Criteria - -- [ ] RagIngestionStack can be synthesized without errors -- [ ] RagIngestionStack can be deployed independently -- [ ] All resources created with correct configuration -- [ ] Lambda function can process documents successfully -- [ ] SSM parameters exported correctly -- [ ] CI/CD pipeline runs successfully -- [ ] No interference with existing AppApiStack resources -- [ ] All tests pass (unit tests and property tests) -- [ ] Documentation complete and accurate diff --git a/.kiro/specs/runtime-config/design.md b/.kiro/specs/runtime-config/design.md deleted file mode 100644 index 8db7e98d..00000000 --- a/.kiro/specs/runtime-config/design.md +++ /dev/null @@ -1,764 +0,0 @@ -# Runtime Configuration Feature - Design Document - -## Architecture Overview - -``` -┌─────────────────────────────────────────────────────────────────┐ -│ Deployment Time │ -├─────────────────────────────────────────────────────────────────┤ -│ │ -│ InfrastructureStack AppApiStack │ -│ │ │ │ -│ ├─ ALB URL ────────────────┼─> SSM Parameter │ -│ │ │ /project/network/alb-url │ -│ │ │ │ -│ InferenceApiStack │ │ -│ │ │ │ -│ ├─ Runtime ARN ────────────┼─> SSM Parameter │ -│ │ /project/inference-api/ │ -│ │ runtime-endpoint-url │ -│ │ │ -│ ▼ │ -│ FrontendStack │ -│ │ │ -│ ┌───────────────┴───────────────┐ │ -│ │ │ │ -│ ▼ ▼ │ -│ Read SSM Parameters Generate config.json │ -│ │ │ -│ ▼ │ -│ Deploy to S3 + CloudFront│ -│ │ -└─────────────────────────────────────────────────────────────────┘ - -┌─────────────────────────────────────────────────────────────────┐ -│ Runtime (Browser) │ -├─────────────────────────────────────────────────────────────────┤ -│ │ -│ 1. User navigates to app │ -│ │ │ -│ ▼ │ -│ 2. Angular bootstrap starts │ -│ │ │ -│ ▼ │ -│ 3. APP_INITIALIZER runs │ -│ │ │ -│ ├─> Fetch /config.json from CloudFront │ -│ │ │ -│ ├─> Parse and validate configuration │ -│ │ │ -│ ├─> Store in ConfigService │ -│ │ │ -│ ▼ │ -│ 4. App initialization completes │ -│ │ │ -│ ▼ │ -│ 5. Services use ConfigService.get('appApiUrl') │ -│ │ -└─────────────────────────────────────────────────────────────────┘ -``` - -## Component Design - -### 0. New Configuration Property: Production Flag - -Following the configuration flow pattern from devops.md, we need to add a `production` boolean property: - -#### Step 1: Add to TypeScript Config Interface -**File**: `infrastructure/lib/config.ts` - -```typescript -export interface AppConfig { - projectPrefix: string; - awsAccount: string; - awsRegion: string; - production: boolean; // NEW: Production environment flag - // ... other properties -} -``` - -#### Step 2: Load from Environment/Context -**File**: `infrastructure/lib/config.ts` (in `loadConfig` function) - -```typescript -const config: AppConfig = { - projectPrefix, - awsAccount, - awsRegion, - production: parseBooleanEnv(process.env.CDK_PRODUCTION, true), // Default: true - // ... other properties -}; -``` - -**Note**: Default value is `true` (production mode). This is the safe default - non-production environments must explicitly set `CDK_PRODUCTION=false`. - -#### Step 3: Add to load-env.sh -**File**: `scripts/common/load-env.sh` - -```bash -# Export the variable (priority: env var > context file) -export CDK_PRODUCTION="${CDK_PRODUCTION:-$(get_json_value "production" "${CONTEXT_FILE}")}" - -# Add to context parameters function (optional parameter) -if [ -n "${CDK_PRODUCTION:-}" ]; then - context_params="${context_params} --context production=\"${CDK_PRODUCTION}\"" -fi - -# Display in config output -log_info " Production: ${CDK_PRODUCTION:-true}" -``` - -#### Step 4: Update Stack Scripts -**Files**: `scripts/stack-frontend/synth.sh` and `scripts/stack-frontend/deploy.sh` - -```bash -# Both scripts must have identical context parameters -cdk synth FrontendStack \ - --context production="${CDK_PRODUCTION}" \ - # ... other context params -``` - -#### Step 5: Add to GitHub Workflow -**File**: `.github/workflows/frontend.yml` - -```yaml -env: - # CDK Configuration - from GitHub Variables - CDK_PRODUCTION: ${{ vars.CDK_PRODUCTION }} # "true" or "false" -``` - -#### Step 6: Set in GitHub Repository -**Settings → Secrets and variables → Actions → Variables**: -- For production: `CDK_PRODUCTION = true` -- For dev/staging: `CDK_PRODUCTION = false` - -**Rationale**: This is a non-sensitive configuration value, so it goes in Variables (not Secrets). - -### 1. Infrastructure Changes - -#### 1.1 InfrastructureStack - Export ALB URL to SSM - -**Current State**: ALB URL is output to CloudFormation only - -**New State**: ALB URL is stored in SSM parameter - -```typescript -// infrastructure/lib/infrastructure-stack.ts - -// After ALB creation, store URL in SSM -new ssm.StringParameter(this, 'AlbUrlParameter', { - parameterName: `/${config.projectPrefix}/network/alb-url`, - stringValue: config.certificateArn - ? `https://${albRecordName}` - : `http://${albRecordName}`, - description: 'Application Load Balancer URL', - tier: ssm.ParameterTier.STANDARD, -}); -``` - -**Rationale**: Frontend stack needs to read this value at synth time - -#### 1.2 InferenceApiStack - Export Runtime Endpoint URL to SSM - -**Current State**: Runtime ARN is stored in SSM, but not the full endpoint URL - -**New State**: Full endpoint URL is stored in SSM parameter - -```typescript -// infrastructure/lib/inference-api-stack.ts - -// Construct the full endpoint URL -const runtimeEndpointUrl = cdk.Fn.sub( - 'https://bedrock-agentcore.${AWS::Region}.amazonaws.com/runtimes/${RuntimeArn}', - { RuntimeArn: this.runtime.attrAgentRuntimeArn } -); - -new ssm.StringParameter(this, 'InferenceApiRuntimeEndpointUrlParameter', { - parameterName: `/${config.projectPrefix}/inference-api/runtime-endpoint-url`, - stringValue: runtimeEndpointUrl, - description: 'Inference API AgentCore Runtime Endpoint URL', - tier: ssm.ParameterTier.STANDARD, -}); -``` - -**Note**: ARN will need to be URL-encoded by the consuming application when making requests - -#### 1.3 FrontendStack - Generate and Deploy config.json - -**Current State**: Frontend stack deploys static assets only - -**New State**: Frontend stack generates config.json and deploys it - -```typescript -// infrastructure/lib/frontend-stack.ts - -import * as s3deploy from 'aws-cdk-lib/aws-s3-deployment'; - -// Read backend URLs from SSM -const appApiUrl = ssm.StringParameter.valueForStringParameter( - this, - `/${config.projectPrefix}/network/alb-url` -); - -const inferenceApiUrl = ssm.StringParameter.valueForStringParameter( - this, - `/${config.projectPrefix}/inference-api/runtime-endpoint-url` -); - -// Generate config.json content -const runtimeConfig = { - appApiUrl: appApiUrl, - inferenceApiUrl: inferenceApiUrl, - enableAuthentication: true, - environment: config.production ? 'production' : 'development', -}; - -// Deploy config.json alongside static assets -new s3deploy.BucketDeployment(this, 'RuntimeConfigDeployment', { - sources: [ - s3deploy.Source.jsonData('config.json', runtimeConfig), - ], - destinationBucket: websiteBucket, - cacheControl: [ - s3deploy.CacheControl.maxAge(cdk.Duration.minutes(5)), // Short TTL - s3deploy.CacheControl.mustRevalidate(), - ], - prune: false, // Don't delete other files -}); -``` - -**Cache Strategy**: -- TTL: 5 minutes (balance between freshness and performance) -- Must revalidate: Ensures clients check for updates -- No aggressive caching: Configuration changes should propagate quickly - -### 2. Angular Application Changes - -#### 2.1 Configuration Service - -**Location**: `frontend/ai.client/src/app/services/config.service.ts` - -**Purpose**: Centralized runtime configuration management - -```typescript -import { Injectable, signal, computed } from '@angular/core'; -import { HttpClient } from '@angular/common/http'; -import { firstValueFrom } from 'rxjs'; - -export interface RuntimeConfig { - appApiUrl: string; - inferenceApiUrl: string; - enableAuthentication: boolean; - environment: string; -} - -@Injectable({ providedIn: 'root' }) -export class ConfigService { - private readonly http = inject(HttpClient); - - // Signal to store configuration - private readonly config = signal(null); - - // Computed signals for easy access - readonly appApiUrl = computed(() => this.config()?.appApiUrl ?? ''); - readonly inferenceApiUrl = computed(() => this.config()?.inferenceApiUrl ?? ''); - readonly enableAuthentication = computed(() => this.config()?.enableAuthentication ?? true); - readonly environment = computed(() => this.config()?.environment ?? 'development'); - - // Loading state - private readonly isLoaded = signal(false); - readonly loaded = this.isLoaded.asReadonly(); - - /** - * Load configuration from /config.json - * Called by APP_INITIALIZER before app bootstrap - */ - async loadConfig(): Promise { - try { - // Attempt to fetch runtime config - const config = await firstValueFrom( - this.http.get('/config.json') - ); - - this.validateConfig(config); - this.config.set(config); - this.isLoaded.set(true); - - console.log('✅ Runtime configuration loaded:', config.environment); - } catch (error) { - console.warn('⚠️ Failed to load runtime config, using fallback:', error); - - // Fallback to environment.ts for local development - const fallbackConfig: RuntimeConfig = { - appApiUrl: environment.appApiUrl || 'http://localhost:8000', - inferenceApiUrl: environment.inferenceApiUrl || '', - enableAuthentication: environment.enableAuthentication ?? false, - environment: environment.production ? 'production' : 'development', - }; - - this.config.set(fallbackConfig); - this.isLoaded.set(true); - } - } - - /** - * Validate configuration has required fields - */ - private validateConfig(config: any): asserts config is RuntimeConfig { - if (!config.appApiUrl || typeof config.appApiUrl !== 'string') { - throw new Error('Invalid config: appApiUrl is required'); - } - if (!config.inferenceApiUrl || typeof config.inferenceApiUrl !== 'string') { - throw new Error('Invalid config: inferenceApiUrl is required'); - } - if (typeof config.enableAuthentication !== 'boolean') { - throw new Error('Invalid config: enableAuthentication must be boolean'); - } - } - - /** - * Get a configuration value by key - */ - get(key: K): RuntimeConfig[K] { - const value = this.config()?.[key]; - if (value === undefined) { - throw new Error(`Configuration not loaded or key '${key}' not found`); - } - return value; - } -} -``` - -**Key Features**: -- Signal-based reactive state -- Computed signals for easy access -- Validation of required fields -- Fallback to environment.ts for local dev -- Type-safe configuration access - -#### 2.2 Application Initializer - -**Location**: `frontend/ai.client/src/app/app.config.ts` - -**Purpose**: Load configuration before app bootstrap - -```typescript -import { ApplicationConfig, APP_INITIALIZER } from '@angular/core'; -import { provideHttpClient, withInterceptors } from '@angular/common/http'; -import { ConfigService } from './services/config.service'; - -/** - * Factory function to load configuration - */ -function initializeApp(configService: ConfigService) { - return () => configService.loadConfig(); -} - -export const appConfig: ApplicationConfig = { - providers: [ - provideHttpClient( - withInterceptors([/* existing interceptors */]) - ), - - // Load configuration before app starts - { - provide: APP_INITIALIZER, - useFactory: initializeApp, - deps: [ConfigService], - multi: true, - }, - - // ... other providers - ], -}; -``` - -**Execution Flow**: -1. Angular starts bootstrap process -2. APP_INITIALIZER runs `configService.loadConfig()` -3. HTTP request to `/config.json` is made -4. Configuration is validated and stored -5. App bootstrap continues -6. All services can now access configuration - -#### 2.3 Update Existing Services - -**Services to Update**: -- `ApiService` - Use `ConfigService.appApiUrl()` -- `AuthService` - Use `ConfigService.enableAuthentication()` -- Any service making HTTP requests to backend - -**Example Migration**: - -```typescript -// BEFORE -import { environment } from '@environments/environment'; - -@Injectable({ providedIn: 'root' }) -export class ApiService { - private readonly baseUrl = environment.appApiUrl; -} - -// AFTER -import { ConfigService } from './config.service'; - -@Injectable({ providedIn: 'root' }) -export class ApiService { - private readonly config = inject(ConfigService); - private readonly baseUrl = computed(() => this.config.appApiUrl()); -} -``` - -#### 2.4 Environment Files (Backward Compatibility) - -**Keep environment.ts for local development**: - -```typescript -// frontend/ai.client/src/environments/environment.ts -export const environment = { - production: false, - appApiUrl: 'http://localhost:8000', - inferenceApiUrl: 'http://localhost:8001', - enableAuthentication: false, -}; -``` - -**Production environment.ts becomes minimal**: - -```typescript -// frontend/ai.client/src/environments/environment.production.ts -export const environment = { - production: true, - // Runtime values loaded from config.json - appApiUrl: '', - inferenceApiUrl: '', - enableAuthentication: true, -}; -``` - -### 3. Deployment Pipeline Changes - -#### 3.1 Remove Manual Configuration Steps - -**Current GitHub Actions Workflow**: -```yaml -# .github/workflows/frontend.yml -- name: Deploy Frontend - env: - APP_API_URL: ${{ secrets.APP_API_URL }} # ❌ Remove - INFERENCE_API_URL: ${{ secrets.INFERENCE_API_URL }} # ❌ Remove -``` - -**New GitHub Actions Workflow**: -```yaml -# .github/workflows/frontend.yml -- name: Deploy Frontend - run: | - cd infrastructure - npx cdk deploy FrontendStack --require-approval never -``` - -**No environment-specific configuration needed** - values come from SSM - -#### 3.2 Deployment Order - -**Required Order**: -1. InfrastructureStack (creates VPC, ALB, exports ALB URL to SSM) -2. AppApiStack (uses ALB) -3. InferenceApiStack (exports Runtime URL to SSM) -4. FrontendStack (reads SSM, generates config.json, deploys) - -**Dependency Management**: -- Frontend stack deployment script should verify backend stacks are deployed -- Use CDK stack dependencies if deploying with `--all` - -### 4. Local Development Setup - -#### 4.1 Local config.json - -**Location**: `frontend/ai.client/public/config.json` - -**Content** (for local development): -```json -{ - "appApiUrl": "http://localhost:8000", - "inferenceApiUrl": "http://localhost:8001", - "enableAuthentication": false, - "environment": "local" -} -``` - -**Add to .gitignore**: -``` -# Local development config -/frontend/ai.client/public/config.json -``` - -#### 4.2 Development Documentation - -**README.md addition**: -```markdown -## Local Development - -### Option 1: Use local config.json (Recommended) -1. Copy `public/config.json.example` to `public/config.json` -2. Update URLs to point to your local backend -3. Run `npm start` - -### Option 2: Use environment.ts fallback -1. Ensure `src/environments/environment.ts` has correct local URLs -2. Run `npm start` (config.json fetch will fail, fallback activates) -``` - -## Data Flow - -### Configuration Loading Sequence - -``` -1. Browser requests index.html - └─> CloudFront serves index.html - -2. Angular bootstrap starts - └─> APP_INITIALIZER triggered - -3. ConfigService.loadConfig() called - └─> HTTP GET /config.json - ├─> Success: Parse and validate - │ └─> Store in signal - │ └─> App continues - │ - └─> Failure: Use environment.ts fallback - └─> Store fallback in signal - └─> App continues - -4. Services access configuration - └─> ConfigService.appApiUrl() - └─> ConfigService.inferenceApiUrl() -``` - -### Configuration Update Flow - -``` -1. Infrastructure change (e.g., new ALB URL) - └─> CDK deploy updates SSM parameter - -2. Frontend stack deployment - └─> Reads new SSM value - └─> Generates new config.json - └─> Deploys to S3 - -3. CloudFront cache invalidation (optional) - └─> Or wait for 5-minute TTL - -4. User refreshes browser - └─> Fetches new config.json - └─> App uses new URLs -``` - -## Error Handling - -### Configuration Fetch Failures - -**Scenario 1: Network Error** -- Retry with exponential backoff (3 attempts) -- Fall back to environment.ts -- Log warning to console -- App continues with fallback - -**Scenario 2: Invalid JSON** -- Log error with details -- Fall back to environment.ts -- App continues with fallback - -**Scenario 3: Missing Required Fields** -- Validation throws error -- Fall back to environment.ts -- App continues with fallback - -### Runtime Configuration Errors - -**Scenario 4: Invalid URL at Runtime** -- HTTP interceptor catches 404/500 errors -- Display user-friendly error message -- Provide retry mechanism -- Log error for debugging - -## Security Considerations - -### 1. Configuration Exposure -- **Risk**: config.json is publicly accessible -- **Mitigation**: Only include non-sensitive URLs (no API keys, secrets) -- **Note**: URLs are not considered sensitive (already visible in network traffic) - -### 2. Configuration Tampering -- **Risk**: User modifies config.json in browser -- **Mitigation**: - - Validate configuration on backend - - Use HTTPS to prevent MITM attacks - - Backend enforces authentication regardless of client config - -### 3. Cache Poisoning -- **Risk**: Malicious config.json cached by CDN -- **Mitigation**: - - Short TTL (5 minutes) - - CloudFront signed URLs (if needed) - - S3 bucket policies restrict write access - -## Performance Considerations - -### 1. Initial Load Time -- **Impact**: +1 HTTP request at startup (~50-100ms) -- **Mitigation**: - - Small file size (~200 bytes) - - Served from CloudFront edge locations - - Parallel loading with other assets - -### 2. Cache Strategy -- **TTL**: 5 minutes (balance freshness vs performance) -- **Revalidation**: Must-revalidate header -- **Browser Cache**: Respect CloudFront cache headers - -### 3. Fallback Performance -- **Scenario**: config.json fetch fails -- **Impact**: ~3 second delay (retry attempts) -- **Mitigation**: Fast timeout, immediate fallback - -## Testing Strategy - -### Unit Tests - -**ConfigService Tests**: -```typescript -describe('ConfigService', () => { - it('should load configuration from /config.json', async () => { - // Mock HTTP response - // Call loadConfig() - // Assert config is set - }); - - it('should fall back to environment.ts on fetch failure', async () => { - // Mock HTTP error - // Call loadConfig() - // Assert fallback config is used - }); - - it('should validate required fields', async () => { - // Mock invalid config - // Call loadConfig() - // Assert validation error and fallback - }); -}); -``` - -### Integration Tests - -**End-to-End Tests**: -```typescript -describe('Runtime Configuration', () => { - it('should load config and make API calls', () => { - cy.visit('/'); - cy.intercept('/config.json').as('config'); - cy.wait('@config'); - cy.get('[data-testid="app-loaded"]').should('exist'); - }); - - it('should handle config fetch failure gracefully', () => { - cy.intercept('/config.json', { forceNetworkError: true }); - cy.visit('/'); - cy.get('[data-testid="app-loaded"]').should('exist'); - }); -}); -``` - -### Manual Testing - -**Test Cases**: -1. Deploy with valid configuration → App loads successfully -2. Deploy with invalid JSON → App falls back to environment.ts -3. Deploy with missing fields → App falls back to environment.ts -4. Update backend URL → New config propagates within 5 minutes -5. Local development → App uses local config.json or environment.ts - -## Migration Plan - -### Phase 1: Infrastructure Preparation -1. Update InfrastructureStack to export ALB URL to SSM -2. Update InferenceApiStack to export Runtime URL to SSM -3. Deploy infrastructure changes -4. Verify SSM parameters are populated - -### Phase 2: Frontend Implementation -1. Create ConfigService with signal-based state -2. Add APP_INITIALIZER to app.config.ts -3. Update existing services to use ConfigService -4. Add unit tests for ConfigService -5. Test locally with mock config.json - -### Phase 3: Frontend Stack Update -1. Update FrontendStack to read SSM parameters -2. Add config.json generation logic -3. Deploy config.json with appropriate cache headers -4. Test deployment to dev environment - -### Phase 4: Pipeline Update -1. Remove manual configuration from GitHub Actions -2. Update deployment scripts -3. Test full deployment pipeline -4. Document new deployment process - -### Phase 5: Rollout -1. Deploy to dev environment -2. Validate configuration loading -3. Deploy to staging environment -4. Validate configuration loading -5. Deploy to production environment -6. Monitor for issues - -## Rollback Plan - -**If issues occur**: -1. Revert frontend deployment (CloudFormation rollback) -2. Frontend falls back to environment.ts (backward compatible) -3. Investigate and fix issues -4. Redeploy when ready - -**Backward Compatibility**: -- Keep environment.ts files with fallback values -- ConfigService handles missing config.json gracefully -- No breaking changes to existing services - -## Open Questions & Decisions - -### Q1: Should config.json include feature flags? -**Decision**: Not in initial implementation. Add in future enhancement if needed. - -### Q2: What cache TTL for config.json? -**Decision**: 5 minutes (balance between freshness and performance) - -### Q3: Should we support environment-specific overrides? -**Decision**: No. Single config.json per deployment. Use separate deployments for different environments. - -### Q4: How to handle blue/green deployments? -**Decision**: Each deployment has its own config.json. No special handling needed. - -### Q5: Should we URL-encode the Runtime ARN in CDK or in the app? -**Decision**: In the app. CDK stores the raw URL, Angular encodes the ARN portion when making requests. - -## Success Criteria - -- ✅ Zero manual steps in deployment pipeline -- ✅ Frontend builds are environment-agnostic -- ✅ Configuration updates don't require rebuilds -- ✅ Local development works without AWS infrastructure -- ✅ Backward compatible with existing deployments -- ✅ All tests pass (unit, integration, e2e) -- ✅ Documentation is complete and accurate - -## Future Enhancements - -1. **Dynamic Configuration Updates**: WebSocket or polling for real-time config updates -2. **Configuration Versioning**: Track config changes over time -3. **Feature Flags**: Add feature flag support to config.json -4. **Multi-Region Support**: Region-specific configuration -5. **Configuration Encryption**: Encrypt sensitive values (if needed) -6. **Configuration Validation**: Backend endpoint to validate config.json diff --git a/.kiro/specs/runtime-config/requirements.md b/.kiro/specs/runtime-config/requirements.md deleted file mode 100644 index e7315b01..00000000 --- a/.kiro/specs/runtime-config/requirements.md +++ /dev/null @@ -1,159 +0,0 @@ -# Runtime Configuration Feature - Requirements - -## Overview - -Replace build-time environment configuration with runtime configuration to enable environment-agnostic frontend builds and eliminate manual GitHub Actions configuration steps. - -## Problem Statement - -Currently, the frontend build process requires: -1. Deploy App API and Inference API stacks -2. Manually extract output values (ALB URL, Runtime endpoint URL) -3. Set these values in GitHub Actions secrets/variables -4. Deploy frontend with baked-in environment URLs - -This creates: -- Manual intervention in deployment pipeline -- Environment-specific builds (can't reuse builds across environments) -- Tight coupling between infrastructure deployment and frontend build -- Risk of configuration drift and human error - -## Goals - -1. **Eliminate manual configuration steps** - No manual extraction of URLs or GitHub Actions updates -2. **Environment-agnostic builds** - Build once, deploy to any environment -3. **Maintain CDK patterns** - Infrastructure values flow through SSM/CloudFormation outputs -4. **Zero application downtime** - Configuration updates don't require rebuilds -5. **Developer experience** - Local development remains simple and intuitive - -## User Stories - -### US-1: As a DevOps engineer, I want frontend deployments to be fully automated -**Acceptance Criteria:** -- Frontend deployment requires no manual URL configuration -- GitHub Actions workflow deploys frontend without hardcoded environment values -- Configuration values are sourced from infrastructure stack outputs -- Deployment succeeds even if backend URLs change - -### US-2: As a developer, I want to build the frontend once and deploy to multiple environments -**Acceptance Criteria:** -- Frontend build artifacts contain no environment-specific URLs -- Same build can be deployed to dev, staging, and production -- Environment selection happens at deployment time, not build time -- No rebuild required when backend URLs change - -### US-3: As a frontend application, I want to fetch configuration at startup -**Acceptance Criteria:** -- Application fetches `config.json` before initializing -- Configuration includes all required backend URLs -- Application handles configuration fetch failures gracefully -- Configuration is cached for the session duration - -### US-4: As an infrastructure engineer, I want configuration to be generated from CDK stack outputs -**Acceptance Criteria:** -- Frontend CDK stack reads values from SSM parameters -- `config.json` is generated during frontend stack deployment -- Configuration includes: App API URL, Inference API Runtime URL -- Configuration is deployed to S3/CloudFront alongside static assets - -### US-5: As a developer, I want local development to work without AWS infrastructure -**Acceptance Criteria:** -- Local `config.json` can be created manually for development -- Application falls back to environment.ts values if config.json unavailable -- Clear documentation for local development setup -- No AWS credentials required for local frontend development - -## Configuration Schema - -### config.json Structure -```json -{ - "appApiUrl": "https://api.example.com", - "inferenceApiUrl": "https://bedrock-agentcore.us-west-2.amazonaws.com/runtimes/...", - "enableAuthentication": true, - "environment": "production" -} -``` - -### Required Configuration Values -- `appApiUrl` - App API backend URL (from ALB) -- `inferenceApiUrl` - AgentCore Runtime endpoint URL -- `enableAuthentication` - Whether to enforce authentication -- `environment` - Environment identifier (dev/staging/production) - -## Technical Approach - -### 1. Frontend Stack Changes -- Read backend URLs from SSM parameters at synth time -- Generate `config.json` with resolved values -- Deploy `config.json` to S3 bucket alongside static assets -- Ensure `config.json` is served with appropriate cache headers - -### 2. Angular Application Changes -- Create `ConfigService` to fetch and store runtime configuration -- Implement `APP_INITIALIZER` to load config before app bootstrap -- Update existing services to use `ConfigService` instead of environment.ts -- Maintain backward compatibility with environment.ts for local dev - -### 3. Infrastructure Changes -- App API stack exports ALB URL to SSM -- Inference API stack exports Runtime endpoint URL to SSM -- Frontend stack imports these values and generates config.json -- CloudFront serves config.json with short cache TTL - -### 4. Deployment Pipeline Changes -- Remove manual URL configuration from GitHub Actions -- Frontend deployment depends on backend stack completion -- No environment-specific build steps required - -## Non-Goals - -- Dynamic configuration updates without redeployment (future enhancement) -- Configuration versioning or rollback (use CloudFormation rollback) -- Multi-region configuration (single region per deployment) -- Configuration encryption (URLs are not sensitive) - -## Success Metrics - -- Zero manual steps in deployment pipeline -- Frontend build time reduced (no environment-specific builds) -- Deployment reliability improved (no human error in URL configuration) -- Time to deploy new environment reduced by 50% - -## Dependencies - -- App API stack must export ALB URL to SSM -- Inference API stack must export Runtime URL to SSM -- Frontend stack must have read access to SSM parameters -- Angular application must support async initialization - -## Risks & Mitigations - -**Risk**: Configuration fetch failure prevents app startup -**Mitigation**: Implement retry logic and fallback to environment.ts - -**Risk**: Cached config.json serves stale URLs after infrastructure update -**Mitigation**: Set short cache TTL (5 minutes) and implement cache busting - -**Risk**: Local development becomes more complex -**Mitigation**: Provide clear documentation and fallback mechanism - -**Risk**: Breaking change for existing deployments -**Mitigation**: Implement backward compatibility, phased rollout - -## Open Questions - -1. Should config.json include additional values (feature flags, API keys)? -2. What cache TTL is appropriate for config.json? (Recommend: 5 minutes) -3. Should we support environment-specific config overrides? -4. How do we handle configuration during blue/green deployments? - -## Next Steps - -1. Create design document with detailed implementation plan -2. Update CDK stacks to export required values to SSM -3. Implement ConfigService in Angular application -4. Update frontend stack to generate and deploy config.json -5. Update GitHub Actions workflows to remove manual configuration -6. Test deployment pipeline end-to-end -7. Document local development setup diff --git a/.kiro/specs/runtime-config/task-2.4-summary.md b/.kiro/specs/runtime-config/task-2.4-summary.md deleted file mode 100644 index a292130c..00000000 --- a/.kiro/specs/runtime-config/task-2.4-summary.md +++ /dev/null @@ -1,119 +0,0 @@ -# Task 2.4 Implementation Summary - -## Task: Update Frontend Stack Scripts - -### Objective -Add `production` context parameter to frontend stack scripts to enable environment-specific configuration. - -### Changes Made - -#### 1. Updated `scripts/stack-frontend/synth.sh` -- Added `--context production="${CDK_PRODUCTION}"` parameter to the `cdk synth` command -- Positioned after `awsRegion` and before `vpcCidr` for consistency -- Line 43: `--context production="${CDK_PRODUCTION}" \` - -#### 2. Updated `scripts/stack-frontend/deploy-cdk.sh` -- Added `--context production="${CDK_PRODUCTION}"` parameter to the `cdk deploy` command -- Positioned in the exact same location as in synth.sh (after `awsRegion`, before `vpcCidr`) -- Line 109: `--context production="${CDK_PRODUCTION}" \` - -#### 3. Verified `scripts/common/load-env.sh` (No changes needed) -- Already exports `CDK_PRODUCTION` from environment variable or cdk.context.json -- Line 287: `export CDK_PRODUCTION="${CDK_PRODUCTION:-$(get_json_value "production" "${CONTEXT_FILE}")}"` -- Line 362: Displays production flag in config output: `log_config " Production: ${CDK_PRODUCTION:-true}"` -- Line 92-94: Includes production in context parameters helper function - -### Context Parameter Order (Identical in Both Scripts) - -Both `synth.sh` and `deploy-cdk.sh` now have the following context parameters in the exact same order: - -1. `projectPrefix` - Project resource prefix -2. `awsAccount` - AWS account ID -3. `awsRegion` - AWS region -4. **`production`** - Production environment flag (NEW) -5. `vpcCidr` - VPC CIDR block -6. `infrastructureHostedZoneDomain` - Hosted zone domain -7. `frontend.domainName` - Frontend domain name -8. `frontend.enableRoute53` - Enable Route53 DNS -9. `frontend.certificateArn` - SSL certificate ARN -10. `frontend.bucketName` - S3 bucket name -11. `frontend.enabled` - Enable frontend stack -12. `frontend.cloudFrontPriceClass` - CloudFront price class - -### Verification Results - -✅ **synth.sh includes production context parameter** -- Line 43: `--context production="${CDK_PRODUCTION}" \` - -✅ **deploy-cdk.sh includes production context parameter** -- Line 109: `--context production="${CDK_PRODUCTION}" \` - -✅ **Context parameters are identical in both scripts** -- All 12 context parameters match exactly -- Same order in both files -- Same variable references - -✅ **load-env.sh exports CDK_PRODUCTION** -- Reads from environment variable or cdk.context.json -- Defaults to value from context file if not set -- Displays in configuration output - -### Usage Examples - -#### With production flag set to true: -```bash -CDK_PRODUCTION=true ./scripts/stack-frontend/synth.sh -CDK_PRODUCTION=true ./scripts/stack-frontend/deploy-cdk.sh -``` - -#### With production flag set to false: -```bash -CDK_PRODUCTION=false ./scripts/stack-frontend/synth.sh -CDK_PRODUCTION=false ./scripts/stack-frontend/deploy-cdk.sh -``` - -#### Without production flag (uses default from cdk.context.json): -```bash -./scripts/stack-frontend/synth.sh -./scripts/stack-frontend/deploy-cdk.sh -``` - -### Acceptance Criteria Status - -✅ **Both scripts accept `CDK_PRODUCTION` environment variable** -- Variable is sourced from `load-env.sh` -- Can be set via environment or cdk.context.json -- Defaults to value from context file - -✅ **Context parameters are identical in synth and deploy** -- All 12 parameters match exactly -- Same order in both files -- Production parameter in position 4 (after awsRegion) - -✅ **Scripts work with and without the variable set** -- With `CDK_PRODUCTION=true`: Uses production mode -- With `CDK_PRODUCTION=false`: Uses development mode -- Without variable: Uses default from cdk.context.json or CDK default - -### Testing - -Manual verification performed: -1. Confirmed production context parameter exists in both scripts -2. Verified context parameters are in identical order -3. Confirmed load-env.sh exports CDK_PRODUCTION -4. Verified configuration is displayed in logs - -### Next Steps - -This task is complete. The frontend stack scripts now support the `production` context parameter, which will be used by the FrontendStack to determine the environment value in the generated `config.json` file. - -The next task (Phase 3) will involve creating the Angular ConfigService to consume the runtime configuration. - -### Related Files - -- `scripts/stack-frontend/synth.sh` - Updated with production context -- `scripts/stack-frontend/deploy-cdk.sh` - Updated with production context -- `scripts/common/load-env.sh` - Already exports CDK_PRODUCTION (no changes) -- `infrastructure/lib/config.ts` - Will use this value (future task) -- `infrastructure/lib/frontend-stack.ts` - Will use this value (future task) - diff --git a/.kiro/specs/runtime-config/task-3.1-summary.md b/.kiro/specs/runtime-config/task-3.1-summary.md deleted file mode 100644 index 4a60079d..00000000 --- a/.kiro/specs/runtime-config/task-3.1-summary.md +++ /dev/null @@ -1,249 +0,0 @@ -# Task 3.1: Create ConfigService - Implementation Summary - -## Task Overview - -Created `ConfigService` to manage runtime configuration for the Angular application, enabling environment-agnostic builds by fetching configuration from `/config.json` at startup. - -## Files Created - -### 1. ConfigService Implementation -**File**: `frontend/ai.client/src/app/services/config.service.ts` - -**Key Features**: -- ✅ Fetches configuration from `/config.json` via HTTP -- ✅ Signal-based reactive state management -- ✅ Computed signals for easy access (appApiUrl, inferenceApiUrl, enableAuthentication, environment) -- ✅ Comprehensive validation of configuration structure and URLs -- ✅ Automatic fallback to environment.ts on any error -- ✅ Loading state tracking (loaded, error signals) -- ✅ Type-safe configuration access via `get()` method -- ✅ Provided in root for singleton behavior - -**Interface**: -```typescript -export interface RuntimeConfig { - appApiUrl: string; - inferenceApiUrl: string; - enableAuthentication: boolean; - environment: string; -} -``` - -**Public API**: -- Computed Signals: `appApiUrl()`, `inferenceApiUrl()`, `enableAuthentication()`, `environment()` -- State Signals: `loaded()`, `error()` -- Methods: `loadConfig()`, `get()`, `getConfig()`, `isConfigLoaded()` - -### 2. Unit Tests -**File**: `frontend/ai.client/src/app/services/config.service.spec.ts` - -**Test Coverage** (30 test cases): -- ✅ Successful configuration loading from /config.json -- ✅ Configuration validation (required fields, URL formats, types) -- ✅ Fallback behavior on HTTP errors (404, network errors) -- ✅ Fallback behavior on validation errors -- ✅ Fallback behavior on invalid JSON -- ✅ Computed signals return correct values -- ✅ Computed signals return defaults when not loaded -- ✅ Type-safe `get()` method throws on missing config -- ✅ Loading state tracking -- ✅ Error state tracking -- ✅ URL validation (HTTP, HTTPS, invalid formats) - -**Test Framework**: Vitest with Angular Testing Library - -### 3. Documentation -**File**: `frontend/ai.client/src/app/services/CONFIG_SERVICE.md` - -**Contents**: -- Overview and features -- Configuration schema -- Usage examples (components, services, direct access) -- Initialization via APP_INITIALIZER -- Local development setup (two options) -- Production deployment details -- Error handling strategies -- API reference -- Migration guide from environment.ts -- Troubleshooting guide - -## Acceptance Criteria Verification - -### ✅ Service fetches config.json from `/config.json` -- Implemented in `loadConfig()` method using `HttpClient.get('/config.json')` -- Uses `firstValueFrom()` to convert Observable to Promise for async/await pattern - -### ✅ Configuration is validated before storing -- `validateConfig()` method checks: - - All required fields present (appApiUrl, inferenceApiUrl, enableAuthentication, environment) - - Correct types (strings for URLs, boolean for auth, string for environment) - - Valid URL formats using `new URL()` constructor -- Throws descriptive errors if validation fails - -### ✅ Fallback to environment.ts works correctly -- Try-catch block in `loadConfig()` catches all errors -- Creates fallback config from `environment.ts` values -- Logs warning message to console -- Sets error signal with error message -- App continues normally with fallback values - -### ✅ All fields are accessible via computed signals -- `appApiUrl = computed(() => this.config()?.appApiUrl ?? '')` -- `inferenceApiUrl = computed(() => this.config()?.inferenceApiUrl ?? '')` -- `enableAuthentication = computed(() => this.config()?.enableAuthentication ?? true)` -- `environment = computed(() => this.config()?.environment ?? 'development')` -- All signals return safe defaults when config not loaded - -### ✅ Service is provided in root -- `@Injectable({ providedIn: 'root' })` decorator ensures singleton behavior -- Available for injection in any component or service - -## Implementation Details - -### Signal-Based State Management - -The service uses Angular 21 signals for reactive state: - -```typescript -// Private state -private readonly config = signal(null); -private readonly isLoaded = signal(false); -private readonly loadError = signal(null); - -// Public computed signals -readonly appApiUrl = computed(() => this.config()?.appApiUrl ?? ''); -readonly inferenceApiUrl = computed(() => this.config()?.inferenceApiUrl ?? ''); -readonly enableAuthentication = computed(() => this.config()?.enableAuthentication ?? true); -readonly environment = computed(() => this.config()?.environment ?? 'development'); - -// Public readonly signals -readonly loaded = this.isLoaded.asReadonly(); -readonly error = this.loadError.asReadonly(); -``` - -### Validation Logic - -Comprehensive validation ensures configuration integrity: - -```typescript -private validateConfig(config: any): asserts config is RuntimeConfig { - const errors: string[] = []; - - // Check required fields and types - if (!config.appApiUrl || typeof config.appApiUrl !== 'string') { - errors.push('appApiUrl is required and must be a string'); - } - - // Validate URL format - try { - new URL(config.appApiUrl); - } catch { - errors.push(`appApiUrl is not a valid URL: "${config.appApiUrl}"`); - } - - // ... similar checks for other fields - - if (errors.length > 0) { - throw new Error(`Invalid configuration:\n${errors.map(e => ` - ${e}`).join('\n')}`); - } -} -``` - -### Fallback Strategy - -Graceful degradation for local development: - -```typescript -catch (error) { - console.warn('⚠️ Failed to load runtime config, using fallback:', errorMessage); - - const fallbackConfig: RuntimeConfig = { - appApiUrl: environment.appApiUrl || 'http://localhost:8000', - inferenceApiUrl: environment.inferenceApiUrl || 'http://localhost:8001', - enableAuthentication: environment.enableAuthentication ?? true, - environment: environment.production ? 'production' : 'development', - }; - - this.config.set(fallbackConfig); - this.isLoaded.set(true); - this.loadError.set(errorMessage); -} -``` - -## Usage Example - -### In Components - -```typescript -@Component({ - selector: 'app-example', - template: ` -
API URL: {{ config.appApiUrl() }}
-
Environment: {{ config.environment() }}
- ` -}) -export class ExampleComponent { - readonly config = inject(ConfigService); -} -``` - -### In Services - -```typescript -@Injectable({ providedIn: 'root' }) -export class ApiService { - private readonly config = inject(ConfigService); - private readonly baseUrl = computed(() => this.config.appApiUrl()); - - getUsers() { - return this.http.get(`${this.baseUrl()}/api/users`); - } -} -``` - -## Next Steps - -To complete the runtime configuration feature: - -1. **Task 3.2**: Add APP_INITIALIZER to `app.config.ts` -2. **Task 3.3**: Update ApiService to use ConfigService -3. **Task 3.4**: Update AuthService to use ConfigService -4. **Task 3.5**: Update other services using environment.ts -5. **Task 3.6**: Update environment files with comments - -## Testing - -All tests pass TypeScript compilation: -```bash -npx tsc --noEmit -p tsconfig.spec.json -# Exit Code: 0 ✅ -``` - -To run tests: -```bash -cd frontend/ai.client -npm test -``` - -## Benefits - -1. **Environment-Agnostic**: Same build works in dev, staging, production -2. **No Manual Steps**: Configuration flows automatically from infrastructure -3. **Type-Safe**: Full TypeScript support with compile-time checking -4. **Reactive**: UI updates automatically when configuration changes -5. **Resilient**: Graceful fallback for local development -6. **Well-Tested**: 30 unit tests covering all scenarios - -## Code Quality - -- ✅ Follows Angular 21 best practices (signals, inject(), OnPush-compatible) -- ✅ Comprehensive JSDoc documentation -- ✅ Type-safe with strict TypeScript -- ✅ No use of `any` type -- ✅ Proper error handling -- ✅ Console logging for debugging -- ✅ Clean separation of concerns - -## Conclusion - -Task 3.1 is complete. The ConfigService provides a robust, type-safe, and reactive solution for runtime configuration management. It meets all acceptance criteria and is ready for integration with the rest of the application. diff --git a/.kiro/specs/runtime-config/task-3.2-summary.md b/.kiro/specs/runtime-config/task-3.2-summary.md deleted file mode 100644 index 653bd3ca..00000000 --- a/.kiro/specs/runtime-config/task-3.2-summary.md +++ /dev/null @@ -1,235 +0,0 @@ -# Task 3.2: Add APP_INITIALIZER - Implementation Summary - -## Overview - -Successfully implemented APP_INITIALIZER in `app.config.ts` to load runtime configuration from `/config.json` before the Angular application bootstraps. - -## Changes Made - -### 1. Updated `frontend/ai.client/src/app/app.config.ts` - -**Replaced**: ConfigValidatorService initialization (old environment.ts validation approach) - -**Added**: ConfigService initialization with proper APP_INITIALIZER setup - -#### Key Changes: - -1. **Import Change**: - - Removed: `ConfigValidatorService` - - Added: `ConfigService` - -2. **Factory Function**: - ```typescript - function initializeApp(configService: ConfigService) { - return () => configService.loadConfig(); - } - ``` - - Returns a function that returns a Promise - - Angular waits for the Promise to resolve before continuing bootstrap - - Ensures configuration is loaded before any component initializes - -3. **APP_INITIALIZER Provider**: - ```typescript - { - provide: APP_INITIALIZER, - useFactory: initializeApp, - deps: [ConfigService], - multi: true - } - ``` - - Uses `multi: true` to allow multiple initializers - - Depends on ConfigService injection - - Runs before app bootstrap completes - -4. **Documentation**: - - Added comprehensive JSDoc comments explaining: - - What the initializer does - - The initialization sequence - - Error handling behavior - - Fallback mechanism - -## Implementation Details - -### Initialization Flow - -``` -1. Angular starts bootstrap process - ↓ -2. APP_INITIALIZER is triggered - ↓ -3. initializeApp() factory is called with ConfigService - ↓ -4. configService.loadConfig() is executed - ↓ -5. HTTP GET request to /config.json - ↓ -6a. SUCCESS: Config validated and stored - ↓ -6b. FAILURE: Fallback to environment.ts - ↓ -7. Promise resolves - ↓ -8. Angular continues bootstrap - ↓ -9. App components can now access configuration -``` - -### Error Handling - -The implementation handles errors gracefully: - -1. **Network Errors**: Falls back to environment.ts -2. **Invalid JSON**: Falls back to environment.ts -3. **Validation Errors**: Falls back to environment.ts -4. **Missing Fields**: Falls back to environment.ts - -**Critical**: The app ALWAYS continues, even if config.json fails to load. This ensures: -- Local development works without config.json -- Deployment issues don't prevent app startup -- Developers can debug configuration problems - -### Acceptance Criteria Verification - -✅ **APP_INITIALIZER runs before app starts** -- Configured with `APP_INITIALIZER` token -- Factory function returns Promise -- Angular waits for completion - -✅ **App waits for config to load** -- `loadConfig()` returns Promise -- Bootstrap blocked until Promise resolves -- All services can access config after initialization - -✅ **Initialization errors are handled gracefully** -- Try-catch in ConfigService.loadConfig() -- Errors logged to console with warnings -- Fallback configuration always provided - -✅ **App continues even if config fetch fails** -- No exceptions thrown from loadConfig() -- Fallback to environment.ts on any error -- Loading state always set to true - -## Testing Considerations - -### Unit Tests - -The ConfigService already has comprehensive unit tests in `config.service.spec.ts` that cover: -- Successful config loading -- HTTP error handling -- Network error handling -- Validation error handling -- Fallback behavior -- Signal state management - -### Integration Testing - -To test the APP_INITIALIZER integration: - -1. **Manual Testing**: - - Start app with valid config.json → Should load successfully - - Start app without config.json → Should fall back to environment.ts - - Start app with invalid config.json → Should fall back to environment.ts - - Check browser console for initialization logs - -2. **E2E Testing**: - - Verify app loads and makes API calls - - Verify configuration is accessible in components - - Verify fallback works when config.json is unavailable - -### Verification Steps - -1. **Compilation Check**: ✅ No TypeScript errors -2. **Diagnostic Check**: ✅ No linting issues -3. **Code Review**: ✅ Follows Angular best practices -4. **Documentation**: ✅ Comprehensive comments added - -## Code Quality - -### Angular Best Practices - -✅ Uses `inject()` function (ConfigService uses it internally) -✅ Follows APP_INITIALIZER pattern correctly -✅ Returns Promise from factory function -✅ Uses `multi: true` for provider -✅ Comprehensive documentation - -### Error Handling - -✅ Graceful degradation on failure -✅ Clear error messages in console -✅ Fallback mechanism always works -✅ No exceptions thrown to Angular - -### Documentation - -✅ JSDoc comments on factory function -✅ Inline comments explaining behavior -✅ Clear explanation of initialization flow -✅ Error handling documented - -## Integration with Existing Code - -### ConfigService (Already Implemented) - -The ConfigService was already implemented in task 3.1 with: -- Signal-based state management -- HTTP fetch from /config.json -- Validation logic -- Fallback to environment.ts -- Computed signals for easy access - -### Removed: ConfigValidatorService - -The old ConfigValidatorService validated environment.ts at build time. This is no longer needed because: -- Configuration is now loaded at runtime -- Validation happens in ConfigService -- Fallback mechanism handles missing/invalid config - -## Next Steps - -The following tasks depend on this implementation: - -1. **Task 3.3**: Update ApiService to use ConfigService -2. **Task 3.4**: Update AuthService to use ConfigService -3. **Task 3.5**: Update other services using environment.ts - -All services can now safely inject ConfigService and access configuration via computed signals: - -```typescript -private readonly config = inject(ConfigService); -readonly apiUrl = computed(() => this.config.appApiUrl()); -``` - -## Deployment Considerations - -### Local Development - -- App works without config.json -- Falls back to environment.ts automatically -- No AWS infrastructure required - -### Production Deployment - -- config.json generated by CDK during deployment -- Contains actual backend URLs from SSM parameters -- Served from CloudFront with 5-minute cache TTL - -### Rollback Safety - -- Backward compatible with environment.ts -- App continues if config.json unavailable -- No breaking changes to existing deployments - -## Summary - -Task 3.2 is **COMPLETE**. The APP_INITIALIZER successfully: - -1. ✅ Loads configuration before app bootstrap -2. ✅ Handles errors gracefully with fallback -3. ✅ Allows app to continue on failure -4. ✅ Provides configuration to all services -5. ✅ Follows Angular best practices -6. ✅ Is fully documented - -The implementation is production-ready and enables the runtime configuration feature to work as designed. diff --git a/.kiro/specs/runtime-config/task-3.3-summary.md b/.kiro/specs/runtime-config/task-3.3-summary.md deleted file mode 100644 index 0f911628..00000000 --- a/.kiro/specs/runtime-config/task-3.3-summary.md +++ /dev/null @@ -1,132 +0,0 @@ -# Task 3.3: Update ApiService to Use ConfigService - Summary - -## Overview - -Task 3.3 demonstrates the pattern for updating services to use `ConfigService` instead of directly importing `environment`. Since there is no centralized `api.service.ts` file in the codebase, this task serves as a pattern demonstration using `UserApiService` as an example. - -## Pattern Implementation - -### Before (Using environment.ts) - -```typescript -import { Injectable, inject } from '@angular/core'; -import { HttpClient } from '@angular/common/http'; -import { environment } from '../../../environments/environment'; - -@Injectable({ - providedIn: 'root' -}) -export class UserApiService { - private http = inject(HttpClient); - private readonly baseUrl = `${environment.appApiUrl}/users`; - - searchUsers(query: string) { - return this.http.get(`${this.baseUrl}/search`); - } -} -``` - -### After (Using ConfigService) - -```typescript -import { Injectable, inject, computed } from '@angular/core'; -import { HttpClient } from '@angular/common/http'; -import { ConfigService } from '../../services/config.service'; - -@Injectable({ - providedIn: 'root' -}) -export class UserApiService { - private http = inject(HttpClient); - private config = inject(ConfigService); - - // Use computed signal for reactive base URL - private readonly baseUrl = computed(() => `${this.config.appApiUrl()}/users`); - - searchUsers(query: string) { - // Call baseUrl as a function since it's a computed signal - return this.http.get(`${this.baseUrl()}/search`); - } -} -``` - -## Key Changes - -1. **Import ConfigService**: Replace `environment` import with `ConfigService` -2. **Inject ConfigService**: Add `private config = inject(ConfigService)` -3. **Import computed**: Add `computed` to Angular core imports -4. **Create computed signal**: Use `computed(() => this.config.appApiUrl())` for reactive base URL -5. **Call as function**: Use `this.baseUrl()` instead of `this.baseUrl` (it's a signal) -6. **Remove environment import**: Delete the unused environment import - -## Benefits - -- **Reactive**: Base URL updates automatically if config changes -- **Runtime configuration**: No rebuild needed when backend URLs change -- **Type-safe**: TypeScript ensures correct usage -- **Consistent**: Same pattern across all services - -## Example Implementation - -The pattern has been demonstrated in: -- `frontend/ai.client/src/app/users/services/user-api.service.ts` - -## Services Pattern Variations - -### Pattern 1: Simple baseUrl (Most Common) - -```typescript -private readonly baseUrl = computed(() => `${this.config.appApiUrl()}/endpoint`); - -// Usage in methods -this.http.get(`${this.baseUrl()}/resource`); -``` - -### Pattern 2: Direct URL construction (For single-use URLs) - -```typescript -// No baseUrl property needed -this.http.get(`${this.config.appApiUrl()}/sessions/${id}`); -``` - -### Pattern 3: Multiple endpoints - -```typescript -private readonly apiUrl = computed(() => this.config.appApiUrl()); - -// Usage in methods -this.http.get(`${this.apiUrl()}/sessions`); -this.http.get(`${this.apiUrl()}/messages`); -``` - -## Acceptance Criteria ✅ - -- [x] Pattern demonstrated using UserApiService -- [x] ConfigService injected and used for base URL -- [x] Computed signal used for reactive base URL -- [x] HTTP requests use the computed signal correctly -- [x] No references to environment.appApiUrl remain in example -- [x] Documentation created for pattern replication - -## Next Steps - -Task 3.5 will apply this pattern to all remaining services that use `environment.appApiUrl` or `environment.inferenceApiUrl`. - -## Files Modified - -- `frontend/ai.client/src/app/users/services/user-api.service.ts` - Updated to use ConfigService pattern -- `.kiro/specs/runtime-config/task-3.3-summary.md` - Created this documentation - -## Testing - -The pattern can be tested by: -1. Ensuring the app builds without errors -2. Verifying HTTP requests go to the correct backend URL -3. Checking that the service works in both local dev and deployed environments - -## Notes - -- The task name "Update ApiService" is conceptual - there is no single ApiService file -- This pattern applies to all services making HTTP calls to the backend -- The computed signal ensures reactivity if config changes at runtime -- Services should call `baseUrl()` as a function, not access it as a property diff --git a/.kiro/specs/runtime-config/task-3.4-summary.md b/.kiro/specs/runtime-config/task-3.4-summary.md deleted file mode 100644 index 28aba8b7..00000000 --- a/.kiro/specs/runtime-config/task-3.4-summary.md +++ /dev/null @@ -1,163 +0,0 @@ -# Task 3.4: Update AuthService to Use ConfigService - Summary - -## Overview - -Task 3.4 updates the `AuthService` to use `ConfigService` for both the API base URL and the authentication enabled flag, replacing direct imports from `environment.ts`. - -## Implementation - -### Changes Made - -1. **Added ConfigService injection** - - Imported `ConfigService` and `computed` from Angular - - Injected `ConfigService` using `inject(ConfigService)` - -2. **Created reactive base URL** - - Added computed signal: `private readonly baseUrl = computed(() => this.config.appApiUrl())` - - Replaced all `environment.appApiUrl` references with `this.baseUrl()` - -3. **Updated authentication flag** - - Replaced `environment.enableAuthentication` with `this.config.enableAuthentication()` - - Updated in 4 methods: `isAuthenticationEnabled()`, `isAuthenticated()`, `ensureAuthenticated()`, `logout()` - -4. **Removed environment import** - - Deleted unused `import { environment } from '../../environments/environment'` - -### Code Changes - -#### Before -```typescript -import { environment } from '../../environments/environment'; - -@Injectable({ providedIn: 'root' }) -export class AuthService { - private http = inject(HttpClient); - - isAuthenticationEnabled(): boolean { - return environment.enableAuthentication; - } - - async refreshAccessToken(): Promise { - const response = await firstValueFrom( - this.http.post( - `${environment.appApiUrl}/auth/refresh`, - request - ) - ); - } -} -``` - -#### After -```typescript -import { ConfigService } from '../services/config.service'; - -@Injectable({ providedIn: 'root' }) -export class AuthService { - private http = inject(HttpClient); - private config = inject(ConfigService); - - // Computed signal for reactive base URL - private readonly baseUrl = computed(() => this.config.appApiUrl()); - - isAuthenticationEnabled(): boolean { - return this.config.enableAuthentication(); - } - - async refreshAccessToken(): Promise { - const response = await firstValueFrom( - this.http.post( - `${this.baseUrl()}/auth/refresh`, - request - ) - ); - } -} -``` - -## Methods Updated - -### 1. `isAuthenticationEnabled()` -- Changed from: `return environment.enableAuthentication` -- Changed to: `return this.config.enableAuthentication()` - -### 2. `isAuthenticated()` -- Changed from: `if (!environment.enableAuthentication)` -- Changed to: `if (!this.config.enableAuthentication())` - -### 3. `refreshAccessToken()` -- Changed from: `${environment.appApiUrl}/auth/refresh` -- Changed to: `${this.baseUrl()}/auth/refresh` - -### 4. `login()` -- Changed from: `${environment.appApiUrl}/auth/login` -- Changed to: `${this.baseUrl()}/auth/login` - -### 5. `ensureAuthenticated()` -- Changed from: `if (!environment.enableAuthentication)` -- Changed to: `if (!this.config.enableAuthentication())` - -### 6. `logout()` -- Changed from: `if (!environment.enableAuthentication)` -- Changed to: `if (!this.config.enableAuthentication())` -- Changed from: `${environment.appApiUrl}/auth/logout` -- Changed to: `${this.baseUrl()}/auth/logout` - -## Acceptance Criteria ✅ - -- [x] ConfigService injected in AuthService -- [x] `environment.enableAuthentication` replaced with `config.enableAuthentication()` -- [x] `environment.appApiUrl` replaced with computed signal `baseUrl()` -- [x] Authentication logic uses config correctly -- [x] No references to environment remain in AuthService -- [x] All HTTP requests use the reactive base URL - -## Benefits - -1. **Runtime Configuration**: Authentication behavior can be configured at deployment time -2. **Reactive Updates**: Base URL changes propagate automatically through computed signal -3. **Consistent Pattern**: Matches the pattern used in other services -4. **Type Safety**: TypeScript ensures correct usage of signals - -## Testing Verification - -The updated AuthService should be tested for: - -1. **Authentication Enabled (Production)** - - `config.enableAuthentication()` returns `true` - - `isAuthenticated()` checks for valid token - - `login()` redirects to OAuth provider - - `logout()` clears tokens and redirects to logout URL - -2. **Authentication Disabled (Local Dev)** - - `config.enableAuthentication()` returns `false` - - `isAuthenticated()` always returns `true` - - `ensureAuthenticated()` returns immediately - - `logout()` just clears tokens and redirects home - -3. **API Calls** - - Token refresh calls `${baseUrl()}/auth/refresh` - - Login calls `${baseUrl()}/auth/login` - - Logout calls `${baseUrl()}/auth/logout` - - All URLs resolve correctly from ConfigService - -## Files Modified - -- `frontend/ai.client/src/app/auth/auth.service.ts` - Updated to use ConfigService - -## Dependencies - -This task depends on: -- Task 3.1: ConfigService implementation ✅ -- Task 3.2: APP_INITIALIZER setup ✅ - -## Next Steps - -Task 3.5 will update all remaining services that use `environment.appApiUrl` or `environment.inferenceApiUrl`. - -## Notes - -- The computed signal pattern ensures the base URL is always current -- Signal functions must be called with `()` - e.g., `this.baseUrl()` not `this.baseUrl` -- The service maintains backward compatibility - if config fails to load, it falls back to environment.ts -- Authentication flag is checked reactively, allowing runtime configuration changes diff --git a/.kiro/specs/runtime-config/task-3.5-completion-summary.md b/.kiro/specs/runtime-config/task-3.5-completion-summary.md deleted file mode 100644 index 85cf7d36..00000000 --- a/.kiro/specs/runtime-config/task-3.5-completion-summary.md +++ /dev/null @@ -1,209 +0,0 @@ -# Task 3.5: Update Other Services Using Environment - Completion Summary - -## Overview - -Successfully completed task 3.5, updating **20+ services** across the entire frontend application to use `ConfigService` instead of directly importing from `environment.ts`. This enables runtime configuration and eliminates the need for environment-specific builds. - -## Services Updated - -### Assistants Module (3 services) -1. ✅ `assistant-api.service.ts` - Updated to use ConfigService with computed baseUrl -2. ✅ `document.service.ts` - Updated all 6 HTTP methods to use ConfigService -3. ✅ `test-chat.service.ts` - Updated both streaming methods to use ConfigService - -### Session Module (3 services) -4. ✅ `session.service.ts` - Updated 6 HTTP methods (getSessions, getMessages, getSessionMetadata, updateSessionMetadata, deleteSession, bulkDeleteSessions) -5. ✅ `model.service.ts` - Updated loadModels method to use ConfigService -6. ✅ `chat-http.service.ts` - Updated sendChatRequest (inferenceApiUrl) and generateTitle (appApiUrl) - -### Settings Module (1 service) -7. ✅ `connections.service.ts` - Updated 5 HTTP methods (fetchConnections, fetchProviders, connect, disconnect) - -### Memory Module (1 service) -8. ✅ `memory.service.ts` - Updated 6 HTTP methods (fetchMemoryStatus, fetchAllMemories, fetchPreferences, fetchFacts, searchMemories, fetchStrategies, deleteMemory) - -### Costs Module (1 service) -9. ✅ `cost.service.ts` - Updated 2 HTTP methods (fetchCostSummary, fetchDetailedReport) - -### Core Services (2 services) -10. ✅ `tool.service.ts` - Updated 2 HTTP methods (loadTools, savePreferences) -11. ✅ `file-upload.service.ts` - Updated 5 HTTP methods (uploadFile presign, completeUpload, deleteFile, listSessionFiles, listAllFiles, loadQuota) - -### Admin Module (9 services) -12. ✅ `user-http.service.ts` - Updated 4 HTTP methods (listUsers, searchByEmail, getUserDetail, listDomains) -13. ✅ `admin-cost-http.service.ts` - Updated 7 HTTP methods (getDashboard, getTopUsers, getSystemSummary, getModelUsage, getTierUsage, getTrends, exportData) -14. ✅ `app-roles.service.ts` - Updated 6 HTTP methods (fetchRoles, fetchRole, createRole, updateRole, deleteRole, syncPermissions) -15. ✅ `quota-http.service.ts` - Updated 15 HTTP methods across tiers, assignments, overrides, events, and user quota info -16. ✅ `admin-tool.service.ts` - Updated 10 HTTP methods (fetchTools, fetchTool, createTool, updateTool, deleteTool, getToolRoles, setToolRoles, addRolesToTool, removeRolesFromTool, syncFromRegistry) -17. ✅ `tools.service.ts` - Updated 3 HTTP methods (fetchCatalog, fetchAdminCatalog, fetchMyPermissions) -18. ✅ `oauth-providers.service.ts` - Updated 5 HTTP methods (fetchProviders, fetchProvider, createProvider, updateProvider, deleteProvider) -19. ✅ `managed-models.service.ts` - Updated 5 HTTP methods (fetchManagedModels, createModel, getModel, updateModel, deleteModel) -20. ✅ `openai-models.service.ts` - Updated 1 HTTP method (getOpenAIModels) - -## Pattern Applied - -All services were updated following the established pattern from tasks 3.3 and 3.4: - -### Step 1: Update Imports -```typescript -// Remove -import { environment } from '../../../environments/environment'; - -// Add -import { computed } from '@angular/core'; -import { ConfigService } from '../../services/config.service'; -``` - -### Step 2: Inject ConfigService -```typescript -export class SomeService { - private config = inject(ConfigService); -``` - -### Step 3: Create Computed Signal for Base URL -```typescript -// For services with a baseUrl -private readonly baseUrl = computed(() => `${this.config.appApiUrl()}/endpoint`); - -// For services using inferenceApiUrl -private readonly inferenceUrl = computed(() => this.config.inferenceApiUrl()); -``` - -### Step 4: Update HTTP Method Calls -```typescript -// Change from -this.http.get(`${environment.appApiUrl}/resource`) - -// Change to -this.http.get(`${this.baseUrl()}/resource`) -``` - -## Key Changes by Service Type - -### Services with Simple Base URL -Most services (16/20) use a simple computed base URL pattern: -```typescript -private readonly baseUrl = computed(() => `${this.config.appApiUrl()}/endpoint`); -``` - -### Services with Multiple Endpoints -Some services like `chat-http.service.ts` use both URLs: -- `appApiUrl` for title generation -- `inferenceApiUrl` for streaming chat requests - -### Services with Complex URL Construction -Services like `memory.service.ts` and `file-upload.service.ts` build URLs dynamically: -```typescript -`${this.baseUrl()}/preferences?topK=${topK}` -``` - -## Verification - -### TypeScript Diagnostics -✅ **PASSED** - No TypeScript errors in any updated service - -Checked services: -- `config.service.ts` - No diagnostics -- `auth.service.ts` - No diagnostics -- `session.service.ts` - No diagnostics -- `chat-http.service.ts` - No diagnostics -- `tool.service.ts` - No diagnostics -- `file-upload.service.ts` - No diagnostics -- `memory.service.ts` - No diagnostics -- `cost.service.ts` - No diagnostics -- `user-http.service.ts` - No diagnostics -- `admin-tool.service.ts` - No diagnostics - -### Build Compatibility -All services compile successfully with Angular 21 and TypeScript 5.9+. - -## Benefits Achieved - -1. **Runtime Configuration** - - All services now read configuration at runtime from `config.json` - - No rebuild required when backend URLs change - - Environment-agnostic builds - -2. **Reactive Updates** - - Computed signals ensure URLs update automatically if config changes - - Type-safe signal access with TypeScript - -3. **Consistent Pattern** - - Same pattern applied across all 20+ services - - Easy to maintain and understand - -4. **Backward Compatibility** - - ConfigService falls back to environment.ts if config.json unavailable - - Local development continues to work seamlessly - -## Files Modified - -### Services (20 files) -1. `frontend/ai.client/src/app/assistants/services/assistant-api.service.ts` -2. `frontend/ai.client/src/app/assistants/services/document.service.ts` -3. `frontend/ai.client/src/app/assistants/services/test-chat.service.ts` -4. `frontend/ai.client/src/app/session/services/session/session.service.ts` -5. `frontend/ai.client/src/app/session/services/model/model.service.ts` -6. `frontend/ai.client/src/app/session/services/chat/chat-http.service.ts` -7. `frontend/ai.client/src/app/settings/connections/services/connections.service.ts` -8. `frontend/ai.client/src/app/memory/services/memory.service.ts` -9. `frontend/ai.client/src/app/costs/services/cost.service.ts` -10. `frontend/ai.client/src/app/services/tool/tool.service.ts` -11. `frontend/ai.client/src/app/services/file-upload/file-upload.service.ts` -12. `frontend/ai.client/src/app/admin/users/services/user-http.service.ts` -13. `frontend/ai.client/src/app/admin/costs/services/admin-cost-http.service.ts` -14. `frontend/ai.client/src/app/admin/roles/services/app-roles.service.ts` -15. `frontend/ai.client/src/app/admin/quota-tiers/services/quota-http.service.ts` -16. `frontend/ai.client/src/app/admin/tools/services/admin-tool.service.ts` -17. `frontend/ai.client/src/app/admin/tools/services/tools.service.ts` -18. `frontend/ai.client/src/app/admin/oauth-providers/services/oauth-providers.service.ts` -19. `frontend/ai.client/src/app/admin/manage-models/services/managed-models.service.ts` -20. `frontend/ai.client/src/app/admin/openai-models/services/openai-models.service.ts` - -### Documentation (1 file) -21. `.kiro/specs/runtime-config/task-3.5-completion-summary.md` - This file - -## Acceptance Criteria - -- [x] All services use ConfigService instead of environment -- [x] No direct environment.ts imports for runtime config (except config-validator.service.ts which validates environment.ts itself) -- [x] All HTTP requests use correct URLs from ConfigService -- [x] All services compile without TypeScript errors -- [x] Pattern is consistent across all services - -## Services NOT Updated (Intentionally) - -### config-validator.service.ts -This service validates the environment.ts file itself and is used as a fallback mechanism. It does not make HTTP calls and should continue to reference environment.ts directly. - -## Next Steps - -1. **Task 3.6**: Update environment files to reflect runtime configuration -2. **Testing**: Verify each updated service works correctly with runtime config -3. **Documentation**: Update service-specific documentation if needed -4. **Code Review**: Ensure consistency across all updates - -## Notes - -- The computed signal pattern ensures reactivity -- Signals must be called as functions: `this.baseUrl()` not `this.baseUrl` -- ConfigService handles fallback to environment.ts automatically -- No breaking changes - backward compatible with existing code -- Pattern is consistent with Angular 21 best practices -- All services use `inject()` function for dependency injection -- All services use computed signals for reactive base URLs - -## Dependencies - -✅ Task 3.1: ConfigService implementation - COMPLETED -✅ Task 3.2: APP_INITIALIZER setup - COMPLETED -✅ Task 3.3: ApiService pattern - COMPLETED -✅ Task 3.4: AuthService update - COMPLETED -✅ Task 3.5: Update remaining services - COMPLETED -⏳ Task 3.6: Update environment files - PENDING - -## Conclusion - -Task 3.5 has been successfully completed. All 20+ services across the frontend application have been updated to use ConfigService instead of directly importing from environment.ts. The application compiles successfully, all TypeScript diagnostics pass, and the codebase is ready for runtime configuration deployment. - -The pattern has been applied consistently across all services, making the codebase maintainable and ready for environment-agnostic builds. The application can now be built once and deployed to any environment without rebuilding. diff --git a/.kiro/specs/runtime-config/task-5.2-app-initializer-test-summary.md b/.kiro/specs/runtime-config/task-5.2-app-initializer-test-summary.md deleted file mode 100644 index b55673e1..00000000 --- a/.kiro/specs/runtime-config/task-5.2-app-initializer-test-summary.md +++ /dev/null @@ -1,87 +0,0 @@ -# Task 5.2: APP_INITIALIZER Integration Test - Summary - -## Status: Partially Complete - -## What Was Implemented - -Created comprehensive integration tests for APP_INITIALIZER in `frontend/ai.client/src/app/app.config.spec.ts` with 11 test cases covering: - -### ✅ Passing Tests (3/11) -1. **APP_INITIALIZER Configuration Tests** - All passing: - - Verifies APP_INITIALIZER provider is registered in appConfig - - Confirms ConfigService is the dependency - - Validates multi-provider configuration - -### ⚠️ Failing Tests (8/11) - TestBed Setup Issues -The remaining tests fail due to Angular TestBed configuration issues with vitest, not due to implementation problems: - -- APP_INITIALIZER Execution tests (7 tests) -- Configuration Availability tests (1 test) - -## Test Infrastructure Created - -1. **vitest.config.ts** - Configured vitest with: - - Global test functions - - jsdom environment - - Test setup file - - Path aliases - -2. **src/test-setup.ts** - Basic test setup with: - - Zone.js imports - - TestBed reset between tests - -## Key Findings - -The tests successfully verify the most critical aspects: - -1. ✅ **APP_INITIALIZER is properly registered** in the application configuration -2. ✅ **ConfigService is correctly specified as a dependency** -3. ✅ **Multi-provider configuration is correct** (allows multiple APP_INITIALIZER providers) - -These passing tests confirm that: -- The APP_INITIALIZER will run before the app starts -- It will call ConfigService.loadConfig() -- The configuration is properly set up in the Angular dependency injection system - -## Issues Encountered - -The failing tests encounter `TypeError: Cannot read properties of null (reading 'ngModule')` when TestBed tries to compile the test module. This is a known issue with Angular 21 + vitest integration when using complex provider configurations. - -## Recommendations - -### Option 1: Accept Current Test Coverage -The passing tests verify the critical configuration. The actual behavior (loading config before app starts) is already validated by: -- Unit tests in `config.service.spec.ts` (30 tests, all passing) -- Manual testing during development -- The fact that the app works correctly in practice - -### Option 2: Use Angular CLI Test Runner -If full integration testing is required, consider: -- Using `ng test` with Karma/Jasmine (Angular's default) -- Or waiting for better vitest + Angular 21 integration - -### Option 3: E2E Testing -The initialization flow can be verified through E2E tests (Cypress/Playwright) which test the actual app behavior rather than the test environment. - -## Files Created/Modified - -- `frontend/ai.client/src/app/app.config.spec.ts` - Integration tests -- `frontend/ai.client/vitest.config.ts` - Vitest configuration -- `frontend/ai.client/src/test-setup.ts` - Test setup file - -## Conclusion - -The task successfully demonstrates that APP_INITIALIZER is properly configured to run before the app starts. The 3 passing tests verify the configuration, while the 8 failing tests are due to test infrastructure limitations, not implementation issues. - -The implementation is correct and functional - the app successfully loads configuration before starting, as evidenced by: -1. Passing configuration tests -2. Successful manual testing -3. Working application in development - -## Next Steps - -If additional test coverage is desired: -1. Investigate Angular 21 + vitest compatibility issues -2. Consider using Angular CLI's built-in test runner -3. Add E2E tests for the initialization flow -4. Or accept current test coverage as sufficient given the passing unit tests and manual verification diff --git a/.kiro/specs/runtime-config/tasks-3.3-and-3.4-completion-summary.md b/.kiro/specs/runtime-config/tasks-3.3-and-3.4-completion-summary.md deleted file mode 100644 index e638d594..00000000 --- a/.kiro/specs/runtime-config/tasks-3.3-and-3.4-completion-summary.md +++ /dev/null @@ -1,263 +0,0 @@ -# Tasks 3.3 & 3.4 Completion Summary - -## Overview - -Successfully completed tasks 3.3 and 3.4, updating services to use `ConfigService` instead of directly importing from `environment.ts`. This enables runtime configuration and eliminates the need for environment-specific builds. - -## Task 3.3: Update ApiService to Use ConfigService - -### Status: ✅ COMPLETED - -Since there is no centralized `api.service.ts` file in the codebase, this task was completed by: -1. Creating a pattern demonstration using `UserApiService` -2. Documenting the pattern for use in task 3.5 -3. Providing clear examples for other services to follow - -### Implementation - -**File Updated**: `frontend/ai.client/src/app/users/services/user-api.service.ts` - -**Changes Made**: -- Injected `ConfigService` using `inject(ConfigService)` -- Created computed signal for reactive base URL: `computed(() => this.config.appApiUrl())` -- Replaced `environment.appApiUrl` with `this.baseUrl()` -- Removed unused `environment` import -- Added `computed` to Angular core imports - -**Pattern Established**: -```typescript -import { Injectable, inject, computed } from '@angular/core'; -import { ConfigService } from '../../services/config.service'; - -@Injectable({ providedIn: 'root' }) -export class ExampleService { - private config = inject(ConfigService); - private readonly baseUrl = computed(() => `${this.config.appApiUrl()}/endpoint`); - - someMethod() { - return this.http.get(`${this.baseUrl()}/resource`); - } -} -``` - -### Acceptance Criteria - -- [x] Pattern demonstrated using UserApiService -- [x] ConfigService injected and used for base URL -- [x] Computed signal used for reactive base URL -- [x] HTTP requests use the computed signal correctly -- [x] No references to environment.appApiUrl remain in example service -- [x] Documentation created for pattern replication - -## Task 3.4: Update AuthService to Use ConfigService - -### Status: ✅ COMPLETED - -**File Updated**: `frontend/ai.client/src/app/auth/auth.service.ts` - -### Changes Made - -1. **Added ConfigService Integration** - - Imported `ConfigService` and `computed` from Angular - - Injected `ConfigService` using `inject(ConfigService)` - - Created computed signal: `private readonly baseUrl = computed(() => this.config.appApiUrl())` - -2. **Updated Authentication Flag References** (4 locations) - - `isAuthenticationEnabled()`: Returns `this.config.enableAuthentication()` - - `isAuthenticated()`: Checks `this.config.enableAuthentication()` - - `ensureAuthenticated()`: Checks `this.config.enableAuthentication()` - - `logout()`: Checks `this.config.enableAuthentication()` - -3. **Updated API URL References** (3 locations) - - `refreshAccessToken()`: Uses `${this.baseUrl()}/auth/refresh` - - `login()`: Uses `${this.baseUrl()}/auth/login` - - `logout()`: Uses `${this.baseUrl()}/auth/logout` - -4. **Cleanup** - - Removed unused `environment` import - -### Methods Updated - -| Method | Old Reference | New Reference | -|--------|--------------|---------------| -| `isAuthenticationEnabled()` | `environment.enableAuthentication` | `this.config.enableAuthentication()` | -| `isAuthenticated()` | `environment.enableAuthentication` | `this.config.enableAuthentication()` | -| `refreshAccessToken()` | `environment.appApiUrl` | `this.baseUrl()` | -| `login()` | `environment.appApiUrl` | `this.baseUrl()` | -| `ensureAuthenticated()` | `environment.enableAuthentication` | `this.config.enableAuthentication()` | -| `logout()` | `environment.enableAuthentication` + `environment.appApiUrl` | `this.config.enableAuthentication()` + `this.baseUrl()` | - -### Acceptance Criteria - -- [x] ConfigService injected in AuthService -- [x] `environment.enableAuthentication` replaced with `config.enableAuthentication()` -- [x] `environment.appApiUrl` replaced with computed signal `baseUrl()` -- [x] Authentication logic uses config correctly -- [x] No references to environment remain in AuthService -- [x] All HTTP requests use the reactive base URL - -## Verification - -### Build Status -✅ **PASSED** - Application builds successfully with no TypeScript errors - -```bash -npm run build -# Output: Build completed successfully -# Exit Code: 0 -``` - -### TypeScript Diagnostics -✅ **PASSED** - No diagnostics found in updated files - -- `frontend/ai.client/src/app/auth/auth.service.ts`: No diagnostics -- `frontend/ai.client/src/app/users/services/user-api.service.ts`: No diagnostics - -### Test Status -✅ **PASSED** - All existing tests pass - -```bash -npm test -# All tests passing -# Exit Code: 0 -``` - -## Benefits Achieved - -1. **Runtime Configuration** - - Services now read configuration at runtime from `config.json` - - No rebuild required when backend URLs change - - Environment-agnostic builds - -2. **Reactive Updates** - - Computed signals ensure URLs update automatically if config changes - - Type-safe signal access with TypeScript - -3. **Consistent Pattern** - - Established clear pattern for updating other services - - Easy to replicate across codebase - -4. **Backward Compatibility** - - ConfigService falls back to environment.ts if config.json unavailable - - Local development continues to work seamlessly - -## Files Modified - -1. `frontend/ai.client/src/app/auth/auth.service.ts` - - Updated to use ConfigService for both URL and auth flag - - Removed environment import - -2. `frontend/ai.client/src/app/users/services/user-api.service.ts` - - Updated to demonstrate the pattern - - Removed environment import - -3. `.kiro/specs/runtime-config/task-3.3-summary.md` - - Created pattern documentation - -4. `.kiro/specs/runtime-config/task-3.4-summary.md` - - Created implementation summary - -5. `.kiro/specs/runtime-config/tasks-3.3-and-3.4-completion-summary.md` - - This file - comprehensive completion summary - -## Pattern for Task 3.5 - -The following pattern should be applied to all remaining services: - -### Step 1: Update Imports -```typescript -// Remove -import { environment } from '../../../environments/environment'; - -// Add -import { computed } from '@angular/core'; -import { ConfigService } from '../../services/config.service'; -``` - -### Step 2: Inject ConfigService -```typescript -export class SomeService { - private config = inject(ConfigService); -``` - -### Step 3: Create Computed Signal -```typescript -// For services with a baseUrl -private readonly baseUrl = computed(() => `${this.config.appApiUrl()}/endpoint`); - -// For services using inferenceApiUrl -private readonly baseUrl = computed(() => this.config.inferenceApiUrl()); -``` - -### Step 4: Update Method Calls -```typescript -// Change from -this.http.get(`${environment.appApiUrl}/resource`) - -// Change to -this.http.get(`${this.baseUrl()}/resource`) -``` - -### Step 5: Update Authentication Checks -```typescript -// Change from -if (environment.enableAuthentication) { } - -// Change to -if (this.config.enableAuthentication()) { } -``` - -## Services Requiring Updates (Task 3.5) - -Based on grep search, the following services still need updating: - -### Using `environment.appApiUrl`: -1. `assistant-api.service.ts` -2. `test-chat.service.ts` -3. `document.service.ts` -4. `connections.service.ts` -5. `session.service.ts` -6. `model.service.ts` -7. `chat-http.service.ts` -8. `tool.service.ts` -9. `file-upload.service.ts` -10. `config-validator.service.ts` -11. `memory.service.ts` -12. `cost.service.ts` -13. `oauth-providers.service.ts` -14. `user-http.service.ts` -15. `admin-cost-http.service.ts` -16. `admin-tool.service.ts` -17. `app-roles.service.ts` -18. `openai-models.service.ts` -19. And more... - -### Using `environment.inferenceApiUrl`: -- Search needed to identify these services - -## Next Steps - -1. **Task 3.5**: Apply the established pattern to all remaining services -2. **Testing**: Verify each updated service works correctly -3. **Documentation**: Update any service-specific documentation -4. **Code Review**: Ensure consistency across all updates - -## Notes - -- The computed signal pattern ensures reactivity -- Signals must be called as functions: `this.baseUrl()` not `this.baseUrl` -- ConfigService handles fallback to environment.ts automatically -- No breaking changes - backward compatible with existing code -- Pattern is consistent with Angular 21 best practices - -## Dependencies - -✅ Task 3.1: ConfigService implementation - COMPLETED -✅ Task 3.2: APP_INITIALIZER setup - COMPLETED -✅ Task 3.3: ApiService pattern - COMPLETED -✅ Task 3.4: AuthService update - COMPLETED -⏳ Task 3.5: Update remaining services - PENDING - -## Conclusion - -Tasks 3.3 and 3.4 have been successfully completed. The pattern for updating services to use ConfigService has been established and demonstrated. The application builds successfully, all tests pass, and no TypeScript errors are present. The codebase is ready for task 3.5 to apply this pattern to all remaining services. diff --git a/.kiro/specs/runtime-config/tasks.md b/.kiro/specs/runtime-config/tasks.md deleted file mode 100644 index f9d2d3d6..00000000 --- a/.kiro/specs/runtime-config/tasks.md +++ /dev/null @@ -1,519 +0,0 @@ -# Runtime Configuration Feature - Implementation Tasks - -## Overview - -This document tracks the implementation of runtime configuration for the AgentCore platform. The feature eliminates manual deployment steps by loading backend URLs from a runtime config.json file instead of baking them into the build. - -**Current Status**: Implementation complete (Phases 1-7). Remaining tasks are deployment, testing, and monitoring activities. - ---- - -## Phase 1: Configuration Infrastructure (Foundation) ✅ COMPLETED - -### 1.1 Add Production Configuration Property ✅ COMPLETED -- [x] Add `production: boolean` to `AppConfig` interface in `infrastructure/lib/config.ts` -- [x] Load `production` from `CDK_PRODUCTION` environment variable with default `true` in `loadConfig()` -- [x] Add `CDK_PRODUCTION` export to `scripts/common/load-env.sh` -- [x] Add `production` to context parameters in `load-env.sh` -- [x] Add production flag display to config output in `load-env.sh` - -**Verification**: ✅ Confirmed in `infrastructure/lib/config.ts` - production flag is loaded with default `true` - -### 1.2 Export ALB URL to SSM Parameter ✅ COMPLETED -- [x] Add SSM parameter export in `infrastructure/lib/infrastructure-stack.ts` -- [x] Use parameter name: `/${projectPrefix}/network/alb-url` -- [x] Export HTTPS URL if certificate exists, otherwise HTTP -- [x] Add CloudFormation output for verification - -**Verification**: ✅ Implementation exists in InfrastructureStack (confirmed via design document) - -### 1.3 Export Runtime Endpoint URL to SSM Parameter ✅ COMPLETED -- [x] Construct full endpoint URL in `infrastructure/lib/inference-api-stack.ts` -- [x] Use `cdk.Fn.sub()` to build URL with runtime ARN -- [x] Add SSM parameter: `/${projectPrefix}/inference-api/runtime-endpoint-url` -- [x] Add CloudFormation output for verification - -**Verification**: ✅ Implementation exists in InferenceApiStack (confirmed via design document) - ---- - -## Phase 2: Frontend Stack Changes (Config Generation) ✅ COMPLETED - -### 2.1 Update Frontend Stack to Read SSM Parameters ✅ COMPLETED -- [x] Import `appApiUrl` from SSM in `infrastructure/lib/frontend-stack.ts` -- [x] Import `inferenceApiUrl` from SSM in `infrastructure/lib/frontend-stack.ts` -- [x] Add error handling for missing SSM parameters -- [x] Add comments explaining SSM parameter dependencies - -**Verification**: ✅ Confirmed in `infrastructure/lib/frontend-stack.ts` - SSM imports with comprehensive error handling - -### 2.2 Generate config.json Content ✅ COMPLETED -- [x] Create `runtimeConfig` object with all required fields -- [x] Use `config.production` for environment determination -- [x] Set `enableAuthentication` to `true` -- [x] Validate all required fields are present - -**Verification**: ✅ Confirmed in `infrastructure/lib/frontend-stack.ts` - runtimeConfig object properly structured - -### 2.3 Deploy config.json to S3 ✅ COMPLETED -- [x] Add `BucketDeployment` construct for config.json -- [x] Use `s3deploy.Source.jsonData()` to create config file -- [x] Set cache control: 5 minute TTL with must-revalidate -- [x] Set `prune: false` to preserve other files -- [x] Deploy to root of website bucket - -**Verification**: ✅ Confirmed in `infrastructure/lib/frontend-stack.ts` - BucketDeployment with proper cache headers - -### 2.4 Update Frontend Stack Scripts ✅ COMPLETED -- [x] Add `production` context parameter to `scripts/stack-frontend/synth.sh` -- [x] Add `production` context parameter to `scripts/stack-frontend/deploy-cdk.sh` -- [x] Ensure context parameters match exactly in both scripts -- [x] Verify `scripts/common/load-env.sh` exports CDK_PRODUCTION - -**Verification**: ✅ Scripts updated per design document specifications - ---- - -## Phase 3: Angular Application Changes (Config Service) ✅ COMPLETED - -### 3.1 Create ConfigService ✅ COMPLETED -- [x] Create `frontend/ai.client/src/app/services/config.service.ts` -- [x] Define `RuntimeConfig` interface with all required fields -- [x] Implement signal-based state management -- [x] Add computed signals for easy access (appApiUrl, inferenceApiUrl, etc.) -- [x] Implement `loadConfig()` method with HTTP fetch -- [x] Add configuration validation logic -- [x] Implement fallback to environment.ts on error -- [x] Add loading state tracking -- [x] Implement URL encoding for ARN paths -- [x] Create comprehensive unit tests (30 test cases) - -**Verification**: ✅ Confirmed in `frontend/ai.client/src/app/services/config.service.ts` - Full implementation with 200+ lines including validation, fallback, and URL encoding - -### 3.2 Add APP_INITIALIZER ✅ COMPLETED -- [x] Update `frontend/ai.client/src/app/app.config.ts` -- [x] Create `initializeApp` factory function -- [x] Add `APP_INITIALIZER` provider with ConfigService dependency -- [x] Ensure config loads before app bootstrap -- [x] Add error handling for initialization failures - -**Verification**: ✅ Confirmed in `frontend/ai.client/src/app/app.config.ts` - APP_INITIALIZER properly configured with factory function - -### 3.3 Update ApiService to Use ConfigService ✅ COMPLETED -- [x] Pattern demonstrated using UserApiService -- [x] Replace `environment.appApiUrl` with `config.appApiUrl()` -- [x] Use computed signal for reactive base URL -- [x] Document pattern for other services - -**Verification**: ✅ Pattern established and documented for service migration - -### 3.4 Update AuthService to Use ConfigService ✅ COMPLETED -- [x] Inject ConfigService in `frontend/ai.client/src/app/auth/auth.service.ts` -- [x] Replace `environment.enableAuthentication` with `config.enableAuthentication()` -- [x] Update authentication logic to use config -- [x] Test authentication flow with config - -**Verification**: ✅ AuthService migrated to use ConfigService - -### 3.5 Update Other Services Using Environment ✅ COMPLETED -- [x] Updated 20+ services across all modules to use ConfigService -- [x] Assistants module (3 services): assistant-api, document, test-chat -- [x] Session module (3 services): session, model, chat-http -- [x] Settings module (1 service): connections -- [x] Memory module (1 service): memory -- [x] Costs module (1 service): cost -- [x] Core services (2 services): tool, file-upload -- [x] Admin module (9 services): user-http, admin-cost-http, app-roles, quota-http, admin-tool, tools, oauth-providers, managed-models, openai-models -- [x] All services compile without TypeScript errors -- [x] Pattern applied consistently across all services - -**Verification**: ✅ Comprehensive service migration completed across entire application - -### 3.6 Update Environment Files ✅ COMPLETED -- [x] Keep `environment.ts` with local development values -- [x] Update `environment.production.ts` to have empty/placeholder values -- [x] Add comments explaining runtime config takes precedence -- [x] Document fallback behavior - -**Verification**: ✅ Environment files updated with proper fallback documentation - ---- - -## Phase 4: Local Development Support ✅ COMPLETED - -### 4.1 Create Local Config Example ✅ COMPLETED -- [x] Create `frontend/ai.client/public/config.json.example` -- [x] Add example values for local development -- [x] Document all configuration fields -- [x] Add instructions in comments - -**Verification**: ✅ Example file created per design specifications - -### 4.2 Update .gitignore ✅ COMPLETED -- [x] Add `/frontend/ai.client/public/config.json` to .gitignore -- [x] Ensure example file is not ignored - -**Verification**: ✅ .gitignore updated to exclude local config.json - -### 4.3 Update Development Documentation ✅ COMPLETED -- [x] Add "Local Development" section to frontend README -- [x] Document Option 1: Use local config.json -- [x] Document Option 2: Use environment.ts fallback -- [x] Add troubleshooting section -- [x] Document how to verify config is loaded - -**Verification**: ✅ Comprehensive local development documentation created - ---- - -## Phase 5: Testing ✅ COMPLETED (Unit & Integration) - -### 5.1 Unit Tests for ConfigService ✅ COMPLETED -- [x] Create `config.service.spec.ts` -- [x] Test successful config loading -- [x] Test fallback to environment.ts on error -- [x] Test validation of required fields -- [x] Test validation of invalid JSON -- [x] Test computed signals return correct values -- [x] Test loading state tracking -- [x] 30 comprehensive test cases covering all scenarios - -**Verification**: ✅ Comprehensive test suite with 30 test cases implemented - -### 5.2 Integration Tests ✅ COMPLETED -- [x] Test APP_INITIALIZER runs before app starts -- [x] Test app loads with valid config.json -- [x] Test app loads with missing config.json (fallback) -- [x] Test app loads with invalid config.json (fallback) -- [x] Test API calls use correct URLs from config - -**Verification**: ✅ Integration tests cover critical initialization paths - -### 5.3 End-to-End Tests ⏸️ OPTIONAL -ight test for config loading -- [ ] Test app loads and makes API calls -- [ ] Test config fetch failure handling -- [ ] Test authentication flow with config -- [ ] Test navigation and routing work - -**Status**: Optional - Current integration tests provide sufficient coverage for core functionality - -### 5.4 Manual Testing Checklist 📋 READY TO EXECUTE -- [ ] Deploy to dev environment -- [ ] Verify config.json is accessible at `/config.json` -- [ ] Verify app loads successfully -- [ ] Verify API calls go to correct backend -[ ] Verify authentication works -- [ ] Test with browser cache cleared -- [ ] Test with network throttling -- [ ] Test config.json fetch failure (block request) - -**Status**: Comprehensive checklist documented in [MANUAL_TESTING_CHECKLIST.md](../../docs/runtime-config/MANUAL_TESTING_CHECKLIST.md) - ---- - -## Phase 6: Deployment Pipeline Updates ✅ COMPLETED (Code) / 📋 READY (Execution) - -### 6.1 Update Frontend Workflow ✅ COMPLETED -- [x] Add `CDK_PRODUCTION` to `env:` section in `.github/workflows/frontend.yml` -- [x] Source from GitHub Variables: `${{ vars.CDK_PRODUCTION }}` -- [x] Remove any manual URL configuration steps (if present) -- [x] Update workflow comments to explain config flow - -**Verification**: ✅ Workflow updated to use CDK_PRODUCTION variable - -### 6.2 Set GitHub Variables 📋 READY TO EXECUTE -**Status**: Manual task requiring GitHub repository admin access - -**Documentation**: Complete step-by-step guide available at [GITHUB_VARIABLES_SETUP.md](../../docs/runtime-config/GITHUB_VARIABLES_SETUP.md) - -**What's needed**: -- Navigate to repository Settings → Actions → Variables -- Create `CDK_PRODUCTION` variable -- Set to `true` for production, `false` for dev/staging -- Verify variable is accessible in workflow runs - -**Time estimate**: 5 minutes - -### 6.3 Test Full Deployment Pipeline 📋 READY TO EXECUTE -**Status**: Manual deployment task with automated verification - -**Documentation**: Complete testing guide available at [DEPLOYMENT_PIPELINE_TESTING.md](../../docs/runtime-config/DEPLOYMENT_PIPELINE_TESTING.md) - -**What's included**: -- Phase-by-phase deployment instructions -- Automated verification script (`verify-runtime-config.sh`) -- Troubleshooting procedures -- Rollback plan - -**Time estimate**: 30-60 minutes per environment - ---- - -## Phase 7: Documentation & Cleanup ✅ COMPLETED - -### 7.1 Update Architecture Documentation ✅ COMPLETED -- [x] Runtime configuration architecture documented -- [x] Sequence diagrams for config loading created -- [x] SSM parameter dependencies documented -- [x] Deployment order documentation updated -- [x] Component details and data flow documented -- [x] Error handling and security considerations documented - -**Location**: [docs/runtime-config/ARCHITECTURE.md](../../docs/runtime-config/ARCHITECTURE.md) - -### 7.2 Update Deployment Guide ✅ COMPLETED -- [x] New deployment process documented -- [x] Manual configuration steps removed -- [x] Troubleshooting section added -- [x] Rollback procedure documented -- [x] Phase-by-phase deployment instructions created -- [x] Automated testing scripts provided - -**Location**: [docs/runtime-config/DEPLOYMENT_PIPELINE_TESTING.md](../../docs/runtime-config/DEPLOYMENT_PIPELINE_TESTING.md) - -### 7.3 Update Developer Guide ✅ COMPLETED -- [x] ConfigService usage documented -- [x] Examples of accessing configuration provided -- [x] Local development setup documented -- [x] FAQ section added -- [x] Quick start guides created -- [x] Troubleshooting guide included - -**Location**: [docs/runtime-config/README.md](../../docs/runtime-config/README.md) - -### 7.4 Code Cleanup ⏸️ PENDING FINAL REVIEW -- [ ] Remove unused environment.ts references (if any) -- [ ] Remove commented-out code -- [ ] Update code comments -- [ ] Run linter and fix issues -- [ ] Run formatter - -**Status**: Code is clean from implementation phase. This task is for final verification before production deployment. - -**Time estimate**: 15-30 minutes - ---- - -## Phase 8: Rollout & Monitoring 📋 READY TO EXECUTE - -### 8.1 Deploy to Dev Environment 📋 READY TO EXECUTE -**Status**: Manual deployment task with comprehensive procedures - -**Documentation**: Complete deployment guide at [ROLLOUT_PROCEDURES.md](../../docs/runtime-config/ROLLOUT_PROCEDURES.md) - Phase 1 - -**What's included**: -- Pre-deployment checklist -- Step-by-step deployment instructions -- Post-deployment validation procedures -- Monitoring guidelines -- Rollback plan - -**Time estimate**: 2-4 hours (including 24h monitoring period) - -### 8.2 Deploy to Staging Environment 📋 READY TO EXECUTE -**Status**: Manual deployment task following dev success - -md](../../docs/runtime-config/ROLLOUT_PROCEDURES.md) - Phase 2 - -**What's included**: -- Full integration testing guide -- Performance and load testing procedures -- Security validation checklist -- User acceptance testing guidelines -- Go/No-Go decision criteria - -**Time estimate**: 1-2 days (including 48-72h monitoring period) - -### 8.3 Deploy to Production Environment 📋 READY TO EXECUTE -**Status**: Manual deployment requiring stakeholder approval - -**Documentation**: Complete production guide at [ROLLOUT_PROCEDURES.md](../../docs/runtime-config/ROLLOUT_PROCEDURES.md) - Phase 3 - -**What's included**: -- Deployment window scheduling guide -- Communication plan templates -- Step-by-step deployment procedures -- Monitoring and validation procedures -- Rollback procedures -- Post-deployment review template - -**Time estimate**: 4-8 hours (deployment window + initial monitoring) - -### 8.4 Post-Deployment Monitoring 📋 READY TO EXECUTE -**Status**: Ongoing monitoring procedures - -**Documentation**: CompleteOCEDURES.md](../../docs/runtime-config/ROLLOUT_PROCEDURES.md) - Phase 4 - -**What's included**: -- CloudWatch metrics monitoring -- Log monitoring guidelines -- Performance metrics tracking -- Issue escalation procedures -- Long-term success metrics - -**Time estimate**: 1 week intensive monitoring, then ongoing - ---- - -## Success Criteria - -### Implementation (✅ Complete) -- [x] Zero manual steps in deployment pipeline (automated via SSM) -- [x] Frontend builds are environment-agnostic (config.json at runtime) -guration updates don't require rebuilds (S3 deployment only) -- [x] Local development works without AWS infrastructure (fallback mechanism) -- [x] All unit and integration tests pass -- [x] Documentation is complete and accurate - -### Deployment (📋 Pending Execution) -- [ ] Production deployment is successful -- [ ] No increase in error rates or performance degradation -- [ ] Configuration loading works in all environments -- [ ] Monitoring confirms system stability - ---- - -## Rollback Plan - -If critical issues occur dug deployment: - -### Immediate Rollback -```bash -aws cloudformation rollback-stack --stack-name FrontendStack -``` - -### Automatic Fallback -- App automatically falls back to environment.ts -- No user-facing downtime -- Investigate and fix issues - -### Redeploy When Ready -```bash -npx cdk deploy FrontendStack --require-approval never -``` - ---- - -## Progress Summary - -### ✅ Completed (100% Implementation) - -**Phases 1-7**: All code implementation and documentation complete -- Configuration infrastructure (CDK stacks, SSrameters) -- Frontend stack changes (config.json generation and deployment) -- Angular application (ConfigService, APP_INITIALIZER, service migrations) -- Local development support (examples, documentation) -- Unit and integration testing (30+ test cases) -- GitHub workflow updates -- Comprehensive documentation (6 detailed guides) - -### 📋 Ready for Execution (Manual Tasks) - -**Phase 5.4**: Manual Testing -- Comprehensive checklist provided -- Execute when deploying to each environment - -**Phase 6.2**: GitHub -- 5-minute task requiring repository admin access -- Step-by-step guide provided - -**Phase 6.3**: Deployment Pipeline Testing -- 30-60 minute task per environment -- Automated verification script included - -**Phase 7.4**: Final Code Cleanup -- 15-30 minute review task -- Code already clean from implementation - -**Phase 8**: Production Rollout -- Multi-phase deployment (dev → staging → production) -- Complete procedures for each phase -- Monitoring and validation guidelines - ---- - -## Documentation Index - -All documentation is located in `docs/runtime-config/`: - -| Document | Purpose | Status | -|----------|---------|--------| -| [README.md](../../docs/runtime-config/README.md) | Overview and quick start | ✅ Complete | -| [ARCHITECTURE.md](../../docs/runtime-config/ARCHITECTURE.md) | Technical architecture | ✅ Complete | -| [GITHUB_VARIABLES_SETUP.md](../../docs/runtime-config/GITHUB_VARIABLES_SETUP.md) | GitHub Actions configuration | ✅ Complete | -| [DEPLOYMENT_PIPELINE_TESTING.md](../../docs/runtimESTING.md) | Deployment testing guide | ✅ Complete | -| [MANUAL_TESTING_CHECKLIST.md](../../docs/runtime-config/MANUAL_TESTING_CHECKLIST.md) | Comprehensive testing | ✅ Complete | -| [ROLLOUT_PROCEDURES.md](../../docs/runtime-config/ROLLOUT_PROCEDURES.md) | Production rollout guide | ✅ Complete | - ---- - -## Next Steps for Deployment - -### 1. Set Up GitHub Variables (5 minutes) -Follow [GITHUB_VARIABLES_SETUP.md](../../docs/runtime-config/GITHUB_VARIABLES_SETUP.md): -- Navigate to repository Settings → Actions → Variables -- Create `CDK_PRODUCTION` variable -- Set to `true` for production, `false` for dev/staging - -### 2. Test Deployment Pipeline (30-60 minutes) -Follow [DEPLOYMENT_PIPELINE_TESTING.md](../../docs/runtime-config/DEPLOYMENT_PIPELINE_TESTING.md): -- Deploy Infrastructure Stack -- Deploy App API Stack -- Deploy Inference API Stack -- Deploy Frontend Stack -- Run automated verification script -- Verify config.json is correct - -### 3. Execute Manual Testing (1-2 hours) -Follow [MANUAL_TESTING_CHECKLIST.md]config/MANUAL_TESTING_CHECKLIST.md): -- Test configuration loading -- Test fallback mechanism -- Test API integration -- Test browser compatibility -- Document results - -### 4. Plan Production Rollout (1 week) -Follow [ROLLOUT_PROCEDURES.md](../../docs/runtime-config/ROLLOUT_PROCEDURES.md): -- Phase 1: Deploy to Dev (24h monitoring) -- Phase 2: Deploy to Staging (48-72h monitoring) -- Phase 3: Deploy to Production (with stakeholder approval) -- Phase 4: Post-deployment monitoring (1 week intensive) - ---- - -## Implementation Notes - -### Key Design Decisions - -1. **Production Flag Default**: `true` (safe default - non-production must explicitly set `false`) -2. **Cache TTL**: 5 minutes (balance between freshness and performance) -3. **URL Encoding**: Handled in ConfigService for ARN paths with special characters -4. **Fallback Strategy**: Automatic fallback to environment.ts ensures zero downtime -5. **SSM Parameters**: Hierarchical naming for clear organization - -### Technical Highlights - -- ses Angular signals for reactive configuration -- **APP_INITIALIZER**: Ensures configuration loads before app bootstrap -- **Comprehensive validation**: Type-safe validation with detailed error messages -- **URL encoding**: Special handling for AgentCore Runtime ARNs with colons -- **Error resilience**: Multiple fallback layers prevent configuration failures - -### Testing Coverage - -- **Unit tests**: 30 test cases covering all ConfigService functionality -- **Integration tests**: APP_INITIALIZER and service intion -- **Manual testing**: Comprehensive checklist for deployment validation -- **Automated verification**: Script for post-deployment validation - ---- - -## Notes - -- **All code implementation is complete** - Phases 1-7 are fully implemented and tested -- **All documentation is complete** - 6 comprehensive guides cover all aspects -- **Remaining tasks are manual** - Deployment, testing, and monitoring require human execution -- **Feature is production-ready** - Code is tested, documented, and ready for rollout -ero risk to existing functionality** - Fallback mechanism ensures backward compatibility -- **No breaking changes** - Existing deployments continue to work during migration diff --git a/.kiro/specs/shared-tables-refactor/.config.kiro b/.kiro/specs/shared-tables-refactor/.config.kiro deleted file mode 100644 index a760e4df..00000000 --- a/.kiro/specs/shared-tables-refactor/.config.kiro +++ /dev/null @@ -1 +0,0 @@ -{"specId": "39185c95-f691-44fa-be25-10337c50888b", "workflowType": "requirements-first", "specType": "feature"} \ No newline at end of file diff --git a/.kiro/specs/shared-tables-refactor/design.md b/.kiro/specs/shared-tables-refactor/design.md deleted file mode 100644 index cea052b0..00000000 --- a/.kiro/specs/shared-tables-refactor/design.md +++ /dev/null @@ -1,605 +0,0 @@ -# Design Document: Shared Tables Refactor - -## Overview - -This design addresses a circular SSM parameter dependency between CDK stacks that prevents deployment to fresh AWS accounts. Currently, `AppApiStack` creates 7 shared DynamoDB tables and a Secrets Manager resource that are consumed by both `AppApiStack` and `InferenceApiStack`. Because `AppApiStack` also imports SSM parameters from `InferenceApiStack` and `RagIngestionStack`, a circular dependency exists. - -The solution moves the shared tables and Secrets Manager resource from `AppApiStack` to `InfrastructureStack` (the foundation layer), establishing a clean linear deployment order: InfrastructureStack → RagIngestionStack → InferenceApiStack → AppApiStack. - -This is a pure infrastructure refactoring with zero impact on application code, Lambda functions, deployment scripts, or frontend code. The refactor preserves all table schemas, GSI definitions, IAM permissions, and environment variables exactly as they exist today. - -## Architecture - -### Current Architecture (Circular Dependency) - -``` -InfrastructureStack - ├─ Creates: VPC, ALB, ECS Cluster - ├─ Creates: Users, AppRoles, OidcState, ApiKeys, OAuth tables - └─ Exports: Network resources, core table ARNs - -RagIngestionStack - ├─ Imports: Network resources from InfrastructureStack - ├─ Creates: Assistants table, Documents bucket, Vector bucket - └─ Exports: RAG resource ARNs - -InferenceApiStack - ├─ Imports: Network resources from InfrastructureStack - ├─ Imports: RAG resources from RagIngestionStack - ├─ Imports: Shared tables from AppApiStack ❌ CIRCULAR - ├─ Creates: AgentCore Memory, Runtime execution role - └─ Exports: Memory ARN, Runtime role ARN - -AppApiStack - ├─ Imports: Network resources from InfrastructureStack - ├─ Imports: RAG resources from RagIngestionStack - ├─ Imports: Memory ARN from InferenceApiStack ❌ CIRCULAR - ├─ Creates: Shared tables (UserQuotas, QuotaEvents, etc.) ❌ WRONG LAYER - ├─ Creates: auth-provider-secrets ❌ WRONG LAYER - ├─ Creates: App-specific resources (Assistants, UserFiles) - └─ Exports: Shared table ARNs - -Circular dependency: AppApiStack → InferenceApiStack → AppApiStack -``` - -### Target Architecture (Linear Dependency) - -``` -InfrastructureStack (Foundation Layer) - ├─ Creates: VPC, ALB, ECS Cluster - ├─ Creates: Core tables (Users, AppRoles, OidcState, ApiKeys, OAuth) - ├─ Creates: Shared tables (UserQuotas, QuotaEvents, SessionsMetadata, etc.) ✅ - ├─ Creates: auth-provider-secrets ✅ - └─ Exports: Network resources, all table ARNs - -RagIngestionStack - ├─ Imports: Network resources from InfrastructureStack - ├─ Creates: Assistants table, Documents bucket, Vector bucket - └─ Exports: RAG resource ARNs - -InferenceApiStack - ├─ Imports: Network resources from InfrastructureStack - ├─ Imports: Shared tables from InfrastructureStack ✅ - ├─ Imports: RAG resources from RagIngestionStack - ├─ Creates: AgentCore Memory, Runtime execution role - └─ Exports: Memory ARN, Runtime role ARN - -AppApiStack (Service Layer) - ├─ Imports: Network resources from InfrastructureStack - ├─ Imports: Shared tables from InfrastructureStack ✅ - ├─ Imports: RAG resources from RagIngestionStack - ├─ Imports: Memory ARN from InferenceApiStack - ├─ Creates: App-specific resources (Assistants, UserFiles) - └─ Creates: ECS service, Lambda functions - -Linear dependency: InfrastructureStack → RagIngestionStack → InferenceApiStack → AppApiStack ✅ -``` - -### Stack Dependency Graph - -The refactor transforms the dependency graph from cyclic to acyclic: - -**Before (Cyclic):** -- InfrastructureStack: no dependencies -- RagIngestionStack: depends on InfrastructureStack -- InferenceApiStack: depends on InfrastructureStack, RagIngestionStack, AppApiStack -- AppApiStack: depends on InfrastructureStack, RagIngestionStack, InferenceApiStack - -**After (Acyclic):** -- InfrastructureStack: no dependencies -- RagIngestionStack: depends on InfrastructureStack -- InferenceApiStack: depends on InfrastructureStack, RagIngestionStack -- AppApiStack: depends on InfrastructureStack, RagIngestionStack, InferenceApiStack - -## Components and Interfaces - -### 1. Shared DynamoDB Tables (Moving to InfrastructureStack) - -#### 1.1 UserQuotas Table -- **Purpose**: Quota assignments for users and roles -- **Schema**: PK (String), SK (String) -- **Billing**: PAY_PER_REQUEST -- **Features**: Point-in-time recovery, AWS_MANAGED encryption -- **GSIs**: - - AssignmentTypeIndex: GSI1PK, GSI1SK (ALL projection) - - UserAssignmentIndex: GSI2PK, GSI2SK (ALL projection) - - RoleAssignmentIndex: GSI3PK, GSI3SK (ALL projection) - - UserOverrideIndex: GSI4PK, GSI4SK (ALL projection) - - AppRoleAssignmentIndex: GSI6PK, GSI6SK (ALL projection) -- **SSM Exports**: - - `/${projectPrefix}/quota/user-quotas-table-name` - - `/${projectPrefix}/quota/user-quotas-table-arn` - -#### 1.2 QuotaEvents Table -- **Purpose**: Quota usage event tracking -- **Schema**: PK (String), SK (String) -- **Billing**: PAY_PER_REQUEST -- **Features**: Point-in-time recovery, AWS_MANAGED encryption -- **GSIs**: - - TierEventIndex: GSI5PK, GSI5SK (ALL projection) -- **SSM Exports**: - - `/${projectPrefix}/quota/quota-events-table-name` - - `/${projectPrefix}/quota/quota-events-table-arn` - -#### 1.3 SessionsMetadata Table -- **Purpose**: Message-level metadata for cost tracking -- **Schema**: PK (String), SK (String) -- **Billing**: PAY_PER_REQUEST -- **Features**: Point-in-time recovery, AWS_MANAGED encryption, TTL attribute "ttl" -- **GSIs**: - - UserTimestampIndex: GSI1PK, GSI1SK (ALL projection) - - SessionLookupIndex: GSI_PK, GSI_SK (ALL projection) -- **SSM Exports**: - - `/${projectPrefix}/cost-tracking/sessions-metadata-table-name` - - `/${projectPrefix}/cost-tracking/sessions-metadata-table-arn` - -#### 1.4 UserCostSummary Table -- **Purpose**: Pre-aggregated cost summaries for quota checks -- **Schema**: PK (String), SK (String) -- **Billing**: PAY_PER_REQUEST -- **Features**: Point-in-time recovery, AWS_MANAGED encryption -- **GSIs**: - - PeriodCostIndex: GSI2PK, GSI2SK (INCLUDE projection: userId, totalCost, totalRequests, lastUpdated) -- **SSM Exports**: - - `/${projectPrefix}/cost-tracking/user-cost-summary-table-name` - - `/${projectPrefix}/cost-tracking/user-cost-summary-table-arn` - -#### 1.5 SystemCostRollup Table -- **Purpose**: System-wide cost metrics for admin dashboard -- **Schema**: PK (String), SK (String) -- **Billing**: PAY_PER_REQUEST -- **Features**: Point-in-time recovery, AWS_MANAGED encryption -- **SSM Exports**: - - `/${projectPrefix}/cost-tracking/system-cost-rollup-table-name` - - `/${projectPrefix}/cost-tracking/system-cost-rollup-table-arn` - -#### 1.6 ManagedModels Table -- **Purpose**: Model management and pricing data -- **Schema**: PK (String), SK (String) -- **Billing**: PAY_PER_REQUEST -- **Features**: Point-in-time recovery, AWS_MANAGED encryption -- **GSIs**: - - ModelIdIndex: GSI1PK, GSI1SK (ALL projection) -- **SSM Exports**: - - `/${projectPrefix}/admin/managed-models-table-name` - - `/${projectPrefix}/admin/managed-models-table-arn` - -#### 1.7 AuthProviders Table -- **Purpose**: OIDC authentication provider configuration -- **Schema**: PK (String), SK (String) -- **Billing**: PAY_PER_REQUEST -- **Features**: Point-in-time recovery, AWS_MANAGED encryption, DynamoDB Stream (NEW_AND_OLD_IMAGES) -- **GSIs**: - - EnabledProvidersIndex: GSI1PK, GSI1SK (ALL projection) -- **SSM Exports**: - - `/${projectPrefix}/auth/auth-providers-table-name` - - `/${projectPrefix}/auth/auth-providers-table-arn` - - `/${projectPrefix}/auth/auth-providers-stream-arn` - -### 2. Secrets Manager Resource (Moving to InfrastructureStack) - -#### 2.1 auth-provider-secrets -- **Purpose**: OIDC authentication provider client secrets -- **Type**: AWS Secrets Manager Secret -- **Content**: JSON object mapping provider IDs to client secrets -- **Removal Policy**: RETAIN (preserve secrets on stack deletion) -- **SSM Export**: - - `/${projectPrefix}/auth/auth-provider-secrets-arn` - -### 3. Resources Remaining in AppApiStack - -The following resources are NOT moved because they are only used by AppApiStack: - -#### 3.1 Assistants Table -- **Purpose**: Assistant configuration and metadata -- **Consumers**: AppApiStack only -- **GSIs**: OwnerStatusIndex, VisibilityStatusIndex, SharedWithIndex - -#### 3.2 AssistantsDocumentsBucket -- **Purpose**: Document storage for RAG ingestion -- **Consumers**: AppApiStack only - -#### 3.3 AssistantsVectorBucket and AssistantsVectorIndex -- **Purpose**: Vector embeddings for RAG -- **Consumers**: AppApiStack only - -#### 3.4 UserFiles Table and UserFilesBucket -- **Purpose**: User file uploads and metadata -- **Consumers**: AppApiStack only - -#### 3.5 RuntimeProvisioner Lambda -- **Purpose**: Provisions AgentCore runtimes on auth provider changes -- **Consumers**: AppApiStack only -- **Event Source**: AuthProviders table DynamoDB Stream - -#### 3.6 RuntimeUpdater Lambda -- **Purpose**: Updates AgentCore runtimes on image tag changes -- **Consumers**: AppApiStack only - -### 4. SSM Parameter Paths - -All SSM parameter paths remain unchanged to maintain compatibility: - -| Resource | Name Parameter | ARN Parameter | Stream ARN Parameter | -|----------|---------------|---------------|---------------------| -| UserQuotas | `/${projectPrefix}/quota/user-quotas-table-name` | `/${projectPrefix}/quota/user-quotas-table-arn` | - | -| QuotaEvents | `/${projectPrefix}/quota/quota-events-table-name` | `/${projectPrefix}/quota/quota-events-table-arn` | - | -| SessionsMetadata | `/${projectPrefix}/cost-tracking/sessions-metadata-table-name` | `/${projectPrefix}/cost-tracking/sessions-metadata-table-arn` | - | -| UserCostSummary | `/${projectPrefix}/cost-tracking/user-cost-summary-table-name` | `/${projectPrefix}/cost-tracking/user-cost-summary-table-arn` | - | -| SystemCostRollup | `/${projectPrefix}/cost-tracking/system-cost-rollup-table-name` | `/${projectPrefix}/cost-tracking/system-cost-rollup-table-arn` | - | -| ManagedModels | `/${projectPrefix}/admin/managed-models-table-name` | `/${projectPrefix}/admin/managed-models-table-arn` | - | -| AuthProviders | `/${projectPrefix}/auth/auth-providers-table-name` | `/${projectPrefix}/auth/auth-providers-table-arn` | `/${projectPrefix}/auth/auth-providers-stream-arn` | -| auth-provider-secrets | - | `/${projectPrefix}/auth/auth-provider-secrets-arn` | - | - -### 5. IAM Permission Patterns - -#### 5.1 AppApiStack ECS Task Role -The ECS task role must maintain the same DynamoDB permissions after the refactor. Instead of using `table.grantReadWriteData()` on local table constructs, it will use explicit IAM policy statements with imported ARNs: - -**Before (local table):** -```typescript -userQuotasTable.grantReadWriteData(taskDefinition.taskRole); -``` - -**After (imported ARN):** -```typescript -const userQuotasTableArn = ssm.StringParameter.valueForStringParameter( - this, - `/${config.projectPrefix}/quota/user-quotas-table-arn` -); - -taskDefinition.taskRole.addToPrincipalPolicy( - new iam.PolicyStatement({ - sid: 'UserQuotasTableAccess', - effect: iam.Effect.ALLOW, - actions: [ - 'dynamodb:GetItem', - 'dynamodb:PutItem', - 'dynamodb:UpdateItem', - 'dynamodb:DeleteItem', - 'dynamodb:Query', - 'dynamodb:Scan', - 'dynamodb:BatchGetItem', - 'dynamodb:BatchWriteItem', - ], - resources: [ - userQuotasTableArn, - `${userQuotasTableArn}/index/*`, - ], - }) -); -``` - -#### 5.2 RuntimeProvisioner Lambda -The RuntimeProvisioner Lambda requires special handling because it uses the AuthProviders table as a DynamoDB Stream event source. The table must be reconstructed using `dynamodb.Table.fromTableAttributes()`: - -```typescript -const authProvidersTableName = ssm.StringParameter.valueForStringParameter( - this, - `/${config.projectPrefix}/auth/auth-providers-table-name` -); -const authProvidersTableArn = ssm.StringParameter.valueForStringParameter( - this, - `/${config.projectPrefix}/auth/auth-providers-table-arn` -); -const authProvidersStreamArn = ssm.StringParameter.valueForStringParameter( - this, - `/${config.projectPrefix}/auth/auth-providers-stream-arn` -); - -const authProvidersTable = dynamodb.Table.fromTableAttributes(this, 'ImportedAuthProvidersTable', { - tableName: authProvidersTableName, - tableArn: authProvidersTableArn, - tableStreamArn: authProvidersStreamArn, -}); - -// Now can use table.grantStreamRead() and add event source -authProvidersTable.grantStreamRead(runtimeProvisionerFunction); -runtimeProvisionerFunction.addEventSource( - new lambdaEventSources.DynamoEventSource(authProvidersTable, { - startingPosition: lambda.StartingPosition.LATEST, - batchSize: 1, - retryAttempts: 3, - bisectBatchOnError: true, - }) -); -``` - -#### 5.3 InferenceApiStack Runtime Execution Role -The InferenceApiStack already imports shared table ARNs via SSM and grants permissions using explicit IAM policy statements. No changes are required to InferenceApiStack beyond updating the comments to reflect that tables are now imported from InfrastructureStack instead of AppApiStack. - -### 6. Environment Variables - -The AppApiStack ECS container environment variables must continue to reference the same table names. The only change is that table names are now imported from SSM instead of being local references: - -**Before (local table):** -```typescript -environment: { - DYNAMODB_QUOTA_TABLE: userQuotasTable.tableName, - DYNAMODB_EVENTS_TABLE: quotaEventsTable.tableName, - // ... -} -``` - -**After (imported from SSM):** -```typescript -const userQuotasTableName = ssm.StringParameter.valueForStringParameter( - this, - `/${config.projectPrefix}/quota/user-quotas-table-name` -); -const quotaEventsTableName = ssm.StringParameter.valueForStringParameter( - this, - `/${config.projectPrefix}/quota/quota-events-table-name` -); - -environment: { - DYNAMODB_QUOTA_TABLE: userQuotasTableName, - DYNAMODB_EVENTS_TABLE: quotaEventsTableName, - // ... -} -``` - -## Data Models - -No data model changes are required. All table schemas, partition keys, sort keys, GSI definitions, and attribute types remain identical. The refactor only changes which CDK stack creates the tables, not the table definitions themselves. - -### Table Schema Preservation - -Each table definition must be copied exactly from AppApiStack to InfrastructureStack with the following preserved: -- Table name generation: `getResourceName(config, '')` -- Partition key and sort key names and types -- Billing mode: `PAY_PER_REQUEST` -- Point-in-time recovery: `true` -- Encryption: `AWS_MANAGED` -- Removal policy: `getRemovalPolicy(config)` -- GSI names, key schemas, and projection types -- Special features: TTL attribute (SessionsMetadata), DynamoDB Stream (AuthProviders) - -## Correctness Properties - -*A property is a characteristic or behavior that should hold true across all valid executions of a system—essentially, a formal statement about what the system should do. Properties serve as the bridge between human-readable specifications and machine-verifiable correctness guarantees.* - -### Analysis - -This refactoring is a pure infrastructure change that modifies CDK stack definitions without altering runtime application behavior. All acceptance criteria specify infrastructure configuration requirements (table schemas, SSM parameter paths, IAM policies, deployment order) rather than functional runtime properties. - -The correctness of this refactor is validated through: -1. **CloudFormation Template Comparison**: Synthesized templates before/after should show tables moved from AppApiStack to InfrastructureStack with identical configurations -2. **Deployment Testing**: Deploying to a fresh AWS account should succeed without circular dependency errors -3. **Integration Testing**: Application code should function identically after the refactor -4. **Manual Verification**: SSM parameters, IAM policies, and environment variables should match pre-refactor values - -### Property-Based Testing Applicability - -After analyzing all 8 requirements and their 40+ acceptance criteria, **none are suitable for property-based testing** because: -- They specify infrastructure configuration, not runtime behavior -- They describe CDK code structure, not application logic -- They define deployment sequencing, not functional properties -- They are one-time deployment concerns, not repeatable runtime properties - -Property-based testing is designed for validating universal properties across many generated inputs (e.g., "for all valid tasks, adding then removing should restore the original state"). Infrastructure refactoring does not have this characteristic—it's a one-time structural change validated through deployment testing and template comparison. - -### No Testable Properties - -Based on the prework analysis, there are no acceptance criteria that can be expressed as universally quantified properties suitable for property-based testing. All requirements are infrastructure configuration specifications that should be validated through: -- CDK synthesis and CloudFormation template inspection -- Deployment to test/staging environments -- Integration tests verifying application behavior is unchanged -- Manual verification of SSM parameters and IAM policies - -## Error Handling - -### Deployment Errors - -#### Circular Dependency Detection -**Error**: `ValidationError: Unable to fetch parameters [/${projectPrefix}/...] (Parameter does not exist)` - -**Cause**: Attempting to deploy AppApiStack before InfrastructureStack has created and exported the shared table SSM parameters. - -**Resolution**: Deploy stacks in the correct order: -1. InfrastructureStack -2. RagIngestionStack -3. InferenceApiStack -4. AppApiStack - -#### Missing SSM Parameters -**Error**: `Parameter /${projectPrefix}/quota/user-quotas-table-arn does not exist` - -**Cause**: InfrastructureStack was deployed without the shared table definitions, or SSM parameter exports are missing. - -**Resolution**: Verify InfrastructureStack includes all 7 shared table definitions and their SSM parameter exports. - -#### IAM Permission Errors -**Error**: `User: arn:aws:sts::123456789012:assumed-role/... is not authorized to perform: dynamodb:GetItem on resource: arn:aws:dynamodb:...` - -**Cause**: IAM policy statements in AppApiStack or InferenceApiStack are missing required permissions after switching from `table.grantReadWriteData()` to explicit policy statements. - -**Resolution**: Verify all IAM policy statements include the same actions as the original `grantReadWriteData()` calls: -- GetItem, PutItem, UpdateItem, DeleteItem -- Query, Scan -- BatchGetItem, BatchWriteItem (where applicable) -- Permissions for both table ARN and `${tableArn}/index/*` - -#### DynamoDB Stream Event Source Errors -**Error**: `Cannot add event source: table stream ARN is undefined` - -**Cause**: RuntimeProvisioner Lambda cannot attach to AuthProviders table stream because the table was not reconstructed using `fromTableAttributes()` with `tableStreamArn`. - -**Resolution**: Use `dynamodb.Table.fromTableAttributes()` to reconstruct the table reference with all three attributes: `tableName`, `tableArn`, and `tableStreamArn`. - -### Rollback Strategy - -If deployment fails or issues are discovered after deployment: - -1. **Immediate Rollback**: Revert the CDK code changes and redeploy the original stack configuration -2. **Data Preservation**: All tables use `getRemovalPolicy(config)` which is RETAIN for production, ensuring no data loss during rollback -3. **SSM Parameter Cleanup**: Manually delete duplicate SSM parameters if both old and new stacks created them -4. **Gradual Migration**: Deploy to dev/staging environments first to validate the refactor before production - -## Testing Strategy - -### Unit Testing - -This refactor does not require new unit tests because: -- No application code changes (backend, frontend, Lambda functions) -- No new business logic or algorithms -- Infrastructure changes are validated through deployment testing - -### Integration Testing - -Integration tests should verify that application behavior is unchanged after the refactor: - -1. **Quota Management Tests** - - Create quota assignments - - Query quota usage - - Verify quota enforcement - -2. **Cost Tracking Tests** - - Record session metadata - - Query user cost summaries - - Verify cost aggregation - -3. **Auth Provider Tests** - - Create/update auth providers - - Verify RuntimeProvisioner Lambda triggers on changes - - Verify runtime provisioning succeeds - -4. **Model Management Tests** - - Create/update managed models - - Query model pricing data - -### Deployment Testing - -The primary validation for this refactor is successful deployment to a fresh AWS account: - -1. **Fresh Account Deployment** - - Deploy to a new AWS account with no existing resources - - Verify deployment order: InfrastructureStack → RagIngestionStack → InferenceApiStack → AppApiStack - - Verify no circular dependency errors - - Verify all SSM parameters are created correctly - -2. **Update Deployment** - - Deploy the refactored stacks to an existing environment - - Verify CloudFormation detects table moves (delete from AppApiStack, create in InfrastructureStack) - - Verify no data loss (tables use RETAIN removal policy) - - Verify application continues functioning - -3. **SSM Parameter Verification** - - Query all SSM parameters after deployment - - Verify parameter paths match expected values - - Verify parameter values (table names, ARNs) are correct - -4. **IAM Permission Verification** - - Inspect ECS task role policies - - Inspect Lambda function role policies - - Verify all required DynamoDB actions are granted - - Verify index ARNs are included in resource lists - -### CloudFormation Template Comparison - -Before deploying, compare synthesized CloudFormation templates: - -```bash -# Synthesize before refactor -git checkout main -cd infrastructure -npx cdk synth InfrastructureStack > /tmp/infra-before.yaml -npx cdk synth AppApiStack > /tmp/app-before.yaml - -# Synthesize after refactor -git checkout feature/shared-tables-refactor -npx cdk synth InfrastructureStack > /tmp/infra-after.yaml -npx cdk synth AppApiStack > /tmp/app-after.yaml - -# Compare -diff /tmp/infra-before.yaml /tmp/infra-after.yaml # Should show 7 new tables -diff /tmp/app-before.yaml /tmp/app-after.yaml # Should show 7 tables removed -``` - -Expected changes: -- InfrastructureStack: +7 DynamoDB tables, +1 Secrets Manager secret, +9 SSM parameters -- AppApiStack: -7 DynamoDB tables, -1 Secrets Manager secret, -9 SSM parameters, +SSM imports, +explicit IAM policies - -### Manual Verification Checklist - -After deployment, manually verify: - -- [ ] All 7 shared tables exist in DynamoDB console -- [ ] All tables have correct schemas (PK, SK, GSIs) -- [ ] All tables have correct billing mode (PAY_PER_REQUEST) -- [ ] All tables have point-in-time recovery enabled -- [ ] SessionsMetadata table has TTL attribute configured -- [ ] AuthProviders table has DynamoDB Stream enabled -- [ ] auth-provider-secrets exists in Secrets Manager -- [ ] All SSM parameters exist with correct paths -- [ ] AppApiStack ECS task role has DynamoDB permissions -- [ ] InferenceApiStack runtime role has DynamoDB permissions -- [ ] RuntimeProvisioner Lambda has DynamoDB Stream event source -- [ ] Application endpoints respond correctly -- [ ] No errors in CloudWatch Logs - -## Implementation Notes - -### Code Organization - -The refactor touches only CDK stack files: -- `infrastructure/lib/infrastructure-stack.ts` (add table definitions) -- `infrastructure/lib/app-api-stack.ts` (remove table definitions, add SSM imports) -- `infrastructure/lib/inference-api-stack.ts` (update comments only) - -### Table Definition Copy-Paste - -When copying table definitions from AppApiStack to InfrastructureStack: -1. Copy the entire table definition block (including comments) -2. Copy the GSI definitions exactly -3. Copy the SSM parameter exports exactly -4. Verify `getResourceName(config, '')` calls use the same suffix -5. Verify `getRemovalPolicy(config)` is used (not hardcoded) - -### Import Pattern - -When importing tables in AppApiStack: -1. Import table name via SSM -2. Import table ARN via SSM -3. Import stream ARN via SSM (AuthProviders only) -4. Use imported values in environment variables -5. Use imported ARNs in IAM policy statements -6. Use `fromTableAttributes()` for tables with event sources - -### Deployment Order - -The deployment order is enforced by SSM parameter dependencies: -1. InfrastructureStack creates and exports SSM parameters -2. RagIngestionStack imports network resources from InfrastructureStack -3. InferenceApiStack imports network and shared table resources -4. AppApiStack imports all upstream resources - -CDK will automatically detect the dependency order based on SSM parameter imports. - -### Removal Policy Considerations - -All shared tables use `getRemovalPolicy(config)` which returns: -- `RETAIN` for production environments (preserves data on stack deletion) -- `DESTROY` for dev/staging environments (allows clean teardown) - -When moving tables from AppApiStack to InfrastructureStack, CloudFormation will: -1. Delete the table resource from AppApiStack (but retain the actual table due to RETAIN policy) -2. Import the existing table into InfrastructureStack (no data loss) - -This is safe for production deployments. - -### SSM Parameter Naming - -All SSM parameter paths follow the convention: -``` -/${projectPrefix}/{category}/{resource-name} -``` - -Categories: -- `/quota/` - Quota management tables -- `/cost-tracking/` - Cost tracking tables -- `/admin/` - Admin management tables -- `/auth/` - Authentication tables and secrets - -This naming convention is preserved exactly to maintain compatibility with application code that reads these parameters. - diff --git a/.kiro/specs/shared-tables-refactor/requirements.md b/.kiro/specs/shared-tables-refactor/requirements.md deleted file mode 100644 index df68967c..00000000 --- a/.kiro/specs/shared-tables-refactor/requirements.md +++ /dev/null @@ -1,127 +0,0 @@ -# Requirements Document - -## Introduction - -The AgentCore Public Stack uses AWS CDK to define infrastructure across multiple stacks. Currently, `AppApiStack` creates 7 shared DynamoDB tables (UserQuotas, QuotaEvents, SessionsMetadata, UserCostSummary, SystemCostRollup, ManagedModels, AuthProviders) and a Secrets Manager resource (auth-provider-secrets) that are consumed by both `AppApiStack` and `InferenceApiStack`. Because `AppApiStack` also imports SSM parameters from `InferenceApiStack` and `RagIngestionStack`, a circular SSM parameter dependency exists that prevents deployment to a fresh AWS account. - -This feature moves the shared DynamoDB tables and related resources from `AppApiStack` to `InfrastructureStack` (the foundation layer), breaking the circular dependency and enabling a clean linear deployment order: InfrastructureStack → RagIngestionStack → InferenceApiStack → AppApiStack. - -## Glossary - -- **InfrastructureStack**: The foundation CDK stack (`infrastructure/lib/infrastructure-stack.ts`) that creates VPC, ALB, ECS Cluster, and core DynamoDB tables. Deploys first with no upstream dependencies. -- **AppApiStack**: The backend service CDK stack (`infrastructure/lib/app-api-stack.ts`) that creates the ECS Fargate service for the App API and currently owns the shared tables. -- **InferenceApiStack**: The inference CDK stack (`infrastructure/lib/inference-api-stack.ts`) that creates AgentCore resources (Memory, Code Interpreter, Browser) and imports shared table ARNs via SSM. -- **RagIngestionStack**: The RAG ingestion CDK stack that creates the assistants table, documents bucket, and vector bucket resources consumed by AppApiStack. -- **Shared_Tables**: The 7 DynamoDB tables consumed by both AppApiStack and InferenceApiStack: UserQuotas, QuotaEvents, SessionsMetadata, UserCostSummary, SystemCostRollup, ManagedModels, AuthProviders. -- **SSM_Parameter**: An AWS Systems Manager Parameter Store entry used for cross-stack references, following the `/${projectPrefix}/...` naming convention. -- **Deployment_Order**: The sequence in which CDK stacks must be deployed: InfrastructureStack → RagIngestionStack → InferenceApiStack → AppApiStack. -- **Stack_Dependency_Graph**: A directed graph where an edge from StackA to StackB means StackB reads an SSM parameter that StackA writes. - -## Requirements - -### Requirement 1: Move Shared DynamoDB Tables to InfrastructureStack - -**User Story:** As a DevOps engineer, I want shared DynamoDB tables created in the foundation layer, so that all consumer stacks can import them without circular dependencies. - -#### Acceptance Criteria - -1. WHEN the InfrastructureStack is deployed, THE InfrastructureStack SHALL create the UserQuotas DynamoDB table with partition key PK (String), sort key SK (String), PAY_PER_REQUEST billing, point-in-time recovery enabled, AWS_MANAGED encryption, and GSIs: AssignmentTypeIndex, UserAssignmentIndex, RoleAssignmentIndex, UserOverrideIndex, AppRoleAssignmentIndex -2. WHEN the InfrastructureStack is deployed, THE InfrastructureStack SHALL create the QuotaEvents DynamoDB table with partition key PK (String), sort key SK (String), PAY_PER_REQUEST billing, point-in-time recovery enabled, AWS_MANAGED encryption, and GSI: TierEventIndex -3. WHEN the InfrastructureStack is deployed, THE InfrastructureStack SHALL create the SessionsMetadata DynamoDB table with partition key PK (String), sort key SK (String), PAY_PER_REQUEST billing, point-in-time recovery enabled, AWS_MANAGED encryption, TTL attribute "ttl", and GSIs: UserTimestampIndex, SessionLookupIndex -4. WHEN the InfrastructureStack is deployed, THE InfrastructureStack SHALL create the UserCostSummary DynamoDB table with partition key PK (String), sort key SK (String), PAY_PER_REQUEST billing, point-in-time recovery enabled, AWS_MANAGED encryption, and GSI: PeriodCostIndex (with INCLUDE projection for userId, totalCost, totalRequests, lastUpdated) -5. WHEN the InfrastructureStack is deployed, THE InfrastructureStack SHALL create the SystemCostRollup DynamoDB table with partition key PK (String), sort key SK (String), PAY_PER_REQUEST billing, point-in-time recovery enabled, and AWS_MANAGED encryption -6. WHEN the InfrastructureStack is deployed, THE InfrastructureStack SHALL create the ManagedModels DynamoDB table with partition key PK (String), sort key SK (String), PAY_PER_REQUEST billing, point-in-time recovery enabled, AWS_MANAGED encryption, and GSI: ModelIdIndex -7. WHEN the InfrastructureStack is deployed, THE InfrastructureStack SHALL create the AuthProviders DynamoDB table with partition key PK (String), sort key SK (String), PAY_PER_REQUEST billing, point-in-time recovery enabled, AWS_MANAGED encryption, DynamoDB Stream (NEW_AND_OLD_IMAGES), and GSI: EnabledProvidersIndex -8. WHEN the InfrastructureStack is deployed, THE InfrastructureStack SHALL create the auth-provider-secrets Secrets Manager resource with RETAIN removal policy - - -### Requirement 2: Export Shared Table SSM Parameters from InfrastructureStack - -**User Story:** As a DevOps engineer, I want shared table names and ARNs exported to SSM from InfrastructureStack, so that consumer stacks can import them using the existing parameter paths. - -#### Acceptance Criteria - -1. WHEN the InfrastructureStack creates the shared tables, THE InfrastructureStack SHALL export SSM parameters for UserQuotas table at paths `/${projectPrefix}/quota/user-quotas-table-name` and `/${projectPrefix}/quota/user-quotas-table-arn` -2. WHEN the InfrastructureStack creates the shared tables, THE InfrastructureStack SHALL export SSM parameters for QuotaEvents table at paths `/${projectPrefix}/quota/quota-events-table-name` and `/${projectPrefix}/quota/quota-events-table-arn` -3. WHEN the InfrastructureStack creates the shared tables, THE InfrastructureStack SHALL export SSM parameters for SessionsMetadata table at paths `/${projectPrefix}/cost-tracking/sessions-metadata-table-name` and `/${projectPrefix}/cost-tracking/sessions-metadata-table-arn` -4. WHEN the InfrastructureStack creates the shared tables, THE InfrastructureStack SHALL export SSM parameters for UserCostSummary table at paths `/${projectPrefix}/cost-tracking/user-cost-summary-table-name` and `/${projectPrefix}/cost-tracking/user-cost-summary-table-arn` -5. WHEN the InfrastructureStack creates the shared tables, THE InfrastructureStack SHALL export SSM parameters for SystemCostRollup table at paths `/${projectPrefix}/cost-tracking/system-cost-rollup-table-name` and `/${projectPrefix}/cost-tracking/system-cost-rollup-table-arn` -6. WHEN the InfrastructureStack creates the shared tables, THE InfrastructureStack SHALL export SSM parameters for ManagedModels table at paths `/${projectPrefix}/admin/managed-models-table-name` and `/${projectPrefix}/admin/managed-models-table-arn` -7. WHEN the InfrastructureStack creates the shared tables, THE InfrastructureStack SHALL export SSM parameters for AuthProviders table at paths `/${projectPrefix}/auth/auth-providers-table-name` and `/${projectPrefix}/auth/auth-providers-table-arn` -8. WHEN the InfrastructureStack creates the shared tables, THE InfrastructureStack SHALL export SSM parameters for AuthProviders stream ARN at path `/${projectPrefix}/auth/auth-providers-stream-arn` -9. WHEN the InfrastructureStack creates the shared tables, THE InfrastructureStack SHALL export SSM parameter for auth-provider-secrets ARN at path `/${projectPrefix}/auth/auth-provider-secrets-arn` - -### Requirement 3: Remove Shared Table Definitions from AppApiStack - -**User Story:** As a DevOps engineer, I want shared table definitions removed from AppApiStack, so that AppApiStack no longer creates resources that belong in the foundation layer. - -#### Acceptance Criteria - -1. WHEN the AppApiStack is deployed, THE AppApiStack SHALL import shared table names and ARNs via SSM parameters from InfrastructureStack instead of creating the 7 shared DynamoDB tables locally -2. WHEN the AppApiStack is deployed, THE AppApiStack SHALL import the auth-provider-secrets ARN via SSM parameter from InfrastructureStack instead of creating the Secrets Manager resource locally -3. WHEN the AppApiStack is deployed, THE AppApiStack SHALL use imported SSM values for ECS container environment variables that reference shared table names (DYNAMODB_QUOTA_TABLE, DYNAMODB_EVENTS_TABLE, DYNAMODB_MANAGED_MODELS_TABLE_NAME, DYNAMODB_SESSIONS_METADATA_TABLE_NAME, DYNAMODB_COST_SUMMARY_TABLE_NAME, DYNAMODB_SYSTEM_ROLLUP_TABLE_NAME, DYNAMODB_AUTH_PROVIDERS_TABLE_NAME, AUTH_PROVIDER_SECRETS_ARN) -4. WHEN the AppApiStack is deployed, THE AppApiStack SHALL grant the ECS task role the same DynamoDB read/write permissions on shared table ARNs using explicit IAM policy statements with imported ARNs -5. WHEN the AppApiStack is deployed, THE AppApiStack SHALL use `dynamodb.Table.fromTableAttributes()` to reconstruct the AuthProviders table reference for the RuntimeProvisioner Lambda DynamoDB Stream event source -6. WHEN the AppApiStack is deployed, THE AppApiStack SHALL grant the RuntimeProvisioner and RuntimeUpdater Lambda functions the same DynamoDB permissions on the AuthProviders table using imported ARNs - -### Requirement 4: Eliminate Circular SSM Dependency - -**User Story:** As a DevOps engineer, I want a valid linear deployment order with no circular dependencies, so that the stack can be deployed to a fresh AWS account without errors. - -#### Acceptance Criteria - -1. THE Stack_Dependency_Graph SHALL form a directed acyclic graph (DAG) with no cycles between any stacks -2. WHEN deploying to a fresh AWS account, THE Deployment_Order SHALL support InfrastructureStack → RagIngestionStack → InferenceApiStack → AppApiStack, where each stack only reads SSM parameters written by stacks earlier in the sequence -3. WHEN deploying InfrastructureStack first, THE InfrastructureStack SHALL create all shared tables and export SSM parameters before any consumer stack deploys -4. WHEN deploying InferenceApiStack after InfrastructureStack, THE InferenceApiStack SHALL successfully import shared table ARNs from SSM parameters created by InfrastructureStack -5. WHEN deploying AppApiStack after InfrastructureStack, RagIngestionStack, and InferenceApiStack, THE AppApiStack SHALL successfully import all required SSM parameters without encountering `ValidationError: Unable to fetch parameters` - -### Requirement 5: Preserve Non-Shared Resources in AppApiStack - -**User Story:** As a DevOps engineer, I want resources that are only used by AppApiStack to remain in AppApiStack, so that the refactor scope is minimal and non-shared resources stay in the correct layer. - -#### Acceptance Criteria - -1. THE AppApiStack SHALL continue to create and manage the Assistants DynamoDB table with GSIs: OwnerStatusIndex, VisibilityStatusIndex, SharedWithIndex -2. THE AppApiStack SHALL continue to create and manage the AssistantsDocumentsBucket S3 bucket -3. THE AppApiStack SHALL continue to create and manage the AssistantsVectorBucket S3 Vector Bucket and AssistantsVectorIndex -4. THE AppApiStack SHALL continue to create and manage the UserFiles DynamoDB table and UserFilesBucket S3 bucket -5. THE AppApiStack SHALL continue to create and manage the RuntimeProvisioner Lambda function and RuntimeUpdater Lambda function - -### Requirement 6: Preserve Table Definitions Identically - -**User Story:** As a DevOps engineer, I want moved table definitions to be identical to the originals, so that no data schema changes or behavioral differences are introduced. - -#### Acceptance Criteria - -1. FOR ALL shared DynamoDB tables moved to InfrastructureStack, THE InfrastructureStack SHALL use the same table names generated by `getResourceName(config, ...)` as the original AppApiStack definitions -2. FOR ALL shared DynamoDB tables moved to InfrastructureStack, THE InfrastructureStack SHALL use the same partition key schemas, sort key schemas, and attribute definitions as the original AppApiStack definitions -3. FOR ALL shared DynamoDB tables with GSIs, THE InfrastructureStack SHALL define the same GSI names, key schemas, and projection types (including nonKeyAttributes where applicable) as the original AppApiStack definitions -4. FOR ALL shared DynamoDB tables moved to InfrastructureStack, THE InfrastructureStack SHALL use the same billingMode (PAY_PER_REQUEST), pointInTimeRecovery, encryption (AWS_MANAGED), and removalPolicy settings as the original AppApiStack definitions -5. WHEN the AuthProviders table is moved, THE InfrastructureStack SHALL preserve the DynamoDB Stream configuration (NEW_AND_OLD_IMAGES) -6. WHEN the SessionsMetadata table is moved, THE InfrastructureStack SHALL preserve the TTL attribute ("ttl") -7. WHEN the PeriodCostIndex GSI on UserCostSummary is moved, THE InfrastructureStack SHALL preserve the INCLUDE projection type with nonKeyAttributes: userId, totalCost, totalRequests, lastUpdated - -### Requirement 7: Preserve IAM Permissions and Environment Variables - -**User Story:** As a DevOps engineer, I want IAM permissions and ECS environment variables to produce the same effective configuration after the refactor, so that backend application code is completely unaffected. - -#### Acceptance Criteria - -1. WHEN the AppApiStack ECS task role references shared tables, THE AppApiStack SHALL grant the same DynamoDB actions (GetItem, PutItem, UpdateItem, DeleteItem, Query, Scan, BatchGetItem, BatchWriteItem as applicable) on the same table ARNs and index ARNs as before the refactor -2. WHEN the InferenceApiStack runtime execution role references shared tables, THE InferenceApiStack SHALL continue to read the same SSM parameter paths for shared table ARNs and grant the same DynamoDB and Secrets Manager permissions -3. WHEN the AppApiStack ECS container is configured, THE AppApiStack SHALL pass the same table name values in environment variables as before the refactor -4. WHEN the RuntimeProvisioner Lambda references the AuthProviders table, THE AppApiStack SHALL grant the same DynamoDB Stream read permissions and DynamoDB read/write permissions using the imported table reference -5. WHEN the RuntimeUpdater Lambda references the AuthProviders table, THE AppApiStack SHALL grant the same DynamoDB read/write permissions using the imported table reference - -### Requirement 8: Scope Changes to CDK Infrastructure Code Only - -**User Story:** As a DevOps engineer, I want all changes confined to CDK infrastructure code, so that backend application code, frontend code, Lambda function code, and deployment scripts remain unchanged. - -#### Acceptance Criteria - -1. THE refactor SHALL modify only files within the `infrastructure/lib/` directory (CDK stack definitions) -2. THE refactor SHALL NOT modify any backend Python application code in `backend/src/` -3. THE refactor SHALL NOT modify any frontend Angular application code in `frontend/ai.client/` -4. THE refactor SHALL NOT modify any Lambda function code in `backend/lambda-functions/` -5. THE refactor SHALL NOT modify any deployment scripts in `scripts/` or GitHub Actions workflows in `.github/workflows/` diff --git a/.kiro/specs/shared-tables-refactor/tasks.md b/.kiro/specs/shared-tables-refactor/tasks.md deleted file mode 100644 index 5f161fb9..00000000 --- a/.kiro/specs/shared-tables-refactor/tasks.md +++ /dev/null @@ -1,190 +0,0 @@ -# Implementation Plan: Shared Tables Refactor - -## Overview - -This implementation plan refactors the CDK infrastructure to move 7 shared DynamoDB tables and the auth-provider-secrets Secrets Manager resource from AppApiStack to InfrastructureStack. This eliminates a circular SSM parameter dependency and establishes a clean linear deployment order: InfrastructureStack → RagIngestionStack → InferenceApiStack → AppApiStack. - -All changes are confined to `infrastructure/lib/` directory. No application code, Lambda functions, deployment scripts, or workflows are modified. The refactor preserves all table schemas, GSI definitions, IAM permissions, and environment variables exactly as they exist today. - -## Tasks - -- [x] 1. Move shared DynamoDB tables to InfrastructureStack - - [x] 1.1 Add UserQuotas table definition to InfrastructureStack - - Copy table definition from AppApiStack with partition key PK, sort key SK, PAY_PER_REQUEST billing - - Include all 5 GSIs: AssignmentTypeIndex, UserAssignmentIndex, RoleAssignmentIndex, UserOverrideIndex, AppRoleAssignmentIndex - - Add SSM parameter exports for table name and ARN at `/${projectPrefix}/quota/user-quotas-table-name` and `/${projectPrefix}/quota/user-quotas-table-arn` - - _Requirements: 1.1, 2.1, 6.1, 6.2, 6.3, 6.4_ - - - [x] 1.2 Add QuotaEvents table definition to InfrastructureStack - - Copy table definition from AppApiStack with partition key PK, sort key SK, PAY_PER_REQUEST billing - - Include GSI: TierEventIndex - - Add SSM parameter exports for table name and ARN at `/${projectPrefix}/quota/quota-events-table-name` and `/${projectPrefix}/quota/quota-events-table-arn` - - _Requirements: 1.2, 2.2, 6.1, 6.2, 6.3, 6.4_ - - - [x] 1.3 Add SessionsMetadata table definition to InfrastructureStack - - Copy table definition from AppApiStack with partition key PK, sort key SK, PAY_PER_REQUEST billing - - Include TTL attribute "ttl" configuration - - Include GSIs: UserTimestampIndex, SessionLookupIndex - - Add SSM parameter exports for table name and ARN at `/${projectPrefix}/cost-tracking/sessions-metadata-table-name` and `/${projectPrefix}/cost-tracking/sessions-metadata-table-arn` - - _Requirements: 1.3, 2.3, 6.1, 6.2, 6.3, 6.4, 6.6_ - - - [x] 1.4 Add UserCostSummary table definition to InfrastructureStack - - Copy table definition from AppApiStack with partition key PK, sort key SK, PAY_PER_REQUEST billing - - Include GSI: PeriodCostIndex with INCLUDE projection type and nonKeyAttributes: userId, totalCost, totalRequests, lastUpdated - - Add SSM parameter exports for table name and ARN at `/${projectPrefix}/cost-tracking/user-cost-summary-table-name` and `/${projectPrefix}/cost-tracking/user-cost-summary-table-arn` - - _Requirements: 1.4, 2.4, 6.1, 6.2, 6.3, 6.4, 6.7_ - - - [x] 1.5 Add SystemCostRollup table definition to InfrastructureStack - - Copy table definition from AppApiStack with partition key PK, sort key SK, PAY_PER_REQUEST billing - - Add SSM parameter exports for table name and ARN at `/${projectPrefix}/cost-tracking/system-cost-rollup-table-name` and `/${projectPrefix}/cost-tracking/system-cost-rollup-table-arn` - - _Requirements: 1.5, 2.5, 6.1, 6.2, 6.3, 6.4_ - - - [x] 1.6 Add ManagedModels table definition to InfrastructureStack - - Copy table definition from AppApiStack with partition key PK, sort key SK, PAY_PER_REQUEST billing - - Include GSI: ModelIdIndex - - Add SSM parameter exports for table name and ARN at `/${projectPrefix}/admin/managed-models-table-name` and `/${projectPrefix}/admin/managed-models-table-arn` - - _Requirements: 1.6, 2.6, 6.1, 6.2, 6.3, 6.4_ - - - [x] 1.7 Add AuthProviders table definition to InfrastructureStack - - Copy table definition from AppApiStack with partition key PK, sort key SK, PAY_PER_REQUEST billing - - Include DynamoDB Stream configuration (NEW_AND_OLD_IMAGES) - - Include GSI: EnabledProvidersIndex - - Add SSM parameter exports for table name, ARN, and stream ARN at `/${projectPrefix}/auth/auth-providers-table-name`, `/${projectPrefix}/auth/auth-providers-table-arn`, and `/${projectPrefix}/auth/auth-providers-stream-arn` - - _Requirements: 1.7, 2.7, 2.8, 6.1, 6.2, 6.3, 6.4, 6.5_ - -- [x] 2. Move auth-provider-secrets to InfrastructureStack - - [x] 2.1 Add auth-provider-secrets Secrets Manager resource to InfrastructureStack - - Copy Secrets Manager secret definition from AppApiStack with RETAIN removal policy - - Add SSM parameter export for secret ARN at `/${projectPrefix}/auth/auth-provider-secrets-arn` - - _Requirements: 1.8, 2.9_ - -- [x] 3. Update AppApiStack to import shared tables via SSM - - [x] 3.1 Remove shared table definitions from AppApiStack - - Remove UserQuotas, QuotaEvents, SessionsMetadata, UserCostSummary, SystemCostRollup, ManagedModels, AuthProviders table definitions - - Remove auth-provider-secrets Secrets Manager resource definition - - Remove SSM parameter exports for shared tables (now exported by InfrastructureStack) - - _Requirements: 3.1, 3.2, 8.1_ - - - [x] 3.2 Import shared table names via SSM in AppApiStack - - Import UserQuotas table name from `/${projectPrefix}/quota/user-quotas-table-name` - - Import QuotaEvents table name from `/${projectPrefix}/quota/quota-events-table-name` - - Import SessionsMetadata table name from `/${projectPrefix}/cost-tracking/sessions-metadata-table-name` - - Import UserCostSummary table name from `/${projectPrefix}/cost-tracking/user-cost-summary-table-name` - - Import SystemCostRollup table name from `/${projectPrefix}/cost-tracking/system-cost-rollup-table-name` - - Import ManagedModels table name from `/${projectPrefix}/admin/managed-models-table-name` - - Import AuthProviders table name from `/${projectPrefix}/auth/auth-providers-table-name` - - _Requirements: 3.1, 3.3_ - - - [x] 3.3 Import shared table ARNs via SSM in AppApiStack - - Import UserQuotas table ARN from `/${projectPrefix}/quota/user-quotas-table-arn` - - Import QuotaEvents table ARN from `/${projectPrefix}/quota/quota-events-table-arn` - - Import SessionsMetadata table ARN from `/${projectPrefix}/cost-tracking/sessions-metadata-table-arn` - - Import UserCostSummary table ARN from `/${projectPrefix}/cost-tracking/user-cost-summary-table-arn` - - Import SystemCostRollup table ARN from `/${projectPrefix}/cost-tracking/system-cost-rollup-table-arn` - - Import ManagedModels table ARN from `/${projectPrefix}/admin/managed-models-table-arn` - - Import AuthProviders table ARN from `/${projectPrefix}/auth/auth-providers-table-arn` - - Import AuthProviders stream ARN from `/${projectPrefix}/auth/auth-providers-stream-arn` - - Import auth-provider-secrets ARN from `/${projectPrefix}/auth/auth-provider-secrets-arn` - - _Requirements: 3.1, 3.2_ - -- [x] 4. Update ECS task role IAM permissions in AppApiStack - - [x] 4.1 Add explicit IAM policy for UserQuotas table access - - Create IAM policy statement with actions: GetItem, PutItem, UpdateItem, DeleteItem, Query, Scan, BatchGetItem, BatchWriteData - - Include resources: table ARN and `${tableArn}/index/*` for GSI access - - Add to ECS task role - - _Requirements: 3.4, 7.1_ - - - [x] 4.2 Add explicit IAM policy for QuotaEvents table access - - Create IAM policy statement with actions: GetItem, PutItem, UpdateItem, DeleteItem, Query, Scan, BatchGetItem, BatchWriteData - - Include resources: table ARN and `${tableArn}/index/*` for GSI access - - Add to ECS task role - - _Requirements: 3.4, 7.1_ - - - [x] 4.3 Add explicit IAM policy for SessionsMetadata table access - - Create IAM policy statement with actions: GetItem, PutItem, UpdateItem, DeleteItem, Query, Scan, BatchGetItem, BatchWriteData - - Include resources: table ARN and `${tableArn}/index/*` for GSI access - - Add to ECS task role - - _Requirements: 3.4, 7.1_ - - - [x] 4.4 Add explicit IAM policy for UserCostSummary table access - - Create IAM policy statement with actions: GetItem, PutItem, UpdateItem, DeleteItem, Query, Scan, BatchGetItem, BatchWriteData - - Include resources: table ARN and `${tableArn}/index/*` for GSI access - - Add to ECS task role - - _Requirements: 3.4, 7.1_ - - - [x] 4.5 Add explicit IAM policy for SystemCostRollup table access - - Create IAM policy statement with actions: GetItem, PutItem, UpdateItem, DeleteItem, Query, Scan, BatchGetItem, BatchWriteData - - Include resources: table ARN and `${tableArn}/index/*` for GSI access - - Add to ECS task role - - _Requirements: 3.4, 7.1_ - - - [x] 4.6 Add explicit IAM policy for ManagedModels table access - - Create IAM policy statement with actions: GetItem, PutItem, UpdateItem, DeleteItem, Query, Scan, BatchGetItem, BatchWriteData - - Include resources: table ARN and `${tableArn}/index/*` for GSI access - - Add to ECS task role - - _Requirements: 3.4, 7.1_ - - - [x] 4.7 Add explicit IAM policy for AuthProviders table access - - Create IAM policy statement with actions: GetItem, PutItem, UpdateItem, DeleteItem, Query, Scan, BatchGetItem, BatchWriteData - - Include resources: table ARN and `${tableArn}/index/*` for GSI access - - Add to ECS task role - - _Requirements: 3.4, 7.1_ - - - [x] 4.8 Add explicit IAM policy for auth-provider-secrets access - - Create IAM policy statement with actions: secretsmanager:GetSecretValue - - Include resource: secret ARN - - Add to ECS task role - - _Requirements: 3.4, 7.1_ - -- [x] 5. Update ECS container environment variables in AppApiStack - - [x] 5.1 Update environment variables to use imported table names - - Set DYNAMODB_QUOTA_TABLE to imported UserQuotas table name - - Set DYNAMODB_EVENTS_TABLE to imported QuotaEvents table name - - Set DYNAMODB_MANAGED_MODELS_TABLE_NAME to imported ManagedModels table name - - Set DYNAMODB_SESSIONS_METADATA_TABLE_NAME to imported SessionsMetadata table name - - Set DYNAMODB_COST_SUMMARY_TABLE_NAME to imported UserCostSummary table name - - Set DYNAMODB_SYSTEM_ROLLUP_TABLE_NAME to imported SystemCostRollup table name - - Set DYNAMODB_AUTH_PROVIDERS_TABLE_NAME to imported AuthProviders table name - - Set AUTH_PROVIDER_SECRETS_ARN to imported secret ARN - - _Requirements: 3.3, 7.3_ - -- [x] 6. Update RuntimeProvisioner Lambda in AppApiStack - - [x] 6.1 Reconstruct AuthProviders table reference using fromTableAttributes - - Use dynamodb.Table.fromTableAttributes() with imported table name, ARN, and stream ARN - - Store reconstructed table reference for event source and IAM grants - - _Requirements: 3.5, 7.4_ - - - [x] 6.2 Update RuntimeProvisioner Lambda DynamoDB Stream event source - - Add DynamoDB Stream event source using reconstructed AuthProviders table reference - - Configure with startingPosition: LATEST, batchSize: 1, retryAttempts: 3, bisectBatchOnError: true - - _Requirements: 3.5, 7.4_ - - - [x] 6.3 Grant RuntimeProvisioner Lambda permissions on AuthProviders table - - Use reconstructed table reference to grant stream read permissions - - Use reconstructed table reference to grant read/write data permissions - - _Requirements: 3.6, 7.4_ - -- [x] 7. Update RuntimeUpdater Lambda in AppApiStack - - [x] 7.1 Grant RuntimeUpdater Lambda permissions on AuthProviders table - - Add explicit IAM policy statement with actions: GetItem, PutItem, UpdateItem, DeleteItem, Query, Scan - - Include resources: imported AuthProviders table ARN and `${tableArn}/index/*` - - _Requirements: 3.6, 7.5_ - -- [x] 8. Checkpoint - Synthesize and compare CloudFormation templates - - Synthesize InfrastructureStack and AppApiStack templates - - Verify InfrastructureStack adds 7 tables, 1 secret, and 9 SSM parameters - - Verify AppApiStack removes 7 tables, 1 secret, and 9 SSM parameters - - Verify AppApiStack adds SSM imports and explicit IAM policies - - Ensure all tests pass, ask the user if questions arise - - _Requirements: 4.1, 4.2, 4.3, 4.4, 4.5_ - -## Notes - -- All changes are confined to `infrastructure/lib/infrastructure-stack.ts` and `infrastructure/lib/app-api-stack.ts` -- No changes to backend application code, Lambda functions, deployment scripts, or workflows -- Table schemas, GSI definitions, billing modes, and encryption settings are preserved exactly -- SSM parameter paths remain unchanged for backward compatibility -- Deployment order becomes: InfrastructureStack → RagIngestionStack → InferenceApiStack → AppApiStack -- Non-shared resources (Assistants, UserFiles, Lambda functions) remain in AppApiStack -- Use `getResourceName(config, ...)` for table names and `getRemovalPolicy(config)` for removal policies -- InferenceApiStack requires no changes (already imports via SSM, just update comments) diff --git a/.kiro/specs/ssm-parameters-audit/.config.kiro b/.kiro/specs/ssm-parameters-audit/.config.kiro deleted file mode 100644 index d30049bf..00000000 --- a/.kiro/specs/ssm-parameters-audit/.config.kiro +++ /dev/null @@ -1 +0,0 @@ -{"generationMode": "requirements-first"} \ No newline at end of file diff --git a/.kiro/specs/ssm-parameters-audit/design.md b/.kiro/specs/ssm-parameters-audit/design.md deleted file mode 100644 index 476e3db2..00000000 --- a/.kiro/specs/ssm-parameters-audit/design.md +++ /dev/null @@ -1,767 +0,0 @@ -# Design Document: SSM Parameters Audit - -## Overview - -This design addresses the missing SSM parameters required by the runtime-provisioner Lambda function. The solution involves auditing existing SSM parameter exports across CDK stacks and adding missing parameters to ensure the Lambda function can successfully fetch all required configuration values. - -The design follows the existing CDK infrastructure patterns established in the project, using SSM Parameter Store for cross-stack references and maintaining consistent naming conventions. - -## Architecture - -### Current State - -The project uses SSM Parameter Store for cross-stack communication: - -``` -InfrastructureStack (Foundation) -├── Exports: VPC, ALB, ECS Cluster, OAuth tables -└── SSM: /network/*, /oauth/*, /users/*, /rbac/* - -InferenceApiStack (AgentCore Resources) -├── Exports: Memory, Code Interpreter, Browser, Runtime Role -└── SSM: /inference-api/* - -GatewayStack (MCP Tools) -├── Exports: Gateway URL, Gateway ID -└── SSM: /gateway/* - -AppApiStack (Application Backend) -├── Exports: DynamoDB tables, S3 buckets -└── SSM: /quota/*, /cost-tracking/*, /file-upload/*, /rag/* - -FrontendStack (CloudFront + S3) -├── Exports: Distribution ID, Frontend URL -└── SSM: /frontend/* -``` - -### Target State - -After this feature, all stacks will export complete SSM parameters required by runtime-provisioner: - -``` -runtime-provisioner Lambda -├── Reads from InfrastructureStack: /oauth/*, /users/*, /rbac/* -├── Reads from InferenceApiStack: /inference-api/* -├── Reads from GatewayStack: /gateway/* -├── Reads from AppApiStack: /rag/* -├── Reads from FrontendStack: /frontend/* -└── Optionally reads: /api-keys/* -``` - -## Components and Interfaces - -### Component 1: InferenceApiStack SSM Exports - -**Purpose**: Export all AgentCore Runtime configuration parameters - -**Existing Parameters** (verified): -- `/${projectPrefix}/inference-api/image-tag` - Docker image tag (set by push-to-ecr.sh) -- `/${projectPrefix}/inference-api/runtime-execution-role-arn` - IAM role ARN for runtimes -- `/${projectPrefix}/inference-api/memory-arn` - AgentCore Memory ARN -- `/${projectPrefix}/inference-api/memory-id` - AgentCore Memory ID -- `/${projectPrefix}/inference-api/code-interpreter-id` - Code Interpreter ID -- `/${projectPrefix}/inference-api/code-interpreter-arn` - Code Interpreter ARN -- `/${projectPrefix}/inference-api/browser-id` - Browser ID -- `/${projectPrefix}/inference-api/browser-arn` - Browser ARN - -**Missing Parameters** (to be added): -- `/${projectPrefix}/inference-api/ecr-repository-uri` - ECR repository URI for container images - -**Implementation**: -```typescript -// In InferenceApiStack constructor, after ECR repository reference - -// Export ECR repository URI for Lambda-created runtimes -new ssm.StringParameter(this, 'EcrRepositoryUriParameter', { - parameterName: `/${config.projectPrefix}/inference-api/ecr-repository-uri`, - stringValue: ecrRepository.repositoryUri, - description: 'Inference API ECR Repository URI for runtime container images', - tier: ssm.ParameterTier.STANDARD, -}); -``` - -### Component 2: GatewayStack SSM Exports - -**Purpose**: Export AgentCore Gateway configuration parameters - -**Existing Parameters** (verified): -- `/${projectPrefix}/gateway/url` - Gateway URL for SigV4 authenticated invocation -- `/${projectPrefix}/gateway/id` - Gateway identifier - -**Status**: No changes needed - all required parameters already exist - -### Component 3: InfrastructureStack SSM Exports - -**Purpose**: Export network and OAuth configuration parameters - -**Existing Parameters** (verified): -- `/${projectPrefix}/network/alb-url` - Application Load Balancer URL -- `/${projectPrefix}/oauth/providers-table-name` - OAuth providers table -- `/${projectPrefix}/oauth/user-tokens-table-name` - OAuth user tokens table -- `/${projectPrefix}/oauth/token-encryption-key-arn` - KMS key for token encryption -- `/${projectPrefix}/oauth/client-secrets-arn` - Secrets Manager ARN for OAuth secrets - -**Missing Parameters** (to be added): -- `/${projectPrefix}/oauth/callback-url` - OAuth callback URL for authentication flows - -**Implementation**: -```typescript -// In InfrastructureStack constructor, after ALB URL export - -// Construct OAuth callback URL -const oauthCallbackUrl = config.frontend?.domainName - ? `https://${config.frontend.domainName}/auth/callback` - : `${albUrl}/auth/callback`; - -// Export OAuth callback URL for runtime provisioner -new ssm.StringParameter(this, 'OAuthCallbackUrlParameter', { - parameterName: `/${config.projectPrefix}/oauth/callback-url`, - stringValue: oauthCallbackUrl, - description: 'OAuth callback URL for authentication provider configuration', - tier: ssm.ParameterTier.STANDARD, -}); -``` - -### Component 4: FrontendStack SSM Exports - -**Purpose**: Export frontend URL and CORS configuration - -**Existing Parameters** (verified): -- `/${projectPrefix}/frontend/url` - Frontend website URL -- `/${projectPrefix}/frontend/distribution-id` - CloudFront distribution ID -- `/${projectPrefix}/frontend/bucket-name` - S3 bucket name - -**Missing Parameters** (to be added): -- `/${projectPrefix}/frontend/cors-origins` - Comma-separated list of allowed CORS origins - -**Implementation**: -```typescript -// In FrontendStack constructor, after frontend URL export - -// Construct CORS origins list -const corsOrigins = config.frontend.domainName - ? `https://${config.frontend.domainName}` - : `https://${this.distributionDomainName}`; - -// Export CORS origins for runtime provisioner -new ssm.StringParameter(this, 'CorsOriginsParameter', { - parameterName: `/${config.projectPrefix}/frontend/cors-origins`, - stringValue: corsOrigins, - description: 'Comma-separated list of allowed CORS origins for OAuth flows', - tier: ssm.ParameterTier.STANDARD, -}); -``` - -### Component 5: Optional API Keys - -**Purpose**: Provide optional external service API keys - -**Parameters** (optional - not created by CDK): -- `/${projectPrefix}/api-keys/tavily-api-key` - Tavily search API key -- `/${projectPrefix}/api-keys/nova-act-api-key` - Nova Act API key - -**Implementation**: These parameters are NOT created by CDK stacks. They must be manually created by administrators when needed: - -```bash -# Manual creation (when needed) -aws ssm put-parameter \ - --name "/${PROJECT_PREFIX}/api-keys/tavily-api-key" \ - --value "YOUR_TAVILY_API_KEY" \ - --type "SecureString" \ - --description "Tavily search API key for web search capabilities" - -aws ssm put-parameter \ - --name "/${PROJECT_PREFIX}/api-keys/nova-act-api-key" \ - --value "YOUR_NOVA_ACT_API_KEY" \ - --type "SecureString" \ - --description "Nova Act API key for browser automation" -``` - -The runtime-provisioner Lambda must handle missing optional parameters gracefully using try-except blocks. - -## Data Models - -### SSM Parameter Structure - -```typescript -interface SSMParameter { - parameterName: string; // Hierarchical path: /${projectPrefix}/{category}/{name} - stringValue: string; // Parameter value (can be token at synth time) - description: string; // Human-readable description - tier: ssm.ParameterTier; // STANDARD or ADVANCED -} -``` - -### Parameter Dependency Matrix - -This matrix documents all SSM parameters used in the system, showing which stacks export each parameter and which stacks/Lambda functions import them. - -| Parameter Path | Exported By | Imported By | Required | Notes | -|---------------|-------------|-------------|----------|-------| -| `/inference-api/image-tag` | push-to-ecr.sh script | InferenceApiStack, runtime-provisioner | Yes | Docker image tag set by CI/CD | -| `/inference-api/ecr-repository-uri` | InferenceApiStack | runtime-provisioner | Yes | ECR repository URI for container images | -| `/inference-api/runtime-execution-role-arn` | InferenceApiStack | runtime-provisioner, AppApiStack | Yes | IAM role ARN for runtimes | -| `/inference-api/memory-arn` | InferenceApiStack | runtime-provisioner, AppApiStack | Yes | AgentCore Memory ARN | -| `/inference-api/memory-id` | InferenceApiStack | runtime-provisioner, AppApiStack | Yes | AgentCore Memory ID | -| `/inference-api/code-interpreter-id` | InferenceApiStack | runtime-provisioner | Yes | Code Interpreter ID | -| `/inference-api/code-interpreter-arn` | InferenceApiStack | AppApiStack | Yes | Code Interpreter ARN | -| `/inference-api/browser-id` | InferenceApiStack | runtime-provisioner | Yes | Browser ID | -| `/inference-api/browser-arn` | InferenceApiStack | AppApiStack | Yes | Browser ARN | -| `/gateway/url` | GatewayStack | runtime-provisioner | Yes | Gateway URL for SigV4 authenticated invocation | -| `/gateway/id` | GatewayStack | runtime-provisioner | Yes | Gateway identifier | -| `/network/vpc-id` | InfrastructureStack | AppApiStack, InferenceApiStack, GatewayStack | Yes | VPC ID for all services | -| `/network/vpc-cidr` | InfrastructureStack | AppApiStack, GatewayStack | Yes | VPC CIDR block | -| `/network/private-subnet-ids` | InfrastructureStack | AppApiStack, InferenceApiStack | Yes | Comma-separated private subnet IDs | -| `/network/public-subnet-ids` | InfrastructureStack | GatewayStack | Yes | Comma-separated public subnet IDs | -| `/network/availability-zones` | InfrastructureStack | AppApiStack | Yes | Comma-separated AZ list | -| `/network/alb-arn` | InfrastructureStack | AppApiStack | Yes | Application Load Balancer ARN | -| `/network/alb-dns-name` | InfrastructureStack | AppApiStack | Yes | ALB DNS name | -| `/network/alb-url` | InfrastructureStack | FrontendStack, runtime-provisioner | Yes | Full ALB URL (http/https) | -| `/network/alb-listener-arn` | InfrastructureStack | AppApiStack | Yes | Primary ALB listener ARN | -| `/network/alb-security-group-id` | InfrastructureStack | AppApiStack | Yes | ALB security group ID | -| `/network/ecs-cluster-name` | InfrastructureStack | AppApiStack, InferenceApiStack | Yes | ECS cluster name | -| `/network/ecs-cluster-arn` | InfrastructureStack | AppApiStack, InferenceApiStack | Yes | ECS cluster ARN | -| `/oauth/callback-url` | InfrastructureStack | runtime-provisioner | Yes | OAuth callback URL for auth flows | -| `/oauth/providers-table-name` | InfrastructureStack | AppApiStack, InferenceApiStack, runtime-provisioner | Yes | OAuth providers table | -| `/oauth/providers-table-arn` | InfrastructureStack | AppApiStack, InferenceApiStack | Yes | OAuth providers table ARN | -| `/oauth/user-tokens-table-name` | InfrastructureStack | AppApiStack, InferenceApiStack, runtime-provisioner | Yes | OAuth user tokens table | -| `/oauth/user-tokens-table-arn` | InfrastructureStack | AppApiStack, InferenceApiStack | Yes | OAuth user tokens table ARN | -| `/oauth/token-encryption-key-arn` | InfrastructureStack | AppApiStack, InferenceApiStack, runtime-provisioner | Yes | KMS key for token encryption | -| `/oauth/client-secrets-arn` | InfrastructureStack | AppApiStack, InferenceApiStack, runtime-provisioner | Yes | Secrets Manager ARN for OAuth secrets | -| `/users/users-table-name` | InfrastructureStack | AppApiStack, InferenceApiStack, runtime-provisioner | Yes | Users table name | -| `/users/users-table-arn` | InfrastructureStack | AppApiStack, InferenceApiStack | Yes | Users table ARN | -| `/rbac/app-roles-table-name` | InfrastructureStack | AppApiStack, InferenceApiStack, runtime-provisioner | Yes | AppRoles table (RBAC + tool catalog) | -| `/rbac/app-roles-table-arn` | InfrastructureStack | AppApiStack, InferenceApiStack | Yes | AppRoles table ARN | -| `/auth/oidc-state-table-name` | InfrastructureStack | AppApiStack, runtime-provisioner | Yes | OIDC state table for distributed auth | -| `/auth/oidc-state-table-arn` | InfrastructureStack | AppApiStack | Yes | OIDC state table ARN | -| `/auth/secret-arn` | InfrastructureStack | AppApiStack | Yes | Authentication secret ARN | -| `/auth/secret-name` | InfrastructureStack | AppApiStack | Yes | Authentication secret name | -| `/rag/assistants-table-name` | RagIngestionStack | AppApiStack, InferenceApiStack, runtime-provisioner | Yes | RAG assistants table | -| `/rag/assistants-table-arn` | RagIngestionStack | AppApiStack, InferenceApiStack | Yes | RAG assistants table ARN | -| `/rag/vector-bucket-name` | RagIngestionStack | AppApiStack, InferenceApiStack, runtime-provisioner | Yes | S3 vector store bucket | -| `/rag/vector-index-name` | RagIngestionStack | AppApiStack, InferenceApiStack, runtime-provisioner | Yes | S3 vector store index name | -| `/frontend/url` | FrontendStack | runtime-provisioner | Yes | Frontend website URL | -| `/frontend/cors-origins` | FrontendStack | runtime-provisioner | Yes | Comma-separated CORS origins | -| `/frontend/distribution-id` | FrontendStack | deployment scripts | Yes | CloudFront distribution ID | -| `/frontend/bucket-name` | FrontendStack | deployment scripts | Yes | S3 bucket name for assets | -| `/api-keys/tavily-api-key` | Manual (admin) | runtime-provisioner | No | Tavily search API key (optional) | -| `/api-keys/nova-act-api-key` | Manual (admin) | runtime-provisioner | No | Nova Act API key (optional) | - -### Parameter Categories - -Parameters are organized into hierarchical categories for easy discovery and management: - -- **`/network/`** - VPC, subnets, ALB, ECS cluster resources -- **`/inference-api/`** - AgentCore Runtime, Memory, Code Interpreter, Browser -- **`/gateway/`** - AgentCore Gateway for MCP tools -- **`/oauth/`** - OAuth providers, tokens, encryption keys -- **`/users/`** - User management tables -- **`/rbac/`** - Role-based access control tables -- **`/auth/`** - Authentication secrets and OIDC state -- **`/rag/`** - RAG assistants and vector storage -- **`/frontend/`** - CloudFront distribution and CORS configuration -- **`/api-keys/`** - Optional external service API keys (manually created) - -### Stack Deployment Order - -The parameter dependency matrix enforces this deployment order: - -1. **InfrastructureStack** (Foundation) - - Exports: VPC, ALB, ECS Cluster, DynamoDB tables, OAuth resources - - Dependencies: None - -2. **RagIngestionStack** (Data Layer) - - Exports: RAG assistants table, vector storage - - Dependencies: InfrastructureStack - -3. **InferenceApiStack** (AgentCore Resources) - - Exports: Memory, Code Interpreter, Browser, Runtime role, ECR URI - - Dependencies: InfrastructureStack, RagIngestionStack - -4. **GatewayStack** (MCP Tools) - - Exports: Gateway URL, Gateway ID - - Dependencies: InfrastructureStack - -5. **AppApiStack** (Application Backend) - - Exports: Application-specific tables and buckets - - Dependencies: InfrastructureStack, InferenceApiStack, GatewayStack, RagIngestionStack - -6. **FrontendStack** (CloudFront + S3) - - Exports: Distribution ID, Frontend URL, CORS origins - - Dependencies: InfrastructureStack, AppApiStack - -### Optional Parameters - -The following parameters are NOT created by CDK stacks and must be manually created by administrators when needed: - -- **`/api-keys/tavily-api-key`** - Tavily search API key for web search capabilities -- **`/api-keys/nova-act-api-key`** - Nova Act API key for browser automation - -These parameters are handled gracefully by the runtime-provisioner Lambda using the `get_optional_parameter()` function, which returns `None` if the parameter doesn't exist. - -To create optional parameters manually: - -```bash -# Tavily API key -aws ssm put-parameter \ - --name "/${PROJECT_PREFIX}/api-keys/tavily-api-key" \ - --value "YOUR_TAVILY_API_KEY" \ - --type "SecureString" \ - --description "Tavily search API key for web search capabilities" - -# Nova Act API key -aws ssm put-parameter \ - --name "/${PROJECT_PREFIX}/api-keys/nova-act-api-key" \ - --value "YOUR_NOVA_ACT_API_KEY" \ - --type "SecureString" \ - --description "Nova Act API key for browser automation" -``` - - -## Correctness Properties - -*A property is a characteristic or behavior that should hold true across all valid executions of a system—essentially, a formal statement about what the system should do. Properties serve as the bridge between human-readable specifications and machine-verifiable correctness guarantees.* - -### Property 1: Parameter Naming Convention Compliance - -*For any* SSM parameter exported by CDK stacks, the parameter name should follow the hierarchical pattern `/${projectPrefix}/{category}/{resource-name}` where category is one of: `network`, `inference-api`, `gateway`, `frontend`, `oauth`, `api-keys`, `users`, `rbac`, `rag`, `quota`, `cost-tracking`, `file-upload`, `auth`, `lambda`, or `sns`. - -**Validates: Requirements 8.1, 8.2, 8.3, 8.4, 8.5, 8.6, 8.7** - -### Property 2: OAuth Callback URL Format - -*For any* OAuth callback URL parameter value, the URL should match the pattern `{base_url}/auth/callback` where base_url is either a custom domain (https://{domain}) or an ALB URL. - -**Validates: Requirements 7.4** - -## Error Handling - -### Missing Optional Parameters - -The runtime-provisioner Lambda function must handle missing optional API key parameters gracefully: - -```python -def get_optional_parameter(parameter_name: str) -> Optional[str]: - """ - Fetch an optional SSM parameter, returning None if it doesn't exist. - - Args: - parameter_name: Full SSM parameter path - - Returns: - Parameter value if it exists, None otherwise - """ - try: - response = ssm_client.get_parameter( - Name=parameter_name, - WithDecryption=True - ) - return response['Parameter']['Value'] - except ssm_client.exceptions.ParameterNotFound: - logger.info(f"Optional parameter {parameter_name} not found, skipping") - return None - except Exception as e: - logger.error(f"Error fetching parameter {parameter_name}: {e}") - raise -``` - -### Missing Required Parameters - -For required parameters, the Lambda function should fail fast with a clear error message: - -```python -def get_required_parameter(parameter_name: str) -> str: - """ - Fetch a required SSM parameter, raising an exception if it doesn't exist. - - Args: - parameter_name: Full SSM parameter path - - Returns: - Parameter value - - Raises: - ParameterNotFound: If the required parameter doesn't exist - Exception: For other SSM errors - """ - try: - response = ssm_client.get_parameter( - Name=parameter_name, - WithDecryption=True - ) - return response['Parameter']['Value'] - except ssm_client.exceptions.ParameterNotFound: - logger.error(f"Required parameter {parameter_name} not found") - raise - except Exception as e: - logger.error(f"Error fetching parameter {parameter_name}: {e}") - raise -``` - -### CDK Deployment Failures - -If SSM parameter export fails during CDK deployment: - -1. CloudFormation will roll back the stack -2. The deployment will fail with a clear error message -3. Existing parameters will remain unchanged -4. No partial state will be left in SSM Parameter Store - -### Parameter Value Validation - -The runtime-provisioner should validate parameter values before using them: - -```python -def validate_url(url: str, parameter_name: str) -> None: - """ - Validate that a URL parameter has the correct format. - - Args: - url: URL string to validate - parameter_name: Parameter name for error messages - - Raises: - ValueError: If URL format is invalid - """ - if not url.startswith(('http://', 'https://')): - raise ValueError( - f"Invalid URL format for {parameter_name}: {url}. " - f"Must start with http:// or https://" - ) - - if not url.strip(): - raise ValueError(f"Empty URL value for {parameter_name}") -``` - -## Testing Strategy - -### Unit Tests - -Unit tests will verify specific CDK stack configurations and parameter exports: - -**Test: InferenceApiStack exports ECR repository URI** -```typescript -test('InferenceApiStack exports ECR repository URI parameter', () => { - const app = new cdk.App(); - const stack = new InferenceApiStack(app, 'TestStack', { - config: testConfig, - }); - - const template = Template.fromStack(stack); - - template.hasResourceProperties('AWS::SSM::Parameter', { - Name: '/test-prefix/inference-api/ecr-repository-uri', - Type: 'String', - Description: Match.stringLikeRegexp('ECR.*URI'), - }); -}); -``` - -**Test: InfrastructureStack exports OAuth callback URL** -```typescript -test('InfrastructureStack exports OAuth callback URL parameter', () => { - const app = new cdk.App(); - const stack = new InfrastructureStack(app, 'TestStack', { - config: testConfig, - }); - - const template = Template.fromStack(stack); - - template.hasResourceProperties('AWS::SSM::Parameter', { - Name: '/test-prefix/oauth/callback-url', - Type: 'String', - Description: Match.stringLikeRegexp('OAuth.*callback'), - }); -}); -``` - -**Test: FrontendStack exports CORS origins** -```typescript -test('FrontendStack exports CORS origins parameter', () => { - const app = new cdk.App(); - const stack = new FrontendStack(app, 'TestStack', { - config: testConfig, - }); - - const template = Template.fromStack(stack); - - template.hasResourceProperties('AWS::SSM::Parameter', { - Name: '/test-prefix/frontend/cors-origins', - Type: 'String', - Description: Match.stringLikeRegexp('CORS.*origins'), - }); -}); -``` - -**Test: OAuth callback URL uses custom domain when configured** -```typescript -test('OAuth callback URL uses custom domain when configured', () => { - const app = new cdk.App(); - const configWithDomain = { - ...testConfig, - frontend: { - ...testConfig.frontend, - domainName: 'app.example.com', - }, - }; - - const stack = new InfrastructureStack(app, 'TestStack', { - config: configWithDomain, - }); - - const template = Template.fromStack(stack); - - // Verify the parameter value contains the custom domain - template.hasResourceProperties('AWS::SSM::Parameter', { - Name: '/test-prefix/oauth/callback-url', - Value: Match.stringLikeRegexp('https://app\\.example\\.com/auth/callback'), - }); -}); -``` - -**Test: OAuth callback URL uses ALB URL when no custom domain** -```typescript -test('OAuth callback URL uses ALB URL when no custom domain', () => { - const app = new cdk.App(); - const configWithoutDomain = { - ...testConfig, - frontend: { - ...testConfig.frontend, - domainName: undefined, - }, - }; - - const stack = new InfrastructureStack(app, 'TestStack', { - config: configWithoutDomain, - }); - - const template = Template.fromStack(stack); - - // Verify the parameter value uses ALB URL - template.hasResourceProperties('AWS::SSM::Parameter', { - Name: '/test-prefix/oauth/callback-url', - Value: Match.stringLikeRegexp('/auth/callback$'), - }); -}); -``` - -**Test: Runtime provisioner handles missing optional parameters** -```python -def test_get_optional_parameter_not_found(): - """Test that get_optional_parameter returns None for missing parameters.""" - with patch('boto3.client') as mock_client: - mock_ssm = MagicMock() - mock_ssm.get_parameter.side_effect = ClientError( - {'Error': {'Code': 'ParameterNotFound'}}, - 'GetParameter' - ) - mock_client.return_value = mock_ssm - - result = get_optional_parameter('/test/api-keys/tavily-api-key') - - assert result is None - mock_ssm.get_parameter.assert_called_once() -``` - -**Test: Runtime provisioner fails on missing required parameters** -```python -def test_get_required_parameter_not_found(): - """Test that get_required_parameter raises exception for missing parameters.""" - with patch('boto3.client') as mock_client: - mock_ssm = MagicMock() - mock_ssm.get_parameter.side_effect = ClientError( - {'Error': {'Code': 'ParameterNotFound'}}, - 'GetParameter' - ) - mock_client.return_value = mock_ssm - - with pytest.raises(ClientError): - get_required_parameter('/test/inference-api/memory-id') -``` - -### Integration Tests - -Integration tests will verify end-to-end parameter flow after deployment: - -**Test: Runtime provisioner can fetch all required parameters** -```python -def test_runtime_provisioner_fetches_all_parameters(): - """ - Integration test: Deploy stacks and verify runtime provisioner - can fetch all required SSM parameters. - """ - # This test requires actual AWS deployment - # Run in CI/CD pipeline after stack deployment - - required_parameters = [ - f'/{PROJECT_PREFIX}/inference-api/image-tag', - f'/{PROJECT_PREFIX}/inference-api/ecr-repository-uri', - f'/{PROJECT_PREFIX}/inference-api/runtime-execution-role-arn', - f'/{PROJECT_PREFIX}/inference-api/memory-arn', - f'/{PROJECT_PREFIX}/inference-api/memory-id', - f'/{PROJECT_PREFIX}/inference-api/code-interpreter-id', - f'/{PROJECT_PREFIX}/inference-api/browser-id', - f'/{PROJECT_PREFIX}/gateway/url', - f'/{PROJECT_PREFIX}/gateway/id', - f'/{PROJECT_PREFIX}/network/alb-url', - f'/{PROJECT_PREFIX}/oauth/callback-url', - f'/{PROJECT_PREFIX}/frontend/url', - f'/{PROJECT_PREFIX}/frontend/cors-origins', - ] - - ssm_client = boto3.client('ssm') - - for param_name in required_parameters: - response = ssm_client.get_parameter(Name=param_name) - assert response['Parameter']['Value'], f"Parameter {param_name} is empty" - print(f"✓ {param_name}: {response['Parameter']['Value']}") -``` - -**Test: All parameters follow naming convention** -```python -def test_all_parameters_follow_naming_convention(): - """ - Integration test: Verify all exported parameters follow the - hierarchical naming convention. - """ - ssm_client = boto3.client('ssm') - - # Get all parameters with project prefix - paginator = ssm_client.get_paginator('describe_parameters') - parameters = [] - - for page in paginator.paginate( - ParameterFilters=[ - { - 'Key': 'Name', - 'Option': 'BeginsWith', - 'Values': [f'/{PROJECT_PREFIX}/'] - } - ] - ): - parameters.extend(page['Parameters']) - - # Validate naming convention - valid_categories = { - 'network', 'inference-api', 'gateway', 'frontend', 'oauth', - 'api-keys', 'users', 'rbac', 'rag', 'quota', 'cost-tracking', - 'file-upload', 'auth', 'lambda', 'sns' - } - - pattern = re.compile(rf'^/{PROJECT_PREFIX}/([^/]+)/([^/]+)$') - - for param in parameters: - name = param['Name'] - match = pattern.match(name) - - assert match, f"Parameter {name} doesn't follow naming convention" - - category = match.group(1) - assert category in valid_categories, \ - f"Parameter {name} uses invalid category: {category}" - - print(f"✓ {name} follows naming convention") -``` - -### Property-Based Tests - -Property-based tests will verify universal properties across all parameter configurations: - -**Property Test: Parameter naming convention** -```python -from hypothesis import given, strategies as st - -@given( - category=st.sampled_from([ - 'network', 'inference-api', 'gateway', 'frontend', 'oauth', - 'api-keys', 'users', 'rbac', 'rag', 'quota', 'cost-tracking', - 'file-upload', 'auth', 'lambda', 'sns' - ]), - resource_name=st.text( - alphabet=st.characters(whitelist_categories=('Ll', 'Nd'), whitelist_characters='-'), - min_size=1, - max_size=50 - ).filter(lambda x: x and not x.startswith('-') and not x.endswith('-')) -) -def test_parameter_naming_convention_property(category: str, resource_name: str): - """ - Property: For any valid category and resource name, the constructed - parameter path should follow the hierarchical naming convention. - - Feature: ssm-parameters-audit, Property 1: Parameter Naming Convention Compliance - """ - project_prefix = 'test-prefix' - param_name = f'/{project_prefix}/{category}/{resource_name}' - - # Verify pattern matches - pattern = re.compile(rf'^/{project_prefix}/([^/]+)/([^/]+)$') - match = pattern.match(param_name) - - assert match is not None, f"Parameter {param_name} doesn't match pattern" - assert match.group(1) == category - assert match.group(2) == resource_name -``` - -**Property Test: OAuth callback URL format** -```python -from hypothesis import given, strategies as st - -@given( - base_url=st.one_of( - st.builds( - lambda domain: f'https://{domain}', - st.from_regex(r'[a-z0-9-]+\.[a-z]{2,}', fullmatch=True) - ), - st.builds( - lambda alb: f'http://{alb}.elb.amazonaws.com', - st.from_regex(r'alb-[a-z0-9]+', fullmatch=True) - ) - ) -) -def test_oauth_callback_url_format_property(base_url: str): - """ - Property: For any valid base URL (custom domain or ALB URL), the OAuth - callback URL should follow the format {base_url}/auth/callback. - - Feature: ssm-parameters-audit, Property 2: OAuth Callback URL Format - """ - callback_url = f'{base_url}/auth/callback' - - # Verify format - assert callback_url.endswith('/auth/callback') - assert callback_url.startswith(('http://', 'https://')) - - # Verify base URL is preserved - assert callback_url.startswith(base_url) -``` - -### Manual Testing Checklist - -After deployment, manually verify: - -- [ ] All required SSM parameters exist in Parameter Store -- [ ] Parameter values are correct (not empty or placeholder values) -- [ ] OAuth callback URL matches expected format -- [ ] Frontend CORS origins parameter contains correct domain(s) -- [ ] ECR repository URI parameter contains valid repository URI -- [ ] Runtime provisioner Lambda can successfully fetch all parameters -- [ ] Runtime provisioner Lambda handles missing optional parameters gracefully -- [ ] CloudFormation outputs show all expected parameter names - -### Testing Configuration - -**Unit Tests**: -- Framework: Jest (TypeScript CDK tests), pytest (Python Lambda tests) -- Run frequency: On every commit -- Coverage target: 80% for new code - -**Integration Tests**: -- Framework: pytest with boto3 -- Run frequency: After deployment to dev/staging -- Requires: Actual AWS environment with deployed stacks - -**Property-Based Tests**: -- Framework: Hypothesis (Python) -- Iterations: 100 per property test -- Run frequency: On every commit -- Focus: Universal properties that hold for all inputs diff --git a/.kiro/specs/ssm-parameters-audit/requirements.md b/.kiro/specs/ssm-parameters-audit/requirements.md deleted file mode 100644 index 8d30d800..00000000 --- a/.kiro/specs/ssm-parameters-audit/requirements.md +++ /dev/null @@ -1,121 +0,0 @@ -# Requirements Document: SSM Parameters Audit - -## Introduction - -The runtime-provisioner Lambda function requires access to multiple SSM parameters across different CDK stacks to dynamically create AgentCore Runtimes for authentication providers. Currently, some required SSM parameters are missing from the CDK stack definitions, which will cause the Lambda function to fail when attempting to fetch these parameters. This feature ensures all required SSM parameters are properly exported by their respective CDK stacks. - -## Glossary - -- **SSM Parameter Store**: AWS Systems Manager Parameter Store, a secure hierarchical storage for configuration data -- **Runtime_Provisioner**: Lambda function that creates AgentCore Runtimes when authentication providers are added -- **CDK_Stack**: AWS Cloud Development Kit infrastructure-as-code stack definition -- **Parameter_Path**: Hierarchical naming convention for SSM parameters (e.g., `/${projectPrefix}/category/resource-name`) -- **InferenceApiStack**: CDK stack that creates AgentCore Runtime shared resources (Memory, Code Interpreter, Browser) -- **GatewayStack**: CDK stack that creates AgentCore Gateway and MCP tools -- **AppApiStack**: CDK stack that creates the main application API Fargate service -- **FrontendStack**: CDK stack that creates CloudFront distribution and S3 bucket for frontend assets -- **ECR_Repository**: Elastic Container Registry repository containing Docker images - -## Requirements - -### Requirement 1: Audit Existing SSM Parameters - -**User Story:** As a DevOps engineer, I want to verify which SSM parameters already exist in CDK stacks, so that I know which parameters need to be added. - -#### Acceptance Criteria - -1. WHEN reviewing InferenceApiStack, THE System SHALL identify all SSM parameters currently exported -2. WHEN reviewing GatewayStack, THE System SHALL identify all SSM parameters currently exported -3. WHEN reviewing AppApiStack, THE System SHALL identify all SSM parameters currently exported -4. WHEN reviewing FrontendStack, THE System SHALL identify all SSM parameters currently exported -5. WHEN comparing against runtime-provisioner requirements, THE System SHALL produce a list of missing parameters - -### Requirement 2: Add Missing Inference API Parameters - -**User Story:** As a runtime provisioner, I want to access inference API configuration via SSM parameters, so that I can create AgentCore Runtimes with the correct settings. - -#### Acceptance Criteria - -1. WHEN InferenceApiStack deploys, THE System SHALL export `/${projectPrefix}/inference-api/ecr-repository-uri` parameter with the ECR repository URI value -2. WHEN InferenceApiStack deploys, THE System SHALL export `/${projectPrefix}/inference-api/image-tag` parameter (already exists - verify only) -3. WHEN InferenceApiStack deploys, THE System SHALL export `/${projectPrefix}/inference-api/runtime-execution-role-arn` parameter (already exists - verify only) -4. WHEN InferenceApiStack deploys, THE System SHALL export `/${projectPrefix}/inference-api/memory-arn` parameter (already exists - verify only) -5. WHEN InferenceApiStack deploys, THE System SHALL export `/${projectPrefix}/inference-api/memory-id` parameter (already exists - verify only) -6. WHEN InferenceApiStack deploys, THE System SHALL export `/${projectPrefix}/inference-api/code-interpreter-id` parameter (already exists - verify only) -7. WHEN InferenceApiStack deploys, THE System SHALL export `/${projectPrefix}/inference-api/browser-id` parameter (already exists - verify only) - -### Requirement 3: Add Missing Gateway Parameters - -**User Story:** As a runtime provisioner, I want to access gateway configuration via SSM parameters, so that I can configure AgentCore Runtimes to use the correct gateway endpoint. - -#### Acceptance Criteria - -1. WHEN GatewayStack deploys, THE System SHALL export `/${projectPrefix}/gateway/url` parameter (already exists - verify only) -2. WHEN GatewayStack deploys, THE System SHALL export `/${projectPrefix}/gateway/id` parameter (already exists - verify only) - -### Requirement 4: Add Missing App API Parameters - -**User Story:** As a runtime provisioner, I want to access app API configuration via SSM parameters, so that I can configure OAuth callback URLs correctly. - -#### Acceptance Criteria - -1. WHEN InfrastructureStack deploys, THE System SHALL export `/${projectPrefix}/network/alb-url` parameter (already exists - verify only) -2. WHEN AppApiStack needs to reference the app API URL, THE System SHALL import it from `/${projectPrefix}/network/alb-url` parameter - -### Requirement 5: Add Missing Frontend Parameters - -**User Story:** As a runtime provisioner, I want to access frontend configuration via SSM parameters, so that I can configure OAuth redirect URIs correctly. - -#### Acceptance Criteria - -1. WHEN FrontendStack deploys, THE System SHALL export `/${projectPrefix}/frontend/url` parameter (already exists - verify only) -2. WHEN FrontendStack deploys, THE System SHALL export `/${projectPrefix}/frontend/cors-origins` parameter with comma-separated allowed origins -3. WHEN FrontendStack deploys AND a custom domain is configured, THE System SHALL use the custom domain as the frontend URL value -4. WHEN FrontendStack deploys AND no custom domain is configured, THE System SHALL use the CloudFront distribution domain as the frontend URL value - -### Requirement 6: Add Optional API Key Parameters - -**User Story:** As a runtime provisioner, I want to access optional API keys via SSM parameters when they exist, so that I can configure external service integrations. - -#### Acceptance Criteria - -1. WHEN runtime-provisioner attempts to fetch `/${projectPrefix}/api-keys/tavily-api-key`, THE System SHALL return the parameter value if it exists -2. WHEN runtime-provisioner attempts to fetch `/${projectPrefix}/api-keys/tavily-api-key` AND the parameter does not exist, THE System SHALL handle the missing parameter gracefully -3. WHEN runtime-provisioner attempts to fetch `/${projectPrefix}/api-keys/nova-act-api-key`, THE System SHALL return the parameter value if it exists -4. WHEN runtime-provisioner attempts to fetch `/${projectPrefix}/api-keys/nova-act-api-key` AND the parameter does not exist, THE System SHALL handle the missing parameter gracefully - -### Requirement 7: Add OAuth Callback URL Parameter - -**User Story:** As a runtime provisioner, I want to access the OAuth callback URL via SSM parameter, so that I can configure authentication providers correctly. - -#### Acceptance Criteria - -1. WHEN InfrastructureStack deploys, THE System SHALL export `/${projectPrefix}/oauth/callback-url` parameter with the OAuth callback URL value -2. WHEN InfrastructureStack deploys AND a custom domain is configured, THE System SHALL construct the callback URL using the custom domain -3. WHEN InfrastructureStack deploys AND no custom domain is configured, THE System SHALL construct the callback URL using the ALB URL -4. THE OAuth_Callback_URL SHALL follow the format `{base_url}/auth/callback` - -### Requirement 8: Maintain Parameter Naming Consistency - -**User Story:** As a developer, I want SSM parameters to follow consistent naming conventions, so that they are easy to discover and use. - -#### Acceptance Criteria - -1. THE System SHALL use the hierarchical naming pattern `/${projectPrefix}/{category}/{resource-name}` for all parameters -2. WHEN a parameter belongs to network resources, THE System SHALL use the category `network` -3. WHEN a parameter belongs to inference API resources, THE System SHALL use the category `inference-api` -4. WHEN a parameter belongs to gateway resources, THE System SHALL use the category `gateway` -5. WHEN a parameter belongs to frontend resources, THE System SHALL use the category `frontend` -6. WHEN a parameter belongs to OAuth resources, THE System SHALL use the category `oauth` -7. WHEN a parameter belongs to API keys, THE System SHALL use the category `api-keys` - -### Requirement 9: Document Parameter Dependencies - -**User Story:** As a developer, I want to understand which stacks depend on which SSM parameters, so that I can maintain the correct deployment order. - -#### Acceptance Criteria - -1. WHEN documenting SSM parameters, THE System SHALL specify which stack exports each parameter -2. WHEN documenting SSM parameters, THE System SHALL specify which stacks or Lambda functions import each parameter -3. WHEN documenting SSM parameters, THE System SHALL indicate whether each parameter is required or optional -4. THE System SHALL maintain a parameter dependency matrix showing export and import relationships diff --git a/.kiro/specs/ssm-parameters-audit/tasks.md b/.kiro/specs/ssm-parameters-audit/tasks.md deleted file mode 100644 index 5f766174..00000000 --- a/.kiro/specs/ssm-parameters-audit/tasks.md +++ /dev/null @@ -1,110 +0,0 @@ -# Implementation Plan: SSM Parameters Audit - -## Overview - -This implementation plan adds missing SSM parameters to CDK stacks to ensure the runtime-provisioner Lambda function can successfully fetch all required configuration values. The work is organized into discrete tasks that build incrementally, with testing integrated throughout. - -## Tasks - -- [x] 1. Add missing SSM parameter to InferenceApiStack - - Add ECR repository URI parameter export - - Verify existing parameters are still present - - _Requirements: 2.1, 2.2, 2.3, 2.4, 2.5, 2.6, 2.7_ - -- [ ]* 1.1 Write unit test for ECR repository URI parameter export - - **Property 1: Parameter Naming Convention Compliance** - - **Validates: Requirements 2.1, 8.1** - -- [x] 2. Add missing SSM parameter to InfrastructureStack - - Add OAuth callback URL parameter export - - Implement conditional logic for custom domain vs ALB URL - - _Requirements: 7.1, 7.2, 7.3, 7.4_ - -- [ ]* 2.1 Write unit test for OAuth callback URL with custom domain - - Test that callback URL uses custom domain when configured - - **Validates: Requirements 7.2, 7.4** - -- [ ]* 2.2 Write unit test for OAuth callback URL with ALB URL - - Test that callback URL uses ALB URL when no custom domain - - **Validates: Requirements 7.3, 7.4** - -- [ ]* 2.3 Write property test for OAuth callback URL format - - **Property 2: OAuth Callback URL Format** - - **Validates: Requirements 7.4** - -- [x] 3. Add missing SSM parameter to FrontendStack - - Add CORS origins parameter export - - Implement conditional logic for custom domain vs CloudFront domain - - _Requirements: 5.2, 5.3, 5.4_ - -- [ ]* 3.1 Write unit test for CORS origins parameter export - - Test that CORS origins parameter is created - - **Validates: Requirements 5.2** - -- [ ]* 3.2 Write unit test for CORS origins with custom domain - - Test that CORS origins uses custom domain when configured - - **Validates: Requirements 5.3** - -- [ ]* 3.3 Write unit test for CORS origins with CloudFront domain - - Test that CORS origins uses CloudFront domain when no custom domain - - **Validates: Requirements 5.4** - -- [x] 4. Update runtime-provisioner Lambda error handling - - Implement get_optional_parameter function for optional API keys - - Implement get_required_parameter function for required parameters - - Add parameter value validation - - _Requirements: 6.1, 6.2, 6.3, 6.4_ - -- [ ]* 4.1 Write unit test for optional parameter handling - - Test that get_optional_parameter returns None for missing parameters - - **Validates: Requirements 6.2, 6.4** - -- [ ]* 4.2 Write unit test for required parameter handling - - Test that get_required_parameter raises exception for missing parameters - - **Validates: Requirements 6.1, 6.3** - -- [ ]* 4.3 Write unit test for parameter value validation - - Test URL validation logic - - **Validates: Requirements 7.4** - -- [x] 5. Checkpoint - Ensure all tests pass - - Ensure all tests pass, ask the user if questions arise. - -- [x] 6. Create parameter dependency documentation - - Update design document with complete parameter dependency matrix - - Document which stacks export each parameter - - Document which stacks/Lambda functions import each parameter - - Mark parameters as required or optional - - _Requirements: 9.1, 9.2, 9.3, 9.4_ - -- [ ]* 6.1 Write integration test for parameter naming convention - - Test that all deployed parameters follow naming convention - - **Property 1: Parameter Naming Convention Compliance** - - **Validates: Requirements 8.1, 8.2, 8.3, 8.4, 8.5, 8.6, 8.7** - -- [ ]* 6.2 Write integration test for runtime provisioner parameter fetching - - Test that runtime provisioner can fetch all required parameters - - **Validates: Requirements 2.1, 2.2, 2.3, 2.4, 2.5, 2.6, 2.7, 3.1, 3.2, 4.1, 5.1, 5.2, 7.1** - -- [ ]* 6.3 Write property test for parameter naming convention - - **Property 1: Parameter Naming Convention Compliance** - - **Validates: Requirements 8.1, 8.2, 8.3, 8.4, 8.5, 8.6, 8.7** - -- [x] 7. Update CDK deployment scripts - - Verify deployment order is correct (Infrastructure → Inference → Gateway → App → Frontend) - - Update any deployment documentation - - _Requirements: 1.1, 1.2, 1.3, 1.4_ - -- [x] 8. Final checkpoint - Ensure all tests pass - - Ensure all tests pass, ask the user if questions arise. - -## Notes - -- Tasks marked with `*` are optional and can be skipped for faster MVP -- Each task references specific requirements for traceability -- Checkpoints ensure incremental validation -- Property tests validate universal correctness properties -- Unit tests validate specific examples and edge cases -- Integration tests validate end-to-end parameter flow after deployment -- The deployment order must be maintained: InfrastructureStack → InferenceApiStack → GatewayStack → AppApiStack → FrontendStack -- Optional API key parameters (/api-keys/*) are NOT created by CDK - they must be manually created by administrators when needed diff --git a/.kiro/specs/supply-chain-hardening/.config.kiro b/.kiro/specs/supply-chain-hardening/.config.kiro deleted file mode 100644 index 2dadde5c..00000000 --- a/.kiro/specs/supply-chain-hardening/.config.kiro +++ /dev/null @@ -1 +0,0 @@ -{"specId": "68db1284-f73b-49ad-824a-28788c916b5d", "workflowType": "requirements-first", "specType": "feature"} \ No newline at end of file diff --git a/.kiro/specs/supply-chain-hardening/design.md b/.kiro/specs/supply-chain-hardening/design.md deleted file mode 100644 index 45f6eefe..00000000 --- a/.kiro/specs/supply-chain-hardening/design.md +++ /dev/null @@ -1,611 +0,0 @@ -# Design Document: Supply Chain Hardening - -## Overview - -This design addresses 17 supply chain hardening findings across the AgentCore Public Stack's CI/CD infrastructure. The changes span four domains: GitHub Actions workflows (13 YAML files), dependency manifests (`pyproject.toml`, two `package.json` files), Dockerfiles (3 files), and shell scripts (`scripts/`). The goal is to eliminate non-determinism in builds, reduce the blast radius of compromised dependencies, and establish guardrails that prevent regressions. - -All changes are configuration-level — no application code is modified. The implementation is purely additive or substitutive (replacing floating references with pinned ones), so the risk of functional regression is minimal. - -### Key Design Decisions - -1. **SHA pinning with version comments**: Every third-party GitHub Action reference becomes `owner/action@ # vX.Y.Z`. The comment preserves human readability while the SHA provides immutability. -2. **Trivy over Grype for image scanning**: Trivy is chosen because it has a first-party GitHub Action (`aquasecurity/trivy-action`), produces SARIF output natively, and is already widely adopted in the GitHub Actions ecosystem. -3. **Lint-time enforcement over runtime enforcement**: Where possible (e.g., exact version pins), we add CI lint checks that fail fast rather than relying on developers to remember conventions. -4. **Incremental rollout**: Requirements are grouped by priority (HIGH first, then MEDIUM) and can be merged independently. No requirement depends on another being completed first. - -## Architecture - -The supply chain hardening touches the CI/CD layer only. No changes to the application runtime architecture are needed. - -```mermaid -graph TD - subgraph "Source Control" - A[pyproject.toml
== pins] --> B[uv.lock] - C[package.json
exact pins] --> D[package-lock.json] - E[Workflow YAML
SHA-pinned actions] - F[Dockerfiles
digest-pinned bases
versioned apt packages] - end - - subgraph "CI Pipeline" - G[Lint Check
version pin validator] - H[npm ci
lockfile-only installs] - I[uv sync --frozen
lockfile-only installs] - J[Docker Build
deterministic layers] - K[Trivy Scan
vulnerability gate] - L[Smoke Tests
post-deploy health checks] - end - - subgraph "Deployment" - M[ECR Push
scanned images only] - N[CDK Deploy
scoped credentials] - end - - A --> G - C --> G - E --> H - E --> I - J --> K - K -->|pass| M - M --> N - N --> L -``` - -### Affected Files Summary - -| Domain | Files | Requirements | -|--------|-------|-------------| -| GitHub Actions workflows | `.github/workflows/*.yml` (13 files) | 1, 8, 13, 15, 17 | -| Composite action | `.github/actions/configure-aws-credentials/action.yml` | 1 | -| Dependabot config | `.github/dependabot.yml` | 9 | -| Python manifest | `backend/pyproject.toml` | 2, 12 | -| Frontend manifest | `frontend/ai.client/package.json` | 3 | -| Infrastructure manifest | `infrastructure/package.json` | 5 | -| Dockerfiles | `backend/Dockerfile.{app-api,inference-api,rag-ingestion}` | 10 | -| Install scripts | `scripts/common/install-deps.sh`, `scripts/stack-*/install.sh` | 4, 6 | -| New files | `CONTRIBUTING.md`, `.github/ARTIFACT_RETENTION.md` | 11, 14 | -| Smoke test scripts | `scripts/stack-*/smoke-test.sh` (new) | 16 | -| Image scanning | `nightly.yml` track addition | 7 | - -## Components and Interfaces - -### Component 1: GitHub Actions SHA Pinning (Requirements 1, 13) - -**Current state**: All workflows reference actions by mutable tag (e.g., `actions/checkout@v5`, `actions/upload-artifact@v6`, `docker/build-push-action@v7`). The composite action at `.github/actions/configure-aws-credentials/action.yml` internally references `aws-actions/configure-aws-credentials@v6`. - -**Target state**: Every third-party action reference is replaced with its SHA-256 digest plus a version comment: - -```yaml -# Before -- uses: actions/checkout@v5 - -# After -- uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2 -``` - -**Approach**: -- For each action used across all 13 workflow files + 1 composite action, resolve the current tag to its commit SHA using `git ls-remote` or the GitHub API. -- Standardize on a single version of `actions/checkout` across all files (Requirement 13). -- The local composite action (`.github/actions/configure-aws-credentials`) continues to be referenced by relative path — exempt from SHA pinning per Requirement 1.4. -- Third-party actions inside the composite action (`aws-actions/configure-aws-credentials@v6`) are also SHA-pinned. - -**Actions to pin** (deduplicated across all workflows): -- `actions/checkout` -- `actions/cache/restore` -- `actions/cache/save` -- `actions/upload-artifact` -- `actions/download-artifact` -- `docker/setup-buildx-action` -- `docker/build-push-action` -- `aws-actions/configure-aws-credentials` (inside composite action) - -### Component 2: Dependency Version Pinning (Requirements 2, 3, 5) - -**Python (`backend/pyproject.toml`)** — Requirement 2: - -Current state has a mix of exact (`==`) and floor (`>=`) pins. All `>=` pins must become `==`: - -```toml -# Before -"boto3>=1.40.1", -"python-dotenv>=1.0.0", - -# After -"boto3==1.40.1", -"python-dotenv==1.0.0", -``` - -This applies to all sections: `dependencies`, `[project.optional-dependencies].agentcore`, and `[project.optional-dependencies].dev`. After pinning, regenerate `uv.lock` with `uv lock`. - -**Frontend (`frontend/ai.client/package.json`)** — Requirement 3: - -For each dependency, look up the actual resolved version in `package-lock.json` and pin to that exact version. Do NOT simply strip the `^`/`~` prefix — the lockfile may have resolved to a higher version than the floor specified in `package.json`. - -```json -// Before (package.json says ^21.0.0, but lockfile resolved to 21.2.5) -"@angular/core": "^21.0.0", - -// After (use the version from package-lock.json) -"@angular/core": "21.2.5", -``` - -Process: -1. Parse `package-lock.json` to extract the resolved version for each direct dependency -2. Replace the version string in `package.json` with the exact resolved version (no `^`, `~`, or range operators) -3. Run `npm install` to regenerate `package-lock.json` consistent with the new exact pins -4. Verify with `npm ci` that the lockfile is in sync - -**Infrastructure (`infrastructure/package.json`)** — Requirement 5: - -Same approach — read resolved versions from `infrastructure/package-lock.json`: - -```json -// Before (package.json says ^2.235.1, lockfile resolved to e.g. 2.235.1) -"aws-cdk-lib": "^2.235.1", -"aws-cdk": "^2.1033.0", - -// After (use exact versions from package-lock.json, upgrading to latest stable) -"aws-cdk-lib": "2.244.0", -"aws-cdk": "2.1113.0", -``` - -Process: -1. Parse `infrastructure/package-lock.json` to extract resolved versions -2. Replace version strings in `package.json` with exact resolved versions -3. Run `npm install` to regenerate `package-lock.json` -4. Verify with `npm ci` - -### Component 3: Install Script Hardening (Requirements 4, 6) - -**Global tool pinning** — Requirement 4: - -In `scripts/common/install-deps.sh`, the CDK CLI install is unpinned: -```bash -# Before -npm install -g aws-cdk - -# After -npm install -g aws-cdk@2.1113.0 -``` - -Same fix in `scripts/stack-infrastructure/install.sh`. Node.js is already installed from a versioned distribution URL (`setup_20.x`), satisfying Requirement 4.2. - -**npm ci enforcement** — Requirement 6: - -Several install scripts use `npm install` instead of `npm ci`: -- `scripts/stack-app-api/install.sh` — uses `npm install` for infrastructure -- `scripts/stack-infrastructure/install.sh` — uses `npm install` - -Fix: Replace `npm install` with `npm ci` and add a lockfile existence check: - -```bash -if [ ! -f "package-lock.json" ]; then - log_error "package-lock.json not found. Cannot run npm ci." - exit 1 -fi -npm ci -``` - -`scripts/stack-frontend/install.sh` already uses `npm ci` with a lockfile check — this is the reference pattern. - -### Component 4: Container Image Scanning (Requirement 7) - -**Approach**: Instead of adding a hard gate to the per-stack deploy workflows, add image scanning as a new optional track in the nightly build system (`nightly.yml`). This follows the existing track-based architecture where `resolve-tracks` parses comma-separated track tokens into boolean flags. - -**New track token**: `scan-images-` (e.g., `scan-images-develop`, `scan-images-main`) - -When `all` is specified, the scan track runs alongside the existing test/deploy/MV tracks. It can also be triggered independently via `workflow_dispatch`. - -**Track resolution** — add to `resolve-tracks` job in `nightly.yml`: - -```bash -scan-images-*) - run_scan_images=true - scan_images_ref="${token#scan-images-}" - ;; -``` - -And include `scan-images` in the `all` case: -```bash -all) - # ... existing tracks ... - run_scan_images=true - scan_images_ref="develop" - ;; -``` - -**New jobs in `nightly.yml`**: - -1. `scan-images` — builds all three Docker images (app-api, inference-api, rag-ingestion) and runs Trivy against each. This job does NOT block any deploy track. It runs in parallel with the existing test and deploy tracks. - -```yaml -scan-images: - name: Scan Docker Images - runs-on: ubuntu-24.04 - needs: resolve-tracks - if: needs.resolve-tracks.outputs.run_scan_images == 'true' - outputs: - status: ${{ steps.summary.outputs.status }} - duration: ${{ steps.summary.outputs.duration }} - steps: - - name: Checkout code - uses: actions/checkout@ - with: - ref: ${{ needs.resolve-tracks.outputs.scan_images_ref }} - - - name: Build and scan app-api image - run: | - docker build -f backend/Dockerfile.app-api -t app-api:scan . - docker save app-api:scan -o /tmp/app-api.tar - - - name: Trivy scan app-api - uses: aquasecurity/trivy-action@ # v0.28.0 - with: - input: /tmp/app-api.tar - format: 'table' - exit-code: '0' # advisory — does NOT fail the job - severity: 'CRITICAL,HIGH' - output: trivy-app-api.txt - - # Repeat for inference-api and rag-ingestion... - - - name: Upload scan reports - if: always() - uses: actions/upload-artifact@ - with: - name: trivy-scan-reports - path: trivy-*.txt - retention-days: 30 - - - name: Generate summary - id: summary - if: always() - run: | - # Parse Trivy outputs and write to GITHUB_STEP_SUMMARY - # Report counts of CRITICAL/HIGH/MEDIUM findings per image - ... -``` - -**Key design choices**: -- `exit-code: '0'` — the scan is advisory, not a hard gate. Findings appear in the nightly summary and as artifacts, but don't block anything. -- The scan job is added to the `summary` job's `needs` list so results appear in the nightly summary report. -- The `all` track includes scanning by default, so scheduled nightly runs get image scanning automatically. -- Forks that don't set `NIGHTLY_TRACKS` get no scanning (fork-safe default, consistent with existing tracks). - -**Nightly summary integration** — add a row to the summary job: -```bash -if [ "$RUN_SCAN_IMAGES" = "true" ]; then - status="$(map_status "${{ needs.scan-images.result }}")" - ROWS+=("Image Scan|${status}|${{ needs.scan-images.outputs.duration || '0' }}") -fi -``` - -### Component 5: Runner Version Pinning (Requirement 8) - -Replace all `ubuntu-latest` references with `ubuntu-24.04`: - -```yaml -# Before -runs-on: ubuntu-latest - -# After -runs-on: ubuntu-24.04 -``` - -Some jobs already use `ubuntu-24.04-arm` (e.g., `synth-cdk` in app-api, `build-docker` in inference-api). These are already pinned and remain unchanged. - -### Component 6: Dependabot Enhancement (Requirement 9) - -The existing `.github/dependabot.yml` already has a `github-actions` ecosystem entry targeting `develop` with grouped minor/patch updates. This satisfies all three acceptance criteria. The only change needed is to verify the configuration works correctly with SHA-pinned actions (Dependabot natively supports SHA digest bumps for GitHub Actions). - -No file changes required — the current configuration already meets Requirement 9. - -### Component 7: Docker apt-get Pinning (Requirement 10) - -Pin all apt-get packages in the three Dockerfiles to specific versions. The exact versions depend on the base image's package repository. - -**`Dockerfile.app-api` and `Dockerfile.inference-api`** (builder stage): -```dockerfile -# Before -RUN apt-get update && apt-get install -y \ - gcc \ - g++ - -# After -RUN apt-get update && apt-get install -y \ - gcc=12.2.0-14 \ - g++=12.2.0-14 -``` - -**Production stage** (both files): -```dockerfile -# Before -RUN apt-get update && apt-get install -y \ - curl - -# After -RUN apt-get update && apt-get install -y \ - curl=7.88.1-10+deb12u12 -``` - -**`Dockerfile.rag-ingestion`** uses `dnf` (Amazon Linux 2023), not `apt-get`. The same principle applies — pin package versions where the package manager supports it. For `dnf`, version pinning uses `package-version` syntax. Where exact versions are unavailable or impractical (e.g., `mesa-libGL` on AL2023), document the constraint as a comment. - -### Component 8: CONTRIBUTING.md (Requirement 11) - -Create `CONTRIBUTING.md` at the repository root documenting: -- Prerequisites (Node.js 20+, Python 3.13+, Docker, AWS CLI v2, uv) -- Clone and install steps for backend, frontend, and infrastructure -- Environment variable configuration (referencing `backend/src/.env` and `frontend/ai.client/src/environments/`) -- How to run test suites (`uv run pytest`, `npm test`, `npx cdk synth`) -- AWS credential setup for local development - -### Component 9: mypy Version Fix (Requirement 12) - -```toml -# Before -[tool.mypy] -python_version = "3.9" - -# After -[tool.mypy] -python_version = "3.10" -``` - -The `requires-python = ">=3.10"` in `pyproject.toml` means the minimum supported version is 3.10. mypy's `python_version` must match. - -### Component 10: Artifact Retention Policy (Requirement 14) - -Create `.github/ARTIFACT_RETENTION.md` documenting retention periods: - -| Artifact Type | Retention | Rationale | -|--------------|-----------|-----------| -| Docker image tarballs | 1 day | Ephemeral build artifacts, images live in ECR | -| CDK synthesized templates | 7 days | Needed for deploy job, then disposable | -| Test results / coverage | 7 days | Debugging window for failed PRs | -| Deployment outputs (stack outputs) | 30 days | Audit trail for deployments | -| Trivy scan reports | 30 days | Security audit trail | - -Verify all `retention-days` values in workflow files match this policy. Current state already uses 1/7/30 day tiers consistently. - -### Component 11: Frontend cancel-in-progress (Requirement 15) - -After review, the frontend workflow includes a CDK deploy step (`deploy-cdk.sh` for the CloudFront/S3 stack). Cancelling a CDK deploy mid-execution can leave CloudFormation in a `ROLLBACK_IN_PROGRESS` or `UPDATE_ROLLBACK_FAILED` state. Therefore `cancel-in-progress: false` is the correct setting for the frontend workflow as well. - -**No change required.** Requirement 15 is satisfied by documenting the rationale: all workflows that include CDK deploys must retain `cancel-in-progress: false`. - -### Component 12: Post-Deployment Smoke Tests (Requirement 16) - -**Deferred.** Post-deployment smoke tests for the per-stack workflows (app-api, inference-api, frontend) are out of scope for this iteration. The nightly deploy pipeline already has a comprehensive smoke test job. This can be revisited later. - -### Component 13: Secret Scoping (Requirement 17) - -**Current state**: Several workflows define AWS credentials (`AWS_ROLE_ARN`, `AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`) at the workflow-level `env:` block, making them available to all jobs including those that don't need AWS access (e.g., `install`, `build-cdk`, `test-python`, `check-stack-dependencies`). - -**Target state**: Move AWS credential env vars from workflow-level to job-level, only on jobs that actually use AWS (jobs with `configure-aws-credentials` step, ECR push, or CDK deploy). - -Jobs that do NOT need AWS credentials: -- `check-stack-dependencies` -- `install` -- `build-docker` (builds locally, no ECR interaction) -- `build-cdk` -- `build-frontend` -- `test-python` -- `test-frontend` - -Currently, the workflows already define most secrets at the job level (inside `env:` blocks on specific jobs). The workflow-level `env:` only contains non-sensitive config (`CDK_REQUIRE_APPROVAL`, `FORCE_JAVASCRIPT_ACTIONS_TO_NODE24`, `LOAD_ENV_QUIET`). This is already correct for most workflows. We need to audit each workflow and confirm no secrets leak to the workflow-level `env:`. - -## Data Models - -This feature does not introduce new data models. All changes are to configuration files (YAML, TOML, JSON, Dockerfile, shell scripts) and documentation (Markdown). No database schemas, API contracts, or runtime data structures are affected. - -### Configuration File Formats - -**Version pin format** (pyproject.toml): -``` -"package==X.Y.Z" -``` - -**Version pin format** (package.json): -``` -"package": "X.Y.Z" -``` - -**SHA pin format** (GitHub Actions): -``` -uses: owner/action@<40-char-sha> # vX.Y.Z -``` - -**apt-get pin format** (Dockerfile): -``` -package=X.Y.Z-release -``` - - - -## Correctness Properties - -*A property is a characteristic or behavior that should hold true across all valid executions of a system — essentially, a formal statement about what the system should do. Properties serve as the bridge between human-readable specifications and machine-verifiable correctness guarantees.* - -### Property 1: Third-party actions are SHA-pinned with version comments - -*For any* `uses:` reference in any workflow YAML file (`.github/workflows/*.yml`) or composite action YAML, if the reference is to a third-party action (not starting with `./`), then it must match the pattern `owner/action@<40-char-hex-sha> # vX.Y.Z`. - -**Validates: Requirements 1.1** - -### Property 2: All Python dependencies use exact version pins - -*For any* dependency string in any section of `pyproject.toml` (`dependencies`, `[project.optional-dependencies].agentcore`, `[project.optional-dependencies].dev`), the version specifier must use the `==` operator. Strings containing `>=`, `~=`, `>`, `<`, or no version constraint must be rejected. - -**Validates: Requirements 2.1, 2.2, 2.4** - -### Property 3: All npm dependencies use exact version pins - -*For any* dependency entry in the `dependencies` or `devDependencies` sections of `frontend/ai.client/package.json` and `infrastructure/package.json`, the version string must not begin with `^`, `~`, `>`, `<`, or `*`. - -**Validates: Requirements 3.1, 3.2, 5.1, 5.2** - -### Property 4: Global npm installs specify exact versions - -*For any* `npm install -g` command in any shell script under `scripts/`, the package name must include an `@version` suffix (e.g., `aws-cdk@2.1033.0`). - -**Validates: Requirements 4.1, 4.3** - -### Property 5: CI install paths use npm ci with lockfile check - -*For any* shell script under `scripts/` that installs npm dependencies for a project directory, the script must use `npm ci` (not `npm install`) when a `package-lock.json` is present, and must exit non-zero if the lockfile is missing. - -**Validates: Requirements 6.1, 6.2** - -### Property 6: Nightly workflow includes image scanning track - -*For the* nightly workflow (`nightly.yml`), the `resolve-tracks` job must output a `run_scan_images` flag, and there must be a `scan-images` job that runs Trivy against all three Docker images (app-api, inference-api, rag-ingestion) when the flag is true. The scan must use `exit-code: '0'` (advisory mode) and upload reports as artifacts. - -**Validates: Requirements 7.1, 7.4** - -### Property 7: No workflow job uses floating runner aliases - -*For any* `runs-on` value in any job in any workflow YAML file, the value must not contain the string `-latest`. It must specify an explicit OS version (e.g., `ubuntu-24.04`). - -**Validates: Requirements 8.1** - -### Property 8: Dependabot entries target develop with grouped updates - -*For any* ecosystem entry in `.github/dependabot.yml`, the `target-branch` must be `"develop"` and the entry must contain a `groups` section that includes `update-types` covering both `"minor"` and `"patch"`. - -**Validates: Requirements 9.2, 9.3** - -### Property 9: Dockerfile apt-get packages have version pins - -*For any* `apt-get install` command in any Dockerfile, every package name must include a version pin in the format `package=version` (for apt-get) or `package-version` (for dnf), unless accompanied by a comment documenting why the pin is omitted. - -**Validates: Requirements 10.1, 10.2** - -### Property 10: Consistent checkout action SHA across all workflows - -*For any* two workflow YAML files that reference `actions/checkout`, the SHA digest used must be identical. - -**Validates: Requirements 13.1** - -### Property 11: Consistent artifact retention per artifact type - -*For any* two `upload-artifact` steps across all workflow files that upload the same category of artifact (Docker image, CDK synth, test results, deployment outputs), the `retention-days` value must be identical. - -**Validates: Requirements 14.2** - -### Property 12: All deployment workflows retain cancel-in-progress false - -*For any* workflow that contains a CDK deploy job (including frontend, which deploys the CloudFront/S3 stack via CDK), the workflow's `concurrency.cancel-in-progress` must be `false`. - -**Validates: Requirements 15.2** - -### Property 13: Deployment workflows have post-deployment smoke tests - -**Deferred.** This property is out of scope for this iteration. The nightly deploy pipeline already includes a smoke test job. - -**Validates: Requirements 16.1** - -### Property 14: AWS credentials scoped to AWS-using jobs only - -*For any* job in any workflow, the job's `env` block contains AWS credential variables (`AWS_ROLE_ARN`, `AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`) if and only if the job contains a step that interacts with AWS (e.g., `configure-aws-credentials`, ECR login, CDK deploy). No AWS credentials may appear in the workflow-level `env` block. - -**Validates: Requirements 17.1, 17.2** - -## Error Handling - -### Lint Check Failures (Requirements 2, 3, 4, 5) - -When the version pin validator detects a non-exact pin: -- The CI job exits with a non-zero status code. -- The error message identifies the file, dependency name, and the offending version specifier. -- The message suggests the correct format (e.g., `"boto3==1.40.1"` instead of `"boto3>=1.40.1"`). - -### Image Scan Results (Requirement 7) - -When Trivy detects CRITICAL or HIGH vulnerabilities in the nightly scan track: -- The vulnerability table is printed to stdout (visible in the job log). -- The full report is uploaded as an artifact with 30-day retention. -- The scan job completes with success regardless of findings (`exit-code: '0'` — advisory mode). -- Results appear in the nightly summary report for visibility. -- No deploy or push is blocked — the scan is informational only. - -### Smoke Test Failures (Requirement 16) - -**Deferred.** Post-deployment smoke tests for per-stack workflows are out of scope for this iteration. - -### Missing Lockfile (Requirement 6) - -When `package-lock.json` is missing and `npm ci` is attempted: -- The install script exits immediately with code 1. -- The error message states: `"package-lock.json not found. Cannot run npm ci. Commit the lockfile first."` - -### Unavailable apt-get Package Versions (Requirement 10) - -When a pinned apt-get package version is not available in the base image's repository: -- The Docker build fails at the `apt-get install` step. -- Resolution: Update the version pin to match the available version in the base image, or document the constraint as a comment if exact pinning is impractical (e.g., AL2023 dnf packages). - -## Testing Strategy - -### Dual Testing Approach - -This feature uses both unit tests (specific examples) and property-based tests (universal properties) for comprehensive coverage. - -**Unit tests** verify: -- Specific examples: e.g., `CONTRIBUTING.md` exists and contains required sections (Req 11) -- Edge cases: e.g., missing lockfile causes non-zero exit (Req 6.3) -- Configuration examples: e.g., Trivy step has `exit-code: '1'` (Req 7.2), mypy version matches requires-python (Req 12.1) -- Specific file checks: e.g., frontend workflow has `cancel-in-progress: true` (Req 15.1) - -**Property-based tests** verify: -- Universal properties across all workflow files, dependency manifests, Dockerfiles, and scripts -- Each property test generates or enumerates the relevant files and checks the invariant holds for every instance - -### Property-Based Testing Configuration - -- **Library**: Python `hypothesis` (already in dev dependencies) for property-based testing, combined with `pytest` -- **Minimum iterations**: 100 per property test (where randomization applies) -- **Tag format**: Each test is tagged with a comment: `# Feature: supply-chain-hardening, Property {N}: {title}` -- **Each correctness property maps to exactly one property-based test** - -Since most properties in this feature are about static file analysis (parsing YAML/TOML/JSON/Dockerfile/shell files and checking structural invariants), the property tests will enumerate all relevant files and check the invariant holds for every entry. For properties where the input space is finite (e.g., all workflow files), the test exhaustively checks every instance rather than sampling. - -### Test File Organization - -``` -backend/tests/supply_chain/ -├── test_action_pinning.py # Properties 1, 10 -├── test_dependency_pinning.py # Properties 2, 3 -├── test_script_hardening.py # Properties 4, 5 -├── test_docker_scanning.py # Property 6 (nightly scan track) -├── test_runner_pinning.py # Property 7 -├── test_dependabot_config.py # Property 8 -├── test_dockerfile_pinning.py # Property 9 -├── test_artifact_retention.py # Property 11 -├── test_concurrency_config.py # Property 12 -├── test_smoke_tests.py # Property 13 -├── test_secret_scoping.py # Property 14 -└── test_documentation.py # Unit tests for Reqs 11, 12, 14 -``` - -### Example Test Patterns - -**Property test** (Property 1 — SHA pinning): -```python -# Feature: supply-chain-hardening, Property 1: Third-party actions are SHA-pinned -import re, yaml, glob - -def test_all_third_party_actions_are_sha_pinned(): - sha_pattern = re.compile(r'^[\w-]+/[\w-]+@[0-9a-f]{40}\s+#\s+v[\d.]+') - for wf in glob.glob('.github/workflows/*.yml'): - # parse YAML, find all uses: values, check pattern - ... -``` - -**Unit test** (Requirement 12 — mypy version): -```python -def test_mypy_version_matches_requires_python(): - # parse pyproject.toml - # extract requires-python minimum version - # extract [tool.mypy].python_version - # assert they match - ... -``` diff --git a/.kiro/specs/supply-chain-hardening/requirements.md b/.kiro/specs/supply-chain-hardening/requirements.md deleted file mode 100644 index b71bcdcf..00000000 --- a/.kiro/specs/supply-chain-hardening/requirements.md +++ /dev/null @@ -1,231 +0,0 @@ -# Requirements Document - -## Introduction - -This specification addresses supply chain hardening, build reproducibility, and CI/CD security across the AgentCore Public Stack. The audit identified 17 issues spanning GitHub Actions workflows, Python/npm dependency management, Docker builds, and pipeline configuration. This document formalizes each finding into testable, EARS-compliant requirements organized by priority. - -**Scope**: GitHub Actions workflows, dependency manifests (`pyproject.toml`, `package.json`), Dockerfiles, shell scripts, and CI/CD pipeline configuration. - -**Out of Scope**: Application-level security (XSS, injection), RBAC logic, runtime secrets rotation. - -## Glossary - -- **CI_Pipeline**: The set of GitHub Actions workflows that build, test, and deploy the AgentCore Public Stack -- **Dependency_Manager**: The tools responsible for resolving and installing packages (npm, uv/pip) -- **Workflow_Runner**: The GitHub Actions runner environment executing CI/CD jobs -- **Docker_Builder**: The multi-stage Docker build process producing container images for deployment -- **Dependabot**: GitHub's automated dependency update service configured via `.github/dependabot.yml` -- **Image_Scanner**: A container vulnerability scanning tool (e.g., Trivy, Grype, or ECR native scanning) -- **Install_Script**: Shell scripts in `scripts/` that install dependencies for CI/CD and local development -- **CDK_Deployer**: The AWS CDK synthesis and deployment pipeline for infrastructure stacks -- **SHA_Digest**: An immutable, content-addressable hash identifying a specific version of a GitHub Action or container image -- **Lockfile**: A file (`uv.lock`, `package-lock.json`) that records exact resolved dependency versions - -## Requirements - -### Requirement 1: Pin GitHub Actions to SHA Digests - -**User Story:** As a DevOps engineer, I want all GitHub Actions references pinned to immutable SHA digests, so that a compromised or force-pushed tag cannot inject malicious code into the CI pipeline. - -**Priority:** HIGH - -#### Acceptance Criteria - -1. THE CI_Pipeline SHALL reference every third-party GitHub Action using a full SHA-256 digest followed by a comment indicating the human-readable version tag -2. WHEN a new GitHub Action version is adopted, THE CI_Pipeline SHALL update both the SHA digest and the version comment in the same commit -3. WHEN Dependabot proposes a GitHub Actions digest bump, THE CI_Pipeline SHALL receive a pull request targeting the `develop` branch with the updated SHA digest -4. THE CI_Pipeline SHALL reference the local composite action (`.github/actions/configure-aws-credentials`) using a relative path (exempt from SHA pinning) - -### Requirement 2: Pin Python Dependencies to Exact Versions - -**User Story:** As a backend developer, I want Python dependencies pinned to exact versions in `pyproject.toml`, so that local development and CI resolve identical packages. - -**Priority:** HIGH - -#### Acceptance Criteria - -1. THE Dependency_Manager SHALL resolve all direct Python dependencies in `pyproject.toml` to exact versions using the `==` operator -2. THE Dependency_Manager SHALL resolve all optional dependency groups (`agentcore`, `dev`) to exact versions using the `==` operator -3. WHEN a dependency version is updated, THE Dependency_Manager SHALL update both `pyproject.toml` and `uv.lock` in the same commit -4. IF a dependency in `pyproject.toml` uses a floor pin (`>=`), a compatible release pin (`~=`), or has no version constraint, THEN THE CI_Pipeline SHALL fail a lint check identifying the non-exact pin - -### Requirement 3: Pin Frontend Dependencies to Exact Versions - -**User Story:** As a frontend developer, I want npm dependencies pinned to exact versions in `package.json`, so that `npm ci` produces identical `node_modules` across all environments. - -**Priority:** HIGH - -#### Acceptance Criteria - -1. THE Dependency_Manager SHALL specify all direct frontend dependencies in `package.json` using exact version strings (no `^` or `~` prefix) -2. THE Dependency_Manager SHALL specify all devDependencies in `package.json` using exact version strings (no `^` or `~` prefix) -3. WHEN a dependency version is updated, THE Dependency_Manager SHALL update both `package.json` and `package-lock.json` in the same commit - -### Requirement 4: Pin Global Tool Installations in Install Scripts - -**User Story:** As a DevOps engineer, I want global tool installations in CI scripts pinned to specific versions, so that builds are reproducible regardless of when they run. - -**Priority:** HIGH - -#### Acceptance Criteria - -1. THE Install_Script SHALL install the AWS CDK CLI at a specific pinned version (e.g., `npm install -g aws-cdk@2.1033.0`) instead of resolving to the latest release -2. THE Install_Script SHALL install Node.js from a versioned distribution URL specifying a major version (e.g., `setup_20.x`) -3. WHEN the Install_Script installs any global npm package, THE Install_Script SHALL specify an exact version using the `@version` suffix - -### Requirement 5: Tighten aws-cdk-lib Version Range - -**User Story:** As an infrastructure developer, I want the `aws-cdk-lib` dependency range tightened, so that weekly CDK releases with breaking construct changes do not silently enter the build. - -**Priority:** HIGH - -#### Acceptance Criteria - -1. THE Dependency_Manager SHALL specify `aws-cdk-lib` in `infrastructure/package.json` using an exact version pin (e.g., `"aws-cdk-lib": "2.235.1"`) -2. THE Dependency_Manager SHALL specify the `aws-cdk` CLI devDependency in `infrastructure/package.json` using an exact version pin -3. WHEN the CDK version is updated, THE Dependency_Manager SHALL update both `package.json` and `package-lock.json` in the same commit - -### Requirement 6: Enforce npm ci in All CI Install Paths - -**User Story:** As a DevOps engineer, I want all CI dependency installations to use `npm ci`, so that the lockfile is the single source of truth for resolved versions. - -**Priority:** HIGH - -#### Acceptance Criteria - -1. THE CI_Pipeline SHALL use `npm ci` (not `npm install`) for all npm dependency installations during CI/CD jobs -2. WHEN a `package-lock.json` file is present, THE Install_Script SHALL use `npm ci` for dependency installation -3. IF a `package-lock.json` file is missing, THEN THE Install_Script SHALL exit with a non-zero status code and a descriptive error message - -### Requirement 7: Add Container Image Scanning - -**User Story:** As a security engineer, I want automated vulnerability scanning on all Docker images before deployment, so that known CVEs are detected before reaching production. - -**Priority:** HIGH - -#### Acceptance Criteria - -1. WHEN a Docker image is built in the CI_Pipeline, THE Image_Scanner SHALL scan the image for known vulnerabilities before the image is pushed to ECR -2. IF the Image_Scanner detects a vulnerability with severity CRITICAL or HIGH, THEN THE CI_Pipeline SHALL fail the build and report the findings in the job summary -3. THE Image_Scanner SHALL produce a scan report artifact with retention matching the existing artifact retention policy -4. THE CI_Pipeline SHALL scan all Dockerfiles in the repository (`Dockerfile.app-api`, `Dockerfile.inference-api`, `Dockerfile.rag-ingestion`) - -### Requirement 8: Pin GitHub Actions Runner Versions - -**User Story:** As a DevOps engineer, I want CI runners pinned to specific OS versions, so that runner image updates do not introduce unexpected environment changes. - -**Priority:** HIGH - -#### Acceptance Criteria - -1. THE CI_Pipeline SHALL specify explicit runner OS versions (e.g., `ubuntu-24.04`) instead of floating aliases (e.g., `ubuntu-latest`) for all workflow jobs -2. WHEN a runner OS version is updated, THE CI_Pipeline SHALL update all workflow files referencing that runner in the same pull request - -### Requirement 9: Enhance Dependabot Configuration for SHA Pinning - -**User Story:** As a DevOps engineer, I want Dependabot configured to propose SHA digest bumps for GitHub Actions, so that pinned actions stay current with security patches. - -**Priority:** HIGH - -**Note:** A `dependabot.yml` already exists with coverage for pip, npm (frontend and infrastructure), and github-actions ecosystems. This requirement focuses on ensuring the configuration supports the SHA-pinned workflow. - -#### Acceptance Criteria - -1. THE Dependabot configuration SHALL include a `github-actions` ecosystem entry that proposes SHA digest updates for all pinned actions -2. THE Dependabot configuration SHALL target the `develop` branch for all update pull requests -3. THE Dependabot configuration SHALL group minor and patch updates to reduce pull request volume - -### Requirement 10: Pin Docker apt-get Package Versions - -**User Story:** As a DevOps engineer, I want apt-get packages in Dockerfiles pinned to specific versions, so that the apt layer does not undermine the base image digest pin. - -**Priority:** HIGH - -#### Acceptance Criteria - -1. THE Docker_Builder SHALL install all apt-get packages with explicit version pins (e.g., `gcc=12.2.0-14`) -2. WHEN a Dockerfile installs system packages via apt-get, THE Docker_Builder SHALL specify the package version for each package -3. IF an apt-get package version is unavailable in the base image's package repository, THEN THE Docker_Builder SHALL document the version constraint as a comment in the Dockerfile - -### Requirement 11: Create Fork Setup Documentation - -**User Story:** As an external contributor, I want a step-by-step fork setup guide, so that I can reproduce the development environment without internal knowledge. - -**Priority:** HIGH - -#### Acceptance Criteria - -1. THE CI_Pipeline repository SHALL include a `CONTRIBUTING.md` file at the repository root -2. THE `CONTRIBUTING.md` SHALL document prerequisites (Node.js version, Python version, AWS CLI, Docker) -3. THE `CONTRIBUTING.md` SHALL document step-by-step instructions for cloning, installing dependencies, and running the application locally -4. THE `CONTRIBUTING.md` SHALL document how to configure required environment variables and AWS credentials for local development -5. THE `CONTRIBUTING.md` SHALL document how to run the test suites for backend, frontend, and infrastructure - -### Requirement 12: Fix mypy Target Version Mismatch - -**User Story:** As a backend developer, I want the mypy target version aligned with the project's minimum Python version, so that type checking reflects the actual runtime environment. - -**Priority:** MEDIUM - -#### Acceptance Criteria - -1. THE Dependency_Manager configuration SHALL set `[tool.mypy] python_version` to match the `requires-python` minimum version in `pyproject.toml` -2. WHEN the `requires-python` minimum version is changed, THE Dependency_Manager configuration SHALL update the mypy `python_version` in the same commit - -### Requirement 13: Standardize GitHub Actions Checkout Versions - -**User Story:** As a DevOps engineer, I want all workflows using the same version of `actions/checkout`, so that inconsistent behavior across workflows is eliminated. - -**Priority:** MEDIUM - -#### Acceptance Criteria - -1. THE CI_Pipeline SHALL use the same SHA-pinned version of `actions/checkout` across all workflow files -2. WHEN the `actions/checkout` version is updated, THE CI_Pipeline SHALL update all workflow files in the same pull request - -### Requirement 14: Document Artifact Retention Policy - -**User Story:** As a DevOps engineer, I want a documented artifact retention policy, so that storage costs are predictable and retention periods are intentional. - -**Priority:** MEDIUM - -#### Acceptance Criteria - -1. THE CI_Pipeline repository SHALL include a documented artifact retention policy specifying retention periods by artifact type -2. THE CI_Pipeline SHALL apply consistent retention periods across all workflows for the same artifact type (e.g., all Docker image artifacts use the same retention, all CDK synth artifacts use the same retention) -3. THE artifact retention policy SHALL define retention periods for: Docker image artifacts, CDK synthesized templates, test results, and deployment outputs - -### Requirement 15: Enable cancel-in-progress for Frontend Workflows - -**User Story:** As a DevOps engineer, I want `cancel-in-progress: true` on frontend asset workflows, so that superseded builds are cancelled to save runner minutes. - -**Priority:** MEDIUM - -#### Acceptance Criteria - -1. THE CI_Pipeline SHALL set `cancel-in-progress: true` on the concurrency group for the frontend workflow -2. THE CI_Pipeline SHALL retain `cancel-in-progress: false` for workflows that deploy infrastructure or push Docker images to ECR - -### Requirement 16: Add Post-Deployment Smoke Tests - -**User Story:** As a DevOps engineer, I want smoke tests after every deployment, so that broken deployments are detected before users are affected. - -**Priority:** MEDIUM - -#### Acceptance Criteria - -1. WHEN a deployment job completes successfully, THE CI_Pipeline SHALL execute a health check against the deployed service endpoint -2. IF the post-deployment health check fails, THEN THE CI_Pipeline SHALL report the failure in the job summary and exit with a non-zero status -3. THE CI_Pipeline SHALL include post-deployment smoke tests for the App API, Inference API, and Frontend workflows - -### Requirement 17: Scope Secrets to Jobs That Require Them - -**User Story:** As a security engineer, I want AWS credentials scoped to only the jobs that need AWS access, so that the blast radius of a credential leak is minimized. - -**Priority:** MEDIUM - -#### Acceptance Criteria - -1. THE CI_Pipeline SHALL define AWS credential environment variables at the job level (not the workflow level) only for jobs that perform AWS operations -2. THE CI_Pipeline SHALL omit AWS credential environment variables from jobs that do not interact with AWS services (e.g., unit test jobs, lint jobs, build jobs without ECR push) -3. WHEN a new job is added to a workflow, THE CI_Pipeline SHALL include AWS credentials only if the job requires AWS API calls diff --git a/.kiro/specs/supply-chain-hardening/tasks.md b/.kiro/specs/supply-chain-hardening/tasks.md deleted file mode 100644 index 7978f231..00000000 --- a/.kiro/specs/supply-chain-hardening/tasks.md +++ /dev/null @@ -1,221 +0,0 @@ -# Implementation Plan: Supply Chain Hardening - -## Overview - -Harden the CI/CD supply chain across GitHub Actions workflows, dependency manifests, Dockerfiles, and shell scripts. All changes are configuration-level — no application code is modified. Tasks are ordered so each builds on the previous, with property-based tests validating invariants after each group of changes. - -## Tasks - -- [x] 1. Pin GitHub Actions to SHA digests and standardize checkout version - - [x] 1.1 Pin all third-party action references in workflow YAML files to SHA digests with version comments - - For each workflow in `.github/workflows/*.yml` (13 files), replace every third-party `uses:` reference (e.g., `actions/checkout@v5`) with its SHA-256 digest plus version comment (e.g., `actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2`) - - Standardize all `actions/checkout` references to the same SHA-pinned version across all 13 workflow files - - Actions to pin: `actions/checkout`, `actions/cache/restore`, `actions/cache/save`, `actions/upload-artifact`, `actions/download-artifact`, `actions/setup-python`, `docker/setup-buildx-action`, `docker/build-push-action`, `aquasecurity/trivy-action` (added in task 5) - - Leave the local composite action (`.github/actions/configure-aws-credentials`) referenced by relative path — exempt from SHA pinning - - _Requirements: 1.1, 1.2, 1.4, 13.1_ - - - [x] 1.2 Pin third-party actions inside the composite action to SHA digests - - In `.github/actions/configure-aws-credentials/action.yml`, replace `aws-actions/configure-aws-credentials@v6` with its SHA digest plus version comment - - _Requirements: 1.1_ - - - [x] 1.3 Write property test for SHA pinning (Property 1) - - **Property 1: Third-party actions are SHA-pinned with version comments** - - Create `backend/tests/supply_chain/test_action_pinning.py` - - Parse all workflow YAML files and the composite action, find all `uses:` values, verify each third-party reference matches `owner/action@<40-char-hex> # vX.Y.Z` - - Verify local composite action references (starting with `./`) are exempt - - **Validates: Requirements 1.1** - - - [x] 1.4 Write property test for consistent checkout SHA (Property 10) - - **Property 10: Consistent checkout action SHA across all workflows** - - In `backend/tests/supply_chain/test_action_pinning.py`, add test that extracts the SHA digest for `actions/checkout` from every workflow file and asserts they are all identical - - **Validates: Requirements 13.1** - -- [x] 2. Pin runner versions across all workflows - - [x] 2.1 Replace all `ubuntu-latest` with `ubuntu-24.04` in workflow files - - In all 13 workflow files under `.github/workflows/`, replace every `runs-on: ubuntu-latest` with `runs-on: ubuntu-24.04` - - Jobs already using `ubuntu-24.04-arm` remain unchanged - - _Requirements: 8.1_ - - - [x] 2.2 Write property test for runner version pinning (Property 7) - - **Property 7: No workflow job uses floating runner aliases** - - Create `backend/tests/supply_chain/test_runner_pinning.py` - - Parse all workflow YAML files, extract every `runs-on` value, assert none contain `-latest` - - **Validates: Requirements 8.1** - -- [x] 3. Checkpoint — Verify workflow YAML changes - - Ensure all tests pass, ask the user if questions arise. - -- [x] 4. Pin Python dependencies to exact versions and fix mypy version - - [x] 4.1 Replace all `>=`, `~=`, and unpinned versions in `pyproject.toml` with `==` exact pins - - In `backend/pyproject.toml`, convert every dependency in `dependencies`, `[project.optional-dependencies].agentcore`, and `[project.optional-dependencies].dev` from floor pins (`>=`) to exact pins (`==`) - - Keep the existing version numbers (e.g., `"boto3>=1.40.1"` → `"boto3==1.40.1"`) - - After pinning, regenerate `uv.lock` with `uv lock` - - _Requirements: 2.1, 2.2, 2.3_ - - - [x] 4.2 Fix mypy `python_version` to match `requires-python` - - In `backend/pyproject.toml`, change `[tool.mypy] python_version = "3.9"` to `python_version = "3.10"` to match `requires-python = ">=3.10"` - - _Requirements: 12.1_ - - - [x] 4.3 Write property test for Python dependency pinning (Property 2) - - **Property 2: All Python dependencies use exact version pins** - - Create `backend/tests/supply_chain/test_dependency_pinning.py` - - Parse `pyproject.toml`, extract all dependency strings from all sections, verify each uses the `==` operator and none use `>=`, `~=`, `>`, `<`, or have no version constraint - - **Validates: Requirements 2.1, 2.2, 2.4** - -- [x] 5. Pin frontend and infrastructure npm dependencies to exact versions - - [x] 5.1 Pin all frontend dependencies in `frontend/ai.client/package.json` to exact versions from lockfile - - For each dependency in `dependencies` and `devDependencies`, look up the resolved version in `frontend/ai.client/package-lock.json` and replace the version string with the exact resolved version (no `^` or `~`) - - Do NOT simply strip `^`/`~` — use the actual resolved version from the lockfile - - Run `npm install` to regenerate `package-lock.json`, then verify with `npm ci` - - _Requirements: 3.1, 3.2, 3.3_ - - - [x] 5.2 Pin infrastructure dependencies in `infrastructure/package.json` to exact versions - - Set `"aws-cdk-lib": "2.244.0"` and `"aws-cdk": "2.1113.0"` (target CDK versions) - - Pin all other dependencies and devDependencies to exact versions from `infrastructure/package-lock.json` (no `^` or `~`) - - Run `npm install` to regenerate `package-lock.json`, then verify with `npm ci` - - _Requirements: 5.1, 5.2, 5.3_ - - - [x] 5.3 Write property test for npm dependency pinning (Property 3) - - **Property 3: All npm dependencies use exact version pins** - - In `backend/tests/supply_chain/test_dependency_pinning.py`, add test that parses `frontend/ai.client/package.json` and `infrastructure/package.json`, checks every version string in `dependencies` and `devDependencies` does not start with `^`, `~`, `>`, `<`, or `*` - - **Validates: Requirements 3.1, 3.2, 5.1, 5.2** - -- [x] 6. Harden install scripts (global tool pinning + npm ci enforcement) - - [x] 6.1 Pin CDK CLI version in install scripts - - In `scripts/common/install-deps.sh`, change `npm install -g aws-cdk` to `npm install -g aws-cdk@2.1113.0` - - In `scripts/stack-infrastructure/install.sh`, change `npm install -g aws-cdk` to `npm install -g aws-cdk@2.1113.0` - - _Requirements: 4.1, 4.3_ - - - [x] 6.2 Replace `npm install` with `npm ci` and add lockfile checks in install scripts - - In `scripts/stack-infrastructure/install.sh`, replace `npm install` with `npm ci` and add a lockfile existence check that exits non-zero if `package-lock.json` is missing - - In `scripts/stack-app-api/install.sh`, replace the `npm install` in the CDK dependencies section with `npm ci` and add a lockfile existence check - - Use `scripts/stack-frontend/install.sh` as the reference pattern - - _Requirements: 6.1, 6.2, 6.3_ - - - [x] 6.3 Write property test for global npm install pinning (Property 4) - - **Property 4: Global npm installs specify exact versions** - - Create `backend/tests/supply_chain/test_script_hardening.py` - - Scan all shell scripts under `scripts/` for `npm install -g` commands, verify each package includes an `@version` suffix - - **Validates: Requirements 4.1, 4.3** - - - [x] 6.4 Write property test for npm ci enforcement (Property 5) - - **Property 5: CI install paths use npm ci with lockfile check** - - In `backend/tests/supply_chain/test_script_hardening.py`, add test that scans install scripts for npm dependency installation commands, verifies they use `npm ci` (not `npm install` for project deps), and include a lockfile existence check - - **Validates: Requirements 6.1, 6.2** - -- [x] 7. Checkpoint — Verify dependency and script changes - - Ensure all tests pass, ask the user if questions arise. - -- [x] 8. Pin Docker apt-get/dnf package versions - - [x] 8.1 Pin apt-get package versions in `Dockerfile.app-api` and `Dockerfile.inference-api` - - In both builder stages, pin `gcc` and `g++` to exact versions available in the `python:3.13-slim` base image (Debian Bookworm) - - In both production stages, pin `curl` to the exact version available in the base image - - Query available versions by inspecting the base image's package repository - - _Requirements: 10.1, 10.2_ - - - [x] 8.2 Pin dnf package versions in `Dockerfile.rag-ingestion` where practical - - In the builder stage, pin `gcc`, `gcc-c++`, `make`, `tar`, `gzip`, `ca-certificates`, `unzip` to versions available in the AL2023 Lambda base image - - In the production stage, pin `mesa-libGL` and `glib2` to available versions - - Where exact versions are unavailable or impractical on AL2023, add a comment documenting the constraint - - _Requirements: 10.1, 10.2, 10.3_ - - - [x] 8.3 Write property test for Dockerfile package pinning (Property 9) - - **Property 9: Dockerfile apt-get packages have version pins** - - Create `backend/tests/supply_chain/test_dockerfile_pinning.py` - - Parse all Dockerfiles, find `apt-get install` and `dnf install` commands, verify every package name includes a version pin (`package=version` for apt-get, `package-version` for dnf) or has a comment documenting why the pin is omitted - - **Validates: Requirements 10.1, 10.2** - -- [x] 9. Add container image scanning as nightly track - - [x] 9.1 Add `scan-images` track resolution to `nightly.yml` - - In the `resolve-tracks` job, add a new `scan-images-*` case that sets `run_scan_images=true` and `scan_images_ref` - - Add `run_scan_images` and `scan_images_ref` to the job outputs - - Include `scan-images` in the `all` case with `scan_images_ref="develop"` - - _Requirements: 7.1, 7.4_ - - - [x] 9.2 Add `scan-images` job to `nightly.yml` - - Add a new `scan-images` job that builds all three Docker images (app-api, inference-api, rag-ingestion) and runs Trivy against each - - Use `aquasecurity/trivy-action` (SHA-pinned) with `exit-code: '0'` (advisory mode — does NOT fail the job) - - Upload scan reports as artifacts with 30-day retention - - The job runs in parallel with existing tracks, does NOT block any deploy - - _Requirements: 7.1, 7.3, 7.4_ - - - [x] 9.3 Add scan results to nightly summary job - - Add `scan-images` to the `summary` job's `needs` list - - Add a row to the summary report for the image scan track status - - _Requirements: 7.1_ - - - [x] 9.4 Write property test for nightly scan track (Property 6) - - **Property 6: Nightly workflow includes image scanning track** - - Create `backend/tests/supply_chain/test_docker_scanning.py` - - Parse `nightly.yml`, verify `resolve-tracks` outputs include `run_scan_images`, verify a `scan-images` job exists that references all three Dockerfiles, uses `exit-code: '0'`, and uploads artifacts - - **Validates: Requirements 7.1, 7.4** - -- [x] 10. Scope secrets to AWS-using jobs only - - [x] 10.1 Audit and move AWS credentials from workflow-level to job-level env blocks - - Review all 13 workflow files for AWS credential variables (`AWS_ROLE_ARN`, `AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`) in workflow-level `env:` blocks - - Move any workflow-level AWS credentials to job-level `env:` blocks, only on jobs that perform AWS operations (configure-aws-credentials, ECR push, CDK deploy) - - Ensure non-AWS jobs (install, build, test, lint) do not have AWS credentials in their env - - _Requirements: 17.1, 17.2_ - - - [x] 10.2 Write property test for secret scoping (Property 14) - - **Property 14: AWS credentials scoped to AWS-using jobs only** - - Create `backend/tests/supply_chain/test_secret_scoping.py` - - Parse all workflow YAML files, verify no AWS credential variables appear in workflow-level `env:` blocks, and that job-level AWS credentials only appear on jobs containing AWS interaction steps - - **Validates: Requirements 17.1, 17.2** - -- [x] 11. Checkpoint — Verify Docker, scanning, and secret scoping changes - - Ensure all tests pass, ask the user if questions arise. - -- [x] 12. Create documentation files - - [x] 12.1 Create `CONTRIBUTING.md` at repository root - - Document prerequisites: Node.js 20+, Python 3.13+, Docker, AWS CLI v2, uv - - Document clone and install steps for backend, frontend, and infrastructure - - Document environment variable configuration (referencing `backend/src/.env` and `frontend/ai.client/src/environments/`) - - Document how to run test suites: `uv run pytest` (backend), `npm test` (frontend), `npx cdk synth` (infrastructure) - - Document AWS credential setup for local development - - _Requirements: 11.1, 11.2, 11.3, 11.4, 11.5_ - - - [x] 12.2 Create `.github/ARTIFACT_RETENTION.md` - - Document retention periods by artifact type: Docker image tarballs (1 day), CDK synth templates (7 days), test results/coverage (7 days), deployment outputs (30 days), Trivy scan reports (30 days) - - Verify all `retention-days` values in workflow files match the documented policy - - _Requirements: 14.1, 14.2, 14.3_ - - - [x] 12.3 Write property test for artifact retention consistency (Property 11) - - **Property 11: Consistent artifact retention per artifact type** - - Create `backend/tests/supply_chain/test_artifact_retention.py` - - Parse all workflow files, find `upload-artifact` steps, group by artifact category, verify `retention-days` is consistent within each category - - **Validates: Requirements 14.2** - - - [x] 12.4 Write property test for cancel-in-progress on deploy workflows (Property 12) - - **Property 12: All deployment workflows retain cancel-in-progress false** - - Create `backend/tests/supply_chain/test_concurrency_config.py` - - Parse all workflow files that contain CDK deploy jobs, verify `concurrency.cancel-in-progress` is `false` - - **Validates: Requirements 15.2** - - - [x] 12.5 Write unit tests for documentation and mypy version - - Create `backend/tests/supply_chain/test_documentation.py` - - Test that `CONTRIBUTING.md` exists and contains required sections (prerequisites, install steps, environment config, test suites, AWS credentials) - - Test that `.github/ARTIFACT_RETENTION.md` exists and documents all artifact types - - Test that `[tool.mypy] python_version` matches the `requires-python` minimum version - - **Validates: Requirements 11.1–11.5, 12.1, 14.1, 14.3** - -- [x] 13. Validate Dependabot configuration (no changes needed) - - [x] 13.1 Write property test for Dependabot config (Property 8) - - **Property 8: Dependabot entries target develop with grouped updates** - - Create `backend/tests/supply_chain/test_dependabot_config.py` - - Parse `.github/dependabot.yml`, verify every ecosystem entry has `target-branch: "develop"` and a `groups` section with `update-types` covering both `"minor"` and `"patch"` - - **Validates: Requirements 9.2, 9.3** - -- [x] 14. Final checkpoint — Ensure all tests pass - - Ensure all tests pass, ask the user if questions arise. - -## Notes - -- Tasks marked with `*` are optional and can be skipped for faster MVP -- Component 6 (Dependabot) requires NO file changes — existing config already meets requirements; only a validation test is added -- Component 11 (cancel-in-progress) requires NO changes — all workflows correctly use `false` since they all have CDK deploys -- Component 12 (smoke tests) and Property 13 are DEFERRED — no tasks created -- For npm version pinning (tasks 5.1, 5.2), resolved versions must be read from the lockfile, not just stripped of `^` or `~` -- CDK target versions: `aws-cdk` CLI = `2.1113.0`, `aws-cdk-lib` = `2.244.0` -- Property tests use Python `hypothesis` + `pytest` (already in dev dependencies) -- All property tests go under `backend/tests/supply_chain/` diff --git a/.kiro/specs/versioning-strategy/.config.kiro b/.kiro/specs/versioning-strategy/.config.kiro deleted file mode 100644 index 8648aeb4..00000000 --- a/.kiro/specs/versioning-strategy/.config.kiro +++ /dev/null @@ -1 +0,0 @@ -{"specId": "a7635d70-d84c-467a-8898-599eabf641c1", "workflowType": "design-first", "specType": "feature"} \ No newline at end of file diff --git a/.kiro/specs/versioning-strategy/design.md b/.kiro/specs/versioning-strategy/design.md deleted file mode 100644 index f720887d..00000000 --- a/.kiro/specs/versioning-strategy/design.md +++ /dev/null @@ -1,531 +0,0 @@ -# Design Document: Versioning Strategy - -## Overview - -This design introduces a unified versioning strategy for the AgentCore Public Stack monorepo ahead of beta launch. Today, version information is fragmented: `pyproject.toml` says `0.1.0`, `package.json` files hold placeholder values, health endpoints return a hardcoded stale `2.0.0`, and Docker images are tagged only with git commit SHAs. There is no CHANGELOG, no VERSION file, and no git tags. - -The strategy establishes a single source of truth — a `VERSION` file at the repo root — from which all package manifests, Docker image tags, health endpoints, AWS resource tags, and frontend UI derive their version at build time. The monorepo ships as one product with one version number. Git tags mark releases. Docker images carry both a semver tag and a SHA tag for traceability. - -## Architecture - -The version flows from a single file through three phases: commit-time sync, CI/CD build-time injection, and runtime exposure. - -```mermaid -graph TD - V["VERSION file
(repo root)
e.g. 1.0.0-beta.1"] --> SYNC["scripts/sync-version.sh
(commit-time)"] - SYNC --> PY["pyproject.toml
version field"] - SYNC --> FE_PKG["frontend/package.json
version field"] - SYNC --> INFRA_PKG["infrastructure/package.json
version field"] - - V --> CI_BACKEND["CI: Docker Build
(--build-arg APP_VERSION)"] - V --> CI_FRONTEND["CI: Frontend Build
(version → environment.ts)"] - V --> CI_TAG["CI: Git Tag
(v1.0.0-beta.1)"] - - V --> CDK_TAG["CDK: applyStandardTags
(Version tag on all resources)"] - - CI_BACKEND --> ECR_SEM["ECR: semver tag
1.0.0-beta.1"] - CI_BACKEND --> ECR_SHA["ECR: SHA tag
abc1234"] - CI_BACKEND --> ENV_VAR["Container ENV
APP_VERSION=1.0.0-beta.1"] - - ENV_VAR --> HEALTH_APP["/health endpoint
App API"] - ENV_VAR --> HEALTH_INF["/ping endpoint
Inference API"] - - CI_FRONTEND --> FE_UI["Frontend UI
version display"] - - ECR_SEM --> SSM["SSM Parameter
image-tag = 1.0.0-beta.1"] - SSM --> CDK["CDK Deploy
(Fargate task definition)"] - -``` - -## Components and Interfaces - -### Component 1: VERSION File (Source of Truth) - -**Purpose**: Single authoritative location for the monorepo's current version. - -**Location**: `VERSION` (repo root) - -**Format**: Plain text, single line, semver with optional prerelease suffix. - -``` -1.0.0-beta.1 -``` - -**Conventions**: -- Follows [SemVer 2.0](https://semver.org/): `MAJOR.MINOR.PATCH[-PRERELEASE]` -- Beta phase uses `X.Y.Z-beta.N` (e.g. `1.0.0-beta.1`, `1.0.0-beta.2`) -- GA release drops the prerelease suffix (e.g. `1.0.0`) -- Bumped manually by a developer via PR — no automated version bumps - -**Responsibilities**: -- Holds the canonical version string -- Read by sync script, CI workflows, and build scripts - ---- - -### Component 2: Version Sync Script - -**Purpose**: Keeps `pyproject.toml`, `frontend/ai.client/package.json`, and `infrastructure/package.json` version fields in sync with the VERSION file. - -**Location**: `scripts/common/sync-version.sh` - -**Interface**: -``` -Usage: bash scripts/common/sync-version.sh [--check] - (no flags) → Writes VERSION value into all package manifests - --check → Exits non-zero if any manifest is out of sync (for CI validation) -``` - -**Responsibilities**: -- Reads `VERSION` file -- Updates `version` field in `backend/pyproject.toml` -- Updates `version` field in `frontend/ai.client/package.json` -- Updates `version` field in `infrastructure/package.json` -- In `--check` mode, reports drift without modifying files (used in CI as a gate) - -**Files Modified**: -| File | Field | Method | -|------|-------|--------| -| `backend/pyproject.toml` | `version = "X.Y.Z"` | sed replacement | -| `frontend/ai.client/package.json` | `"version": "X.Y.Z"` | jq or sed | -| `infrastructure/package.json` | `"version": "X.Y.Z"` | jq or sed | - -**Note**: Docker images (App API, Inference API, RAG Ingestion) receive the version via `--build-arg` at CI time, not through the sync script. The sync script only handles package manifest files. - ---- - -### Component 3: Backend Health Endpoints (Runtime) - -**Purpose**: Expose the running version at runtime via health check responses. - -**Current State**: -- App API (`/health`): Returns hardcoded `"version": "2.0.0"` -- Inference API (`/ping`): Returns `{"status": "healthy"}` with no version -- FastAPI app object: `version="2.0.0"` hardcoded in `main.py` - -**New Behavior**: -- Both endpoints read version from `APP_VERSION` environment variable -- Falls back to `"unknown"` if env var is not set (local dev without Docker) -- FastAPI app `version` parameter also reads from env var - -**Affected Files**: -- `backend/src/apis/app_api/health/health.py` -- `backend/src/apis/inference_api/chat/routes.py` (the `/ping` endpoint) -- `backend/src/apis/inference_api/main.py` (FastAPI app `version` param) -- `backend/src/apis/app_api/main.py` (FastAPI app `version` param, if hardcoded) - ---- - -### Component 4: Docker Build (Build-Time Injection) - -**Purpose**: Bake the version into Docker images as an environment variable and apply semver + SHA dual tags. - -**Current State**: -- Dockerfiles accept `BUILD_DATE` and `VCS_REF` build args but no version -- Images tagged only with short git SHA -- `tag-latest.sh` adds `latest` and `deployed-` tags post-deploy - -**New Behavior**: -- Dockerfiles accept a new `APP_VERSION` build arg -- `ENV APP_VERSION=${APP_VERSION}` baked into the image -- CI tags images with both semver (`1.0.0-beta.1`) and SHA (`abc1234`) -- `tag-latest.sh` continues to add `latest` after successful deploy -- ECR lifecycle policy already preserves tags prefixed with `v` and `release` - -**Affected Docker images (3 total)**: - -| Image | Dockerfile | Health Endpoint | Version Env Var | -|-------|-----------|-----------------|-----------------| -| App API | `Dockerfile.app-api` | `/health` → version in response | `APP_VERSION` | -| Inference API | `Dockerfile.inference-api` | `/ping` → version in response | `APP_VERSION` | -| RAG Ingestion | `Dockerfile.rag-ingestion` | N/A (Lambda, no health endpoint) | `APP_VERSION` (for logging/traceability) | - -**Affected Files**: -- `backend/Dockerfile.app-api` -- `backend/Dockerfile.inference-api` -- `backend/Dockerfile.rag-ingestion` -- `scripts/stack-app-api/build.sh` -- `scripts/stack-app-api/push-to-ecr.sh` -- `scripts/stack-inference-api/build.sh` -- `scripts/stack-inference-api/push-to-ecr.sh` -- `scripts/stack-rag-ingestion/push-to-ecr.sh` - -**Stacks excluded from Docker versioning (no container images)**: -- **Infrastructure** — Pure CDK resources (VPC, ALB, ECS Cluster). No runtime artifact. -- **Gateway** — AgentCore Gateway + Lambda functions bundled by CDK. No Docker image. -- **Frontend** — Static assets to S3. Version exposed via `config.json` (Component 6). - ---- - -### Component 5: CI/CD Workflows (Orchestration) - -**Purpose**: Read VERSION file, pass it through build/push/deploy pipeline, and optionally create git tags. - -**Current State**: -- `IMAGE_TAG` is set to `git rev-parse --short HEAD` in the `build-docker` job -- No version validation or git tagging - -**New Behavior**: -- New step in `build-docker` job: read VERSION file into `APP_VERSION` output -- Docker build passes `--build-arg APP_VERSION=$APP_VERSION` -- Docker image tagged with both `$APP_VERSION` and `$IMAGE_TAG` (SHA) -- `push-to-ecr.sh` pushes both tags; SSM parameter stores the semver tag -- Version-check job runs `sync-version.sh --check` to catch drift -- On `main` branch push: create git tag `v$APP_VERSION` if it doesn't exist - -**Affected Workflows**: -- `.github/workflows/app-api.yml` -- `.github/workflows/inference-api.yml` -- `.github/workflows/rag-ingestion.yml` -- `.github/workflows/frontend.yml` - -**Workflows excluded (no version injection needed)**: -- `.github/workflows/infrastructure.yml` — CDK-only, no Docker image or runtime version surface -- `.github/workflows/gateway.yml` — CDK-only, Lambda functions bundled by CDK (no Docker image) - ---- - -### Component 6: Frontend Version Display - -**Purpose**: Make the running version visible in the Angular frontend UI. - -**Current State**: -- `environment.ts` has no version field (local dev fallback only) -- `ConfigService` loads runtime config from `/config.json` at startup (generated by CDK `FrontendStack`) -- No version displayed anywhere in the UI - -**New Behavior**: -- **Deployed builds**: CDK `FrontendStack` reads the version (from CDK context or env var) and includes it in the generated `config.json` alongside `appApiUrl` and `environment`. The `ConfigService` picks it up at startup via `APP_INITIALIZER`. -- **Local dev**: `environment.ts` gets a static fallback `version: 'dev'`. If a local `public/config.json` exists, it can override this. -- `RuntimeConfig` interface in `ConfigService` gains a `version` field. -- Frontend can display version in the sidebar footer, settings page, or header tooltip. - -**Affected Files**: -- `frontend/ai.client/src/app/services/config.service.ts` (add `version` to `RuntimeConfig` interface + computed signal) -- `frontend/ai.client/src/environments/environment.ts` (add `version: 'dev'` fallback) -- `frontend/ai.client/src/environments/environment.production.ts` (add `version: ''` fallback) -- `infrastructure/lib/frontend-stack.ts` (add `version` to `runtimeConfig` object) -- `infrastructure/lib/config.ts` (load version from env var / context) - -**Config flow (deployed)**: -``` -VERSION file → CI env var → CDK context → config.ts → FrontendStack → config.json (S3) → ConfigService → UI -``` - -**Config flow (local dev)**: -``` -environment.ts (version: 'dev') → ConfigService fallback → UI -``` - ---- - -### Component 7: AWS Resource Tagging - -**Purpose**: Tag all AWS resources across all stacks with the current version for traceability, cost allocation, and audit. - -**Current State**: -- `applyStandardTags()` in `config.ts` applies `Project` tag + any tags from `config.tags` to every stack -- Every stack calls `applyStandardTags(this, config)` — so adding a tag here cascades to all AWS resources automatically -- No `Version` tag exists today - -**New Behavior**: -- `config.ts` loads the app version from `CDK_APP_VERSION` env var or CDK context (`appVersion`) -- `applyStandardTags()` adds a `Version` tag with the value from the VERSION file (e.g. `1.0.0-beta.1`) -- This applies to all resources in all 7 stacks: Infrastructure, App API, Inference API, Frontend, Gateway, RAG Ingestion, and any future stacks -- No per-stack changes needed — the tag propagates via the existing `applyStandardTags()` call - -**Affected Files**: -- `infrastructure/lib/config.ts` (add `appVersion` to `AppConfig`, load from env/context, add to `applyStandardTags`) -- `scripts/common/load-env.sh` (export `CDK_APP_VERSION` from VERSION file) -- All `synth.sh` / `deploy.sh` scripts (pass `--context appVersion=...`) -- All workflow YAML files (read VERSION file, set `CDK_APP_VERSION` env var) - -**Tag applied**: -| Tag Key | Tag Value | Example | -|---------|-----------|---------| -| `Version` | `` | `1.0.0-beta.1` | - -**Coverage**: All AWS resources across all stacks (VPC, ALB, ECS, S3, CloudFront, DynamoDB, Lambda, Gateway, etc.) - ---- - -### Component 8: PR Version Gate Workflow - -**Purpose**: Block PRs to `main` that haven't bumped the VERSION file or have manifests out of sync. - -**Trigger**: All pull requests targeting `main`, regardless of which files changed. - -**Checks (both must pass)**: - -| Check | What it does | Failure message | -|-------|-------------|-----------------| -| Version bumped | Compares `VERSION` file in the PR branch against `main`. If unchanged, fails. | "VERSION file has not been updated. Bump the version before merging to main." | -| Version synced | Runs `sync-version.sh --check` to verify all manifests match VERSION. | "Package manifests are out of sync with VERSION. Run `bash scripts/common/sync-version.sh` and commit." | - -**Workflow**: `.github/workflows/version-check.yml` - -**Behavior**: -- Fires on every PR to `main` (all file paths, no path filter) -- Fetches `main` branch to compare VERSION against -- Step 1: `git diff origin/main -- VERSION` — if empty, the version wasn't bumped → fail -- Step 2: `bash scripts/common/sync-version.sh --check` — if non-zero exit, manifests are drifted → fail -- Both steps run so the developer sees all failures at once (not fail-fast on step 1) -- Lightweight: no dependencies to install, no AWS credentials, no Docker — just bash + git - -**Branch protection**: Configure `version-check` as a required status check on `main` in GitHub repo settings. This blocks merge until both checks pass. - -**Note**: This workflow does NOT run on pushes to `main` or `develop` — it's PR-only. The version bump enforcement only applies to the merge gate into `main`. - ---- - -### Component 9: Git Tags - -**Purpose**: Mark release commits with semver tags for traceability and rollback. - -**Mechanism**: -- After successful deploy on `main`, CI creates an annotated git tag `v` if it doesn't already exist -- Tags are not created on `develop` or PR branches -- Tags are lightweight pointers — no GitHub Release objects created automatically (can be added later) - -**Affected Files**: -- `.github/workflows/app-api.yml` (or a dedicated release workflow) - ---- - -### Component 10: AI Assistant Versioning Guides - -**Purpose**: Ensure all AI coding assistants (Claude Code, Cursor, Kiro) know how to bump the version correctly without the developer having to explain it each time. - -**Files created (3 total)**: - -| File | Tool | Inclusion | -|------|------|-----------| -| `.claude/skills/versioning/SKILL.md` | Claude Code | Auto (skill) | -| `.cursor/rules/versioning.mdc` | Cursor | `alwaysApply: true` | -| `.kiro/steering/versioning.md` | Kiro | Always included (no frontmatter = default) | - -**Content** (identical across all three, adapted to each format): - -Concise instructions covering: -1. Source of truth is `VERSION` file at repo root -2. Format: `MAJOR.MINOR.PATCH[-PRERELEASE]` (SemVer) -3. To bump: edit `VERSION`, run `bash scripts/common/sync-version.sh`, commit both -4. PRs to `main` will fail if VERSION isn't bumped or manifests are out of sync -5. CI handles everything else (Docker tags, AWS resource tags, health endpoints, frontend, git tags) - -**Key constraint**: Keep each file under ~20 lines of content. The guides should be a quick reference, not a tutorial. - -## Data Models - -### VERSION File Format - -``` -MAJOR.MINOR.PATCH[-PRERELEASE] -``` - -Examples: -- `1.0.0-beta.1` (first beta) -- `1.0.0-beta.2` (second beta) -- `1.0.0` (GA release) -- `1.1.0` (minor feature release) - -**Validation Rules**: -- Must match regex: `^[0-9]+\.[0-9]+\.[0-9]+(-[a-zA-Z0-9.]+)?$` -- No leading `v` prefix (the `v` is added only in git tags) -- No trailing newline beyond the single line -- File must contain exactly one line - -### Health Endpoint Response (App API) - -```json -{ - "status": "healthy", - "service": "agent-core", - "version": "1.0.0-beta.1" -} -``` - -### Health Endpoint Response (Inference API) - -```json -{ - "status": "healthy", - "version": "1.0.0-beta.1" -} -``` - -### SSM Parameter - -| Parameter | Value | Description | -|-----------|-------|-------------| -| `/{prefix}/app-api/image-tag` | `1.0.0-beta.1` | Semver tag (was SHA) | -| `/{prefix}/inference-api/image-tag` | `1.0.0-beta.1` | Semver tag (was SHA) | - -### ECR Image Tags (per image) - -| Tag | Purpose | Example | -|-----|---------|---------| -| Semver | Release identification | `1.0.0-beta.1` | -| SHA | Commit traceability | `abc1234` | -| `latest` | Current deployed (post-deploy) | `latest` | -| `deployed-` | Lifecycle policy protection | `deployed-abc1234` | - - -## Sequence Diagrams - -### Version Flow: Developer Bumps Version - -```mermaid -sequenceDiagram - participant Dev as Developer - participant VF as VERSION file - participant Sync as sync-version.sh - participant PT as pyproject.toml - participant PJ as package.json (x2) - participant Git as Git - - Dev->>VF: Edit VERSION to "1.0.0-beta.2" - Dev->>Sync: Run sync-version.sh - Sync->>VF: Read "1.0.0-beta.2" - Sync->>PT: Update version = "1.0.0-beta.2" - Sync->>PJ: Update "version": "1.0.0-beta.2" - Dev->>Git: git add + commit + push -``` - -### Version Flow: CI/CD Pipeline (App API) - -```mermaid -sequenceDiagram - participant GH as GitHub Actions - participant VF as VERSION file - participant Docker as Docker Build - participant ECR as ECR Registry - participant SSM as SSM Parameter Store - participant CDK as CDK Deploy - participant ECS as ECS/Fargate - - GH->>VF: Read VERSION → "1.0.0-beta.1" - GH->>GH: Set IMAGE_TAG=SHA, APP_VERSION=1.0.0-beta.1 - - GH->>Docker: docker build --build-arg APP_VERSION=1.0.0-beta.1 - Docker-->>GH: Image built with ENV APP_VERSION - - GH->>ECR: Push :1.0.0-beta.1 (semver tag) - GH->>ECR: Push :abc1234 (SHA tag) - GH->>SSM: Put /{prefix}/app-api/image-tag = "1.0.0-beta.1" - - GH->>CDK: cdk deploy (reads image-tag from SSM) - CDK->>ECS: Update task definition with new image - ECS-->>ECS: Container starts with APP_VERSION env var - - Note over ECS: GET /health → {"version": "1.0.0-beta.1"} -``` - -### Version Flow: Frontend Build & Deploy - -```mermaid -sequenceDiagram - participant GH as GitHub Actions - participant VF as VERSION file - participant Build as build.sh - participant CDK as CDK FrontendStack - participant S3 as S3 Bucket - participant CF as CloudFront - participant App as Angular App - - GH->>VF: Read VERSION → "1.0.0-beta.1" - GH->>Build: ng build --configuration production - Build-->>GH: dist/ artifacts (no version baked in) - - GH->>S3: Upload dist/ to S3 - - GH->>CDK: cdk deploy FrontendStack (--context appVersion=1.0.0-beta.1) - CDK->>S3: Generate & upload config.json - Note over S3: config.json contains:
appApiUrl, environment, version: "1.0.0-beta.1" - - GH->>CF: Invalidate CloudFront cache - - App->>S3: GET /config.json (via APP_INITIALIZER) - S3-->>App: { version: "1.0.0-beta.1", ... } - Note over App: ConfigService stores version signal
UI displays "v1.0.0-beta.1" -``` - -### Version Flow: Git Tagging (on main) - -```mermaid -sequenceDiagram - participant GH as GitHub Actions - participant VF as VERSION file - participant Git as Git - - GH->>VF: Read VERSION → "1.0.0-beta.1" - GH->>Git: Check if tag v1.0.0-beta.1 exists - alt Tag does not exist - GH->>Git: git tag -a v1.0.0-beta.1 -m "Release 1.0.0-beta.1" - GH->>Git: git push origin v1.0.0-beta.1 - else Tag already exists - GH->>GH: Skip tagging (idempotent) - end -``` - -## Error Handling - -### Error Scenario 1: VERSION File Missing or Malformed - -**Condition**: VERSION file doesn't exist, is empty, or doesn't match semver regex. -**Response**: `sync-version.sh` and CI workflows exit with non-zero code and a clear error message. -**Recovery**: Developer creates or fixes the VERSION file and re-runs. - -### Error Scenario 2: Package Manifests Out of Sync - -**Condition**: `sync-version.sh --check` detects that a manifest's version doesn't match VERSION. -**Response**: CI version-check job fails, blocking the pipeline. -**Recovery**: Developer runs `sync-version.sh` locally, commits the updated manifests. - -### Error Scenario 3: APP_VERSION Env Var Not Set at Runtime - -**Condition**: Container starts without `APP_VERSION` (e.g., local dev without Docker build args). -**Response**: Health endpoints return `"version": "unknown"`. Application runs normally. -**Recovery**: No action needed — this is expected in local development. - -### Error Scenario 4: Git Tag Already Exists - -**Condition**: CI tries to create a tag that already exists (re-run of same version). -**Response**: Tagging step is idempotent — skips if tag exists. -**Recovery**: No action needed. - -### Error Scenario 5: ECR Push Fails for Semver Tag - -**Condition**: Network error or permissions issue pushing the semver-tagged image. -**Response**: CI job fails. SHA-tagged image may or may not have been pushed. -**Recovery**: Re-run the workflow. ECR push is idempotent for the same digest. - -## Testing Strategy - -### Unit Testing Approach - -- Health endpoint tests: verify response includes `version` field read from env var -- `sync-version.sh --check`: test with matching and mismatched versions -- VERSION file validation: test regex against valid and invalid strings - -### Integration Testing Approach - -- Docker build test: build image with `--build-arg APP_VERSION=test-1.0.0`, run container, curl `/health`, assert version matches -- Existing `test-docker.sh` scripts already test health endpoints — extend to verify version field -- Frontend build test: run build with `APP_VERSION` set, verify `environment.ts` contains injected version - -## Performance Considerations - -No performance impact. Version reading happens once at build time (Docker `ENV`) or once at startup (reading env var). Health endpoints already exist and add no new overhead. - -## Security Considerations - -- VERSION file contains no secrets — safe to commit -- `APP_VERSION` env var is non-sensitive — no need for Secrets Manager -- Git tags are created by CI with existing `GITHUB_TOKEN` permissions (requires `contents: write`) - -## Dependencies - -- **Existing**: jq (already available in CI runners and load-env.sh), sed, git -- **No new external dependencies** — this feature uses only shell scripts, Docker build args, and environment variables -- **ECR lifecycle policy**: Already preserves tags prefixed with `v` — semver tags like `1.0.0-beta.1` need the existing `release` prefix rule or a new numeric prefix rule added diff --git a/.kiro/specs/versioning-strategy/requirements.md b/.kiro/specs/versioning-strategy/requirements.md deleted file mode 100644 index 883e7696..00000000 --- a/.kiro/specs/versioning-strategy/requirements.md +++ /dev/null @@ -1,164 +0,0 @@ -# Requirements: Versioning Strategy - -## Requirement 1: Single Source of Truth - -### User Story -As a developer, I want a single VERSION file at the repo root that defines the monorepo's version, so I don't have to update multiple files manually or wonder which one is authoritative. - -### Acceptance Criteria -- [ ] A `VERSION` file exists at the repository root containing a single line with the version string -- [ ] The version string follows SemVer 2.0 format: `MAJOR.MINOR.PATCH[-PRERELEASE]` -- [ ] The VERSION file validates against regex: `^[0-9]+\.[0-9]+\.[0-9]+(-[a-zA-Z0-9.]+)?$` -- [ ] The initial version is set to `1.0.0-beta.1` -- [ ] The file contains no leading `v` prefix (the `v` is added only in git tags) -- [ ] The file contains exactly one line with no trailing whitespace beyond a single newline - ---- - -## Requirement 2: Package Manifest Sync - -### User Story -As a developer, I want a script that propagates the VERSION file value into all package manifests, so they stay in sync without manual editing. - -### Acceptance Criteria -- [ ] A script exists at `scripts/common/sync-version.sh` that reads the VERSION file -- [ ] Running the script without flags updates the `version` field in `backend/pyproject.toml` -- [ ] Running the script without flags updates the `version` field in `frontend/ai.client/package.json` -- [ ] Running the script without flags updates the `version` field in `infrastructure/package.json` -- [ ] Running the script with `--check` exits non-zero if any manifest version doesn't match VERSION -- [ ] Running the script with `--check` does not modify any files -- [ ] The script exits with a clear error message if the VERSION file is missing or malformed -- [ ] The script uses `set -euo pipefail` for error handling - ---- - -## Requirement 3: Backend Health Endpoint Versioning - -### User Story -As an operator, I want the health endpoints to return the running version, so I can verify which version is deployed without checking ECR or SSM. - -### Acceptance Criteria -- [ ] App API `/health` endpoint response includes a `"version"` field read from the `APP_VERSION` environment variable -- [ ] Inference API `/ping` endpoint response includes a `"version"` field read from the `APP_VERSION` environment variable -- [ ] Both endpoints fall back to `"version": "unknown"` when `APP_VERSION` is not set (local dev) -- [ ] The FastAPI `app` object `version` parameter in both `main.py` files reads from `APP_VERSION` env var instead of a hardcoded string -- [ ] The hardcoded `"2.0.0"` version string is removed from all backend files - ---- - -## Requirement 4: Docker Build-Time Version Injection - -### User Story -As a CI pipeline, I want to bake the version into Docker images at build time, so containers know their version at runtime without external lookups. - -### Acceptance Criteria -- [ ] `Dockerfile.app-api` accepts an `APP_VERSION` build arg and sets `ENV APP_VERSION=${APP_VERSION}` -- [ ] `Dockerfile.inference-api` accepts an `APP_VERSION` build arg and sets `ENV APP_VERSION=${APP_VERSION}` -- [ ] `Dockerfile.rag-ingestion` accepts an `APP_VERSION` build arg and sets `ENV APP_VERSION=${APP_VERSION}` -- [ ] Build scripts (`scripts/stack-app-api/build.sh`, `scripts/stack-inference-api/build.sh`) pass `--build-arg APP_VERSION` to `docker build` -- [ ] The `APP_VERSION` value defaults to `"unknown"` if the build arg is not provided - ---- - -## Requirement 5: Docker Image Dual-Tagging - -### User Story -As an operator, I want Docker images tagged with both a semver tag and a git SHA tag, so I can identify releases by version and trace them back to specific commits. - -### Acceptance Criteria -- [ ] ECR images for App API are tagged with both the semver version (e.g. `1.0.0-beta.1`) and the short git SHA (e.g. `abc1234`) -- [ ] ECR images for Inference API are tagged with both the semver version and the short git SHA -- [ ] ECR images for RAG Ingestion are tagged with both the semver version and the short git SHA -- [ ] `push-to-ecr.sh` scripts push both tags for each image -- [ ] SSM parameters (`/{prefix}/app-api/image-tag`, `/{prefix}/inference-api/image-tag`) store the semver tag instead of the SHA tag -- [ ] The `latest` and `deployed-` tags continue to be applied post-deploy as before - ---- - -## Requirement 6: CI/CD Workflow Version Integration - -### User Story -As a CI pipeline, I want workflows to read the VERSION file and pass it through the build/push/deploy pipeline, so the version flows automatically from source to production. - -### Acceptance Criteria -- [ ] The `build-docker` job in `app-api.yml` reads the VERSION file and outputs `APP_VERSION` -- [ ] The `build-docker` job in `inference-api.yml` reads the VERSION file and outputs `APP_VERSION` -- [ ] The `build-docker` job in `rag-ingestion.yml` reads the VERSION file and outputs `APP_VERSION` -- [ ] Docker build steps pass `--build-arg APP_VERSION=$APP_VERSION` -- [ ] The `frontend.yml` workflow reads the VERSION file and passes it as CDK context (`--context appVersion=...`) -- [ ] All workflows that run `cdk deploy` pass the version via `CDK_APP_VERSION` env var or `--context appVersion` - ---- - -## Requirement 7: Frontend Version Display - -### User Story -As a user, I want to see the application version in the frontend UI, so I can report which version I'm using when filing issues. - -### Acceptance Criteria -- [ ] The `RuntimeConfig` interface in `ConfigService` includes a `version` field of type `string` -- [ ] `ConfigService` exposes a `version` computed signal that returns the version from config -- [ ] `environment.ts` (local dev) includes `version: 'dev'` as a fallback value -- [ ] `environment.production.ts` includes `version: ''` as a fallback placeholder -- [ ] CDK `FrontendStack` includes `version` in the generated `config.json` object, read from config -- [ ] `config.ts` loads the app version from `CDK_APP_VERSION` env var or CDK context (`appVersion`) -- [ ] The version is displayed somewhere visible in the frontend UI (sidebar footer, header tooltip, or settings page) - ---- - -## Requirement 8: AWS Resource Tagging - -### User Story -As an operator, I want all AWS resources tagged with the deployed version, so I can filter resources by version in the AWS console and use it for cost allocation. - -### Acceptance Criteria -- [ ] `AppConfig` interface in `config.ts` includes an `appVersion` field -- [ ] `loadConfig()` in `config.ts` loads `appVersion` from `CDK_APP_VERSION` env var or CDK context -- [ ] `applyStandardTags()` adds a `Version` tag with the value from `config.appVersion` to every stack -- [ ] The `Version` tag is applied to all resources across all 7 stacks (Infrastructure, App API, Inference API, Frontend, Gateway, RAG Ingestion) -- [ ] `scripts/common/load-env.sh` exports `CDK_APP_VERSION` by reading the VERSION file -- [ ] All `synth.sh` and `deploy.sh` scripts pass `--context appVersion=...` to CDK commands - ---- - -## Requirement 9: PR Version Gate - -### User Story -As a team lead, I want PRs to `main` blocked if the VERSION file hasn't been bumped or manifests are out of sync, so we never merge unversioned changes to production. - -### Acceptance Criteria -- [ ] A workflow exists at `.github/workflows/version-check.yml` that triggers on all PRs to `main` -- [ ] The workflow has no path filters — it runs on every PR regardless of files changed -- [ ] The workflow fails if the VERSION file content is identical to `main` branch (version not bumped) -- [ ] The workflow fails if `sync-version.sh --check` exits non-zero (manifests out of sync) -- [ ] Both checks run regardless of the other's result (developer sees all failures at once) -- [ ] The workflow requires no AWS credentials, Docker, or dependency installation (bash + git only) -- [ ] The workflow job name is suitable for use as a required status check in branch protection settings - ---- - -## Requirement 10: Git Tagging - -### User Story -As a developer, I want git tags created automatically on successful deploys to `main`, so I can reference specific releases and roll back if needed. - -### Acceptance Criteria -- [ ] After successful deploy on `main`, CI creates an annotated git tag `v` (e.g. `v1.0.0-beta.1`) -- [ ] The tagging step is idempotent — it skips if the tag already exists -- [ ] Tags are not created on `develop` or PR branches -- [ ] The CI workflow has `contents: write` permission to push tags -- [ ] The tag message includes the version string (e.g. `"Release 1.0.0-beta.1"`) - ---- - -## Requirement 11: AI Assistant Versioning Guides - -### User Story -As a developer using AI coding assistants, I want the assistants to already know how to bump the version, so I don't have to explain the process each time. - -### Acceptance Criteria -- [ ] A Claude Code skill exists at `.claude/skills/versioning/SKILL.md` with concise version bump instructions -- [ ] A Cursor rule exists at `.cursor/rules/versioning.mdc` with `alwaysApply: true` and concise version bump instructions -- [ ] A Kiro steering file exists at `.kiro/steering/versioning.md` (always included, no frontmatter) with concise version bump instructions -- [ ] All three files contain the same core information: VERSION file location, SemVer format, sync script command, PR gate behavior, and that CI handles the rest -- [ ] Each file is under ~20 lines of content (quick reference, not a tutorial) diff --git a/.kiro/specs/versioning-strategy/tasks.md b/.kiro/specs/versioning-strategy/tasks.md deleted file mode 100644 index 0b0da1a8..00000000 --- a/.kiro/specs/versioning-strategy/tasks.md +++ /dev/null @@ -1,175 +0,0 @@ -# Implementation Plan: Versioning Strategy - -## Overview - -Implement a unified versioning strategy for the monorepo using a single `VERSION` file as the source of truth. The version flows through a sync script, Docker builds, CI/CD workflows, health endpoints, frontend config, AWS resource tags, a PR gate, git tags, and AI assistant guides. Tasks are ordered so each step builds on the previous — starting with the VERSION file and sync script, then wiring version into backend, Docker, infrastructure, frontend, CI/CD, and finally the PR gate and AI guides. - -## Tasks - -- [x] 1. Create VERSION file and sync script - - [x] 1.1 Create the VERSION file at the repo root - - Create `VERSION` with content `1.0.0-beta.1` (single line, no `v` prefix, no trailing whitespace) - - Validate it matches SemVer regex: `^[0-9]+\.[0-9]+\.[0-9]+(-[a-zA-Z0-9.]+)?$` - - _Requirements: 1.1, 1.2, 1.3, 1.4, 1.5, 1.6_ - - - [x] 1.2 Create `scripts/common/sync-version.sh` - - Read VERSION file, validate format (exit with error if missing or malformed) - - Update `version` field in `backend/pyproject.toml` via sed - - Update `version` field in `frontend/ai.client/package.json` via sed or jq - - Update `version` field in `infrastructure/package.json` via sed or jq - - Implement `--check` mode that exits non-zero on drift without modifying files - - Use `set -euo pipefail` for error handling - - _Requirements: 2.1, 2.2, 2.3, 2.4, 2.5, 2.6, 2.7, 2.8_ - - - [ ]* 1.3 Write tests for sync-version.sh - - Test sync mode updates all three manifests correctly - - Test `--check` mode detects drift and exits non-zero - - Test `--check` mode does not modify files - - Test error handling for missing or malformed VERSION file - - _Requirements: 2.5, 2.6, 2.7_ - -- [x] 2. Update backend health endpoints to expose version - - [x] 2.1 Update App API health endpoint and FastAPI app version - - Modify `backend/src/apis/app_api/health/health.py` to read `APP_VERSION` env var - - Include `"version"` field in `/health` response, fallback to `"unknown"` - - Update `backend/src/apis/app_api/main.py` FastAPI `version` parameter to read from `APP_VERSION` env var - - Remove hardcoded `"2.0.0"` version string - - _Requirements: 3.1, 3.3, 3.4, 3.5_ - - - [x] 2.2 Update Inference API ping endpoint and FastAPI app version - - Modify `backend/src/apis/inference_api/chat/routes.py` to include `"version"` field in `/ping` response - - Read from `APP_VERSION` env var, fallback to `"unknown"` - - Update `backend/src/apis/inference_api/main.py` FastAPI `version` parameter to read from `APP_VERSION` env var - - Remove any hardcoded version strings - - _Requirements: 3.2, 3.3, 3.4, 3.5_ - - - [ ]* 2.3 Write unit tests for health endpoint versioning - - Test `/health` returns version from `APP_VERSION` env var - - Test `/ping` returns version from `APP_VERSION` env var - - Test both endpoints return `"unknown"` when env var is not set - - _Requirements: 3.1, 3.2, 3.3_ - -- [x] 3. Checkpoint - Ensure all tests pass - - Ensure all tests pass, ask the user if questions arise. - -- [x] 4. Update Dockerfiles and build scripts for version injection - - [x] 4.1 Add `APP_VERSION` build arg to all three Dockerfiles - - Add `ARG APP_VERSION=unknown` and `ENV APP_VERSION=${APP_VERSION}` to `backend/Dockerfile.app-api` - - Add `ARG APP_VERSION=unknown` and `ENV APP_VERSION=${APP_VERSION}` to `backend/Dockerfile.inference-api` - - Add `ARG APP_VERSION=unknown` and `ENV APP_VERSION=${APP_VERSION}` to `backend/Dockerfile.rag-ingestion` - - _Requirements: 4.1, 4.2, 4.3, 4.5_ - - - [x] 4.2 Update build scripts to pass `--build-arg APP_VERSION` - - Update `scripts/stack-app-api/build.sh` to read VERSION file and pass `--build-arg APP_VERSION=...` - - Update `scripts/stack-inference-api/build.sh` to read VERSION file and pass `--build-arg APP_VERSION=...` - - _Requirements: 4.4_ - - - [x] 4.3 Update push-to-ecr scripts for dual-tagging (semver + SHA) - - Update `scripts/stack-app-api/push-to-ecr.sh` to push both semver and SHA tags - - Update `scripts/stack-inference-api/push-to-ecr.sh` to push both semver and SHA tags - - Update `scripts/stack-rag-ingestion/push-to-ecr.sh` to push both semver and SHA tags (if exists) - - Update SSM parameter writes to store semver tag instead of SHA tag - - _Requirements: 5.1, 5.2, 5.3, 5.4, 5.5, 5.6_ - -- [x] 5. Update infrastructure for version tagging and frontend config - - [x] 5.1 Add `appVersion` to CDK config and `applyStandardTags()` - - Add `appVersion` field to `AppConfig` interface in `infrastructure/lib/config.ts` - - Load `appVersion` from `CDK_APP_VERSION` env var or CDK context (`appVersion`) in `loadConfig()` - - Add `Version` tag in `applyStandardTags()` using `config.appVersion` - - This automatically tags all resources across all 7 stacks - - _Requirements: 8.1, 8.2, 8.3, 8.4_ - - - [x] 5.2 Update `load-env.sh` and deploy scripts to pass version to CDK - - Update `scripts/common/load-env.sh` to export `CDK_APP_VERSION` from VERSION file - - Update all `synth.sh` and `deploy.sh` scripts to pass `--context appVersion=...` to CDK commands - - _Requirements: 8.5, 8.6_ - - - [x] 5.3 Add version to CDK `FrontendStack` config.json generation - - Update `infrastructure/lib/frontend-stack.ts` to include `version` in the generated `config.json` - - Read version from `config.appVersion` (already loaded in 5.1) - - _Requirements: 7.5, 7.6_ - -- [x] 6. Update frontend to display version - - [x] 6.1 Add `version` to `RuntimeConfig` and `ConfigService` - - Add `version` field to `RuntimeConfig` interface in `config.service.ts` - - Add a `version` computed signal to `ConfigService` that returns the version from config - - _Requirements: 7.1, 7.2_ - - - [x] 6.2 Add version fallbacks to environment files - - Add `version: 'dev'` to `frontend/ai.client/src/environments/environment.ts` - - Add `version: ''` to `frontend/ai.client/src/environments/environment.production.ts` - - _Requirements: 7.3, 7.4_ - - - [x] 6.3 Display version in the frontend UI - - Add version display to a visible location (sidebar footer, header tooltip, or settings page) - - Read version from `ConfigService.version` signal - - _Requirements: 7.7_ - -- [x] 7. Checkpoint - Ensure all tests pass - - Ensure all tests pass, ask the user if questions arise. - -- [x] 8. Update CI/CD workflows for version integration - - [x] 8.1 Update `app-api.yml` workflow - - Add step to read VERSION file into `APP_VERSION` output in `build-docker` job - - Pass `--build-arg APP_VERSION=$APP_VERSION` to Docker build - - Push both semver and SHA tags to ECR - - Pass version to CDK deploy via `CDK_APP_VERSION` env var or `--context appVersion` - - _Requirements: 6.1, 6.4, 6.6_ - - - [x] 8.2 Update `inference-api.yml` workflow - - Add step to read VERSION file into `APP_VERSION` output in `build-docker` job - - Pass `--build-arg APP_VERSION=$APP_VERSION` to Docker build - - Push both semver and SHA tags to ECR - - Pass version to CDK deploy via `CDK_APP_VERSION` env var or `--context appVersion` - - _Requirements: 6.2, 6.4, 6.6_ - - - [x] 8.3 Update `rag-ingestion.yml` workflow - - Add step to read VERSION file into `APP_VERSION` output in `build-docker` job - - Pass `--build-arg APP_VERSION=$APP_VERSION` to Docker build - - Push both semver and SHA tags to ECR - - _Requirements: 6.3, 6.4_ - - - [x] 8.4 Update `frontend.yml` workflow - - Add step to read VERSION file into `APP_VERSION` - - Pass version as CDK context (`--context appVersion=$APP_VERSION`) during deploy - - _Requirements: 6.5_ - -- [x] 9. Create PR version gate workflow - - [x] 9.1 Create `.github/workflows/version-check.yml` - - Trigger on all PRs to `main` with no path filters - - Fetch `main` branch for comparison - - Check 1: Fail if VERSION file content is identical to `main` (version not bumped) - - Check 2: Fail if `sync-version.sh --check` exits non-zero (manifests out of sync) - - Run both checks regardless of the other's result (not fail-fast) - - Require no AWS credentials, Docker, or dependency installation (bash + git only) - - Use a job name suitable for required status check in branch protection - - _Requirements: 9.1, 9.2, 9.3, 9.4, 9.5, 9.6, 9.7_ - -- [x] 10. Add git tagging to CI - - [x] 10.1 Add git tag creation step to the `app-api.yml` workflow (or a dedicated release workflow) - - After successful deploy on `main`, create annotated git tag `v` if it doesn't exist - - Tag message: `"Release "` - - Skip if tag already exists (idempotent) - - Only run on `main` branch (not `develop` or PR branches) - - Ensure workflow has `contents: write` permission - - _Requirements: 10.1, 10.2, 10.3, 10.4, 10.5_ - -- [x] 11. Create AI assistant versioning guides - - [x] 11.1 Create all three AI assistant guide files - - Create `.claude/skills/versioning/SKILL.md` with concise version bump instructions - - Create `.cursor/rules/versioning.mdc` with `alwaysApply: true` frontmatter and concise version bump instructions - - Create `.kiro/steering/versioning.md` (no frontmatter) with concise version bump instructions - - All three contain identical core info: VERSION file location, SemVer format, sync script command, PR gate behavior, CI handles the rest - - Each file under ~20 lines of content - - _Requirements: 11.1, 11.2, 11.3, 11.4, 11.5_ - -- [x] 12. Final checkpoint - Ensure all tests pass - - Ensure all tests pass, ask the user if questions arise. - -## Notes - -- Tasks marked with `*` are optional and can be skipped for faster MVP -- Each task references specific requirements for traceability -- Checkpoints ensure incremental validation -- The design uses Bash, Python, TypeScript, and YAML — no pseudocode language selection needed -- All runtime commands must execute inside the Docker container via `docker compose exec dev` diff --git a/.kiro/steering/cors-configuration.md b/.kiro/steering/cors-configuration.md new file mode 100644 index 00000000..4449ab9a --- /dev/null +++ b/.kiro/steering/cors-configuration.md @@ -0,0 +1,80 @@ +--- +inclusion: fileMatch +fileMatchPattern: ["infrastructure/lib/*-stack.ts", "infrastructure/lib/config.ts", "infrastructure/test/cors*", "backend/src/apis/*/main.py", ".github/workflows/*.yml", "scripts/common/load-env.sh"] +--- + +# CORS Configuration + +## Two-Layer Model + +CORS origins are built from exactly two sources, applied consistently across every stack: + +1. **CDK_DOMAIN_NAME** (required for production) — auto-applied as `https://{value}` to every CORS consumer. This is the primary domain of the application. +2. **CDK_CORS_ORIGINS** (optional) — additional origins appended globally. Use for localhost during local dev or extra domains. + +localhost is NOT auto-included. For local development, set `CDK_CORS_ORIGINS=http://localhost:4200`. + +## Per-Section Extras + +Each stack can optionally append additional origins via section-specific env vars: + +| Env Var | Stack | Config Field | +|---|---|---| +| `CDK_APP_API_CORS_ORIGINS` | App API | `appApi.additionalCorsOrigins` | +| `CDK_INFERENCE_API_CORS_ORIGINS` | Inference API | `inferenceApi.additionalCorsOrigins` | +| `CDK_FRONTEND_CORS_ORIGINS` | Frontend | `frontend.additionalCorsOrigins` | +| `CDK_FILE_UPLOAD_CORS_ORIGINS` | Infrastructure (file upload S3) | `fileUpload.additionalCorsOrigins` | +| `CDK_RAG_CORS_ORIGINS` | RAG Ingestion (S3) | `ragIngestion.additionalCorsOrigins` | +| `CDK_ASSISTANTS_CORS_ORIGINS` | Assistants | `assistants.additionalCorsOrigins` | +| `CDK_FINE_TUNING_CORS_ORIGINS` | SageMaker Fine-Tuning (S3) | `fineTuning.additionalCorsOrigins` | + +## Shared Helper + +All stacks use `buildCorsOrigins(config, additionalOrigins?)` from `config.ts`: + +```typescript +import { buildCorsOrigins } from './config'; + +// Global origins only (domain + CDK_CORS_ORIGINS) +const origins = buildCorsOrigins(config); + +// Global + section-specific extras +const origins = buildCorsOrigins(config, config.ragIngestion.additionalCorsOrigins); +``` + +For container env vars (Fargate, AgentCore Runtime): +```typescript +CORS_ORIGINS: buildCorsOrigins(config, config.appApi.additionalCorsOrigins).join(','), +``` + +For S3 bucket CORS rules: +```typescript +cors: [{ allowedOrigins: buildCorsOrigins(config, config.fileUpload?.additionalCorsOrigins) }] +``` + +## Python Backend + +Both FastAPI apps read `CORS_ORIGINS` env var (set by CDK): + +```python +_cors_origins = os.environ.get("CORS_ORIGINS", "").split(",") +app.add_middleware(CORSMiddleware, allow_origins=[o.strip() for o in _cors_origins if o.strip()]) +``` + +## Flow + +``` +GitHub vars.CDK_DOMAIN_NAME + vars.CDK_CORS_ORIGINS + → workflow job-level env (MUST be job-level, not workflow-level) + → scripts/common/load-env.sh (--context domainName, --context corsOrigins) + → infrastructure/lib/config.ts (corsOrigins = "https://{domainName}" + extras) + → buildCorsOrigins(config, sectionExtras?) → string[] + → S3 CORS rules / container CORS_ORIGINS env var +``` + +## Critical Rules + +- **NEVER** put `vars.*` in workflow-level `env:` — they resolve to empty strings. Always use job-level `env:` on jobs with `environment:` set. +- **NEVER** hardcode localhost or `*` as CORS origins. +- **EVERY** workflow that runs `synth` or `deploy` MUST have `CDK_DOMAIN_NAME` and `CDK_CORS_ORIGINS` in its job-level env. +- **EVERY** new stack that needs CORS must use `buildCorsOrigins()`. diff --git a/.kiro/steering/devops.md b/.kiro/steering/devops.md index eb2f6871..3920d13f 100644 --- a/.kiro/steering/devops.md +++ b/.kiro/steering/devops.md @@ -215,20 +215,22 @@ cdk deploy StackName \ **File**: `.github/workflows/.yml` -Add to the `env:` section at workflow level: - -- **Secrets** (sensitive data): Use `secrets.` -- **Variables** (non-sensitive config): Use `vars.` +Add to the `env:` section **at the job level** (NOT the workflow top-level). Environment-scoped variables (`vars.*`) and secrets (`secrets.*`) require the `environment:` key, which is set on individual jobs. Placing them at the workflow top-level will silently resolve to empty strings. ```yaml -env: - # CDK Configuration - from GitHub Variables - CDK_ALB_SUBDOMAIN: ${{ vars.CDK_ALB_SUBDOMAIN }} - - # CDK Secrets - from GitHub Secrets - CDK_CERTIFICATE_ARN: ${{ secrets.CDK_CERTIFICATE_ARN }} +jobs: + deploy: + environment: production + env: + # CDK Configuration - from GitHub Variables (MUST be at job level) + CDK_ALB_SUBDOMAIN: ${{ vars.CDK_ALB_SUBDOMAIN }} + + # CDK Secrets - from GitHub Secrets + CDK_CERTIFICATE_ARN: ${{ secrets.CDK_CERTIFICATE_ARN }} ``` +**CRITICAL**: Only non-sensitive, non-environment-scoped values (like `CDK_REQUIRE_APPROVAL: never`) belong in the workflow-level `env:`. Everything that reads from `vars.*` or `secrets.*` MUST be in a job-level `env:` block on a job that has `environment:` set. + **When to use Secrets vs Variables:** - **Secrets**: API keys, passwords, certificate ARNs, AWS credentials - **Variables**: Project names, regions, non-sensitive config diff --git a/.kiro/steering/release-notes.md b/.kiro/steering/release-notes.md new file mode 100644 index 00000000..8f61854f --- /dev/null +++ b/.kiro/steering/release-notes.md @@ -0,0 +1,91 @@ +--- +inclusion: fileMatch +fileMatchPattern: 'RELEASE_NOTES.md' +--- + +# Writing Release Notes + +## Branch Model & Why This Is Hard + +This repo uses a squash-merge workflow: `develop` accumulates feature branches via merge commits, and when a release is cut, `develop` is squash-merged into `main`. This means `main` and `develop` have **divergent git histories** — you cannot do a simple `git log main..develop` to get a clean diff. Commit SHAs on `main` don't correspond to anything on `develop`. + +## How to Identify What Changed + +### Step 1: Find the boundary + +Look at the last squash-merge commit on `main` to determine when the previous release was cut: + +```bash +git log main --oneline -5 +``` + +Then find the corresponding release tag or date. Use that date as your boundary. + +### Step 2: List commits on develop since the boundary + +```bash +git log develop --oneline --no-merges --since="" +``` + +This gives you the raw commit list, but **do not rely solely on commit messages**. Dependabot commits are usually accurate, but human commits often have vague or incomplete messages. + +### Step 3: Inspect the actual code changes + +For every non-trivial commit, read the diff or at minimum the `--stat` output: + +```bash +git show --stat +git show --no-patch # full commit message +``` + +For feature commits, read the changed files to understand what was actually built — not just what the message claims. Look for: + +- New API endpoints (routes files) +- New or modified models/schemas +- New frontend pages or components +- Infrastructure changes (CDK stacks, config) +- New test files (indicates new functionality) +- Dependency changes (pyproject.toml, package.json) + +### Step 4: Group by category + +Organize changes into the standard sections used by prior releases. Review the existing release notes in the file for the established pattern. Typical sections include: + +- **Highlights** — 2-3 sentence summary of the release theme +- **New features** — each gets its own H2 with subsections for backend/frontend/infra +- **Bug fixes** — concise list +- **Security** — vulnerability patches, CodeQL fixes +- **Dependency upgrades** — table format +- **CI/CD improvements** — workflow changes +- **Test fixes** — test-only changes +- **Deployment notes** — what operators need to do differently + +## Writing Style + +- Match the tone and depth of the existing release notes in the file. They are detailed and technical — written for developers who will deploy and maintain this system. +- Every feature section should explain **what** changed, **why** it matters, and **how** it works at a technical level. +- Use specific file names, endpoint paths, and class names when relevant. +- Include line counts for large test additions (e.g., "4,200+ lines of new tests"). +- For dependency upgrades, use a markdown table with From/To columns. +- The Highlights section should read as a standalone summary — someone skimming only that paragraph should understand the release. + +## Header Format + +```markdown +# Release Notes — v1.0.0-beta.XX + +**Release Date:** +**Previous Release:** v1.0.0-beta.XX-1 () + +--- +``` + +The new release goes at the **top** of the file. Do not modify previous release sections. + +## Common Pitfalls + +- **Don't trust commit messages blindly.** A commit titled "fix: update models" might contain a new feature with 800 lines of code. Always check the diff. +- **Don't miss Dependabot PRs.** They often bump 10+ packages in a single grouped PR. Check `pyproject.toml`, `package.json`, and workflow files for version changes. +- **Don't forget CI/CD changes.** Workflow file modifications (`.github/workflows/`) are easy to overlook but important for operators. +- **Don't duplicate sections.** If a feature spans backend + frontend + infra, keep it in one section with subsections — don't scatter it across the document. +- **Check the VERSION file and README badge.** These should already be updated via `sync-version.sh` before the release notes are finalized. diff --git a/.kiro/steering/structure.md b/.kiro/steering/structure.md index dafcb41a..f1ff5eea 100644 --- a/.kiro/steering/structure.md +++ b/.kiro/steering/structure.md @@ -9,7 +9,6 @@ agentcore-public-stack/ ├── infrastructure/ # AWS CDK infrastructure code ├── docs/ # Documentation and specifications ├── scripts/ # Deployment and build scripts -└── deploy.sh # Cloud deployment script ``` ## Backend Structure diff --git a/CLAUDE.MD b/CLAUDE.MD index d9eb4a55..a736d9d7 100644 --- a/CLAUDE.MD +++ b/CLAUDE.MD @@ -1,373 +1,105 @@ # CLAUDE.md -This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. - -## Project Overview - Production-ready multi-agent conversational AI system built with AWS Bedrock AgentCore and Strands Agents. -**Tech Stack:** -- **Frontend**: Angular v21, TypeScript, Tailwind v4.1+ CSS -- **Backend**: Python 3.13+, FastAPI -- **Agent Framework**: Strands Agents (AWS Bedrock) -- **Cloud Services**: AWS Bedrock AgentCore (Runtime, Memory, Gateway, Code Interpreter, Browser) - -## Build and Run Commands +## Build & Run ### Backend - ```bash cd backend - -# Install uv (one-time) -curl -LsSf https://astral.sh/uv/install.sh | sh - -# Install for app_api only -uv sync - -# Install for inference_api (with AgentCore) -uv sync --extra agentcore - -# Install all including dev tools -uv sync --extra agentcore --extra dev - -# Run App API (port 8000) -cd src/apis/app_api && uv run python main.py - -# Run Inference API (port 8001) -cd src/apis/inference_api && uv run python main.py - -# Run tests -uv run python -m pytest tests/ -v +uv sync --extra agentcore --extra dev # All deps +uv run python -m pytest tests/ -v # Tests +cd src/apis/app_api && uv run python main.py # App API (port 8000) +cd src/apis/inference_api && uv run python main.py # Inference API (port 8001) ``` ### Frontend - ```bash cd frontend/ai.client npm install -npm run start # Dev server (port 4200) -npm run build # Production build -npm test # Run tests (Vitest) +npm run start # Dev server (port 4200) +npm test # Tests (Vitest via Analog.js) ``` -### Infrastructure (CDK) - +### Infrastructure ```bash cd infrastructure npm install -npm run build # Compile TypeScript -npx cdk synth # Generate CloudFormation -npx cdk deploy --all # Deploy all stacks -npx cdk diff # Compare changes +npm run build +npx cdk synth +npx cdk deploy --all ``` -## Project Structure +## Key Conventions -``` -/ -├── backend/ -│ └── src/ -│ ├── agents/main_agent/ # Core agent implementation -│ │ ├── core/ # Agent factory, model config, system prompt -│ │ ├── session/ # Turn-based session management -│ │ ├── streaming/ # SSE event processing & formatting -│ │ └── tools/ # Tool registry & local tools -│ └── apis/ -│ ├── app_api/ # Main application API (port 8000) -│ ├── inference_api/ # Bedrock inference endpoint (port 8001) -│ └── shared/ # Shared utilities & error handling -├── frontend/ai.client/ # Angular SPA -│ └── src/app/ -│ ├── auth/ # OIDC/Entra ID authentication -│ ├── session/ # Chat UI & services -│ ├── admin/ # Admin dashboard pages -│ └── services/ # State management, HTTP services -└── infrastructure/ # AWS CDK infrastructure - └── lib/ # Stack definitions -``` - -## Key Architecture Patterns - -### Multi-Protocol Tool Architecture - -| Protocol | Location | Examples | Auth | -|----------|----------|----------|------| -| Direct call | `agents/main_agent/tools/` | Weather, Calculator | N/A | -| AWS SDK | `agents/main_agent/tools/` | Code Interpreter, Browser | IAM | -| MCP + SigV4 | Cloud Lambda (Gateway) | Wikipedia, ArXiv, Finance | AWS SigV4 | -| A2A | Cloud Runtime (WIP) | Report Writer | AgentCore auth | - -### Turn-based Session Management - -**File:** `backend/src/agents/main_agent/session/turn_based_session_manager.py` +- **Deploy order:** Infrastructure → Gateway → App API → Inference API → Frontend +- **Admin endpoints** go under `/admin//`, user-facing under `//` +- **Errors stream as assistant messages** via SSE (not HTTP error codes) +- **Signal-based state** throughout frontend (`signal()`, `computed()`) +- **All dependencies use exact version pins** — no `^`, `~`, or `>=` +- **Never install packages without explicit user approval** -Messages are buffered within a turn to reduce AgentCore Memory API calls: -- Pass-through mode: Messages sent individually -- Message count initialized once at startup -- Supports session cancellation via `cancelled` flag - -### Prompt Caching Strategy - -**File:** `backend/src/agents/main_agent/core/model_config.py` - -Automatic prompt caching (Bedrock only) via `CacheConfig(strategy="auto")` passed to BedrockModel. -The SDK automatically injects cache points at the end of the last assistant message. - -### SSE Event Types +## SSE Event Types | Event | Purpose | |-------|---------| | `message_start` | Start of assistant response | | `content_block_start/delta/stop` | Streaming content | | `message_stop` | End of message | -| `tool_use` | Tool invocation | -| `tool_result` | Tool execution result | +| `tool_use` / `tool_result` | Tool invocation and result | | `stream_error` | Conversational error | | `done` | Stream complete | -## Backend API Route Conventions - -All admin endpoints MUST be under the `/admin/` prefix: - -| Pattern | Example | Use For | -|---------|---------|---------| -| `/resource/` | `/tools/` | User-facing endpoints | -| `/admin/resource/` | `/admin/tools/` | Admin CRUD | - -**Correct:** `GET /admin/tools/`, `PUT /admin/tools/{id}` -**Incorrect:** ~~`GET /tools/admin/`~~ - -## Authentication Flow - -**Frontend:** OIDC with Entra ID + PKCE - -1. `login()` → Backend `/auth/login` → Entra ID authorization -2. Callback → `/auth/token` exchange → Store tokens in localStorage -3. `authInterceptor` adds Bearer token, auto-refreshes on expiry -4. `authGuard` protects routes - -## Error Handling - -Errors stream as assistant messages (better UX than HTTP errors): -- `ConversationalErrorEvent` for user-friendly markdown errors -- Errors persisted to session history -- Fail-open approach for RBAC/quota errors - -## Frontend Guidelines - -### Icon-Only Buttons (Accessibility Required) - -Buttons with only icons MUST include a tooltip: - -```html - -``` - -### State Management - -Signal-based state throughout (`signal()`, `computed()`) - -## Tailwind CSS v4.1+ Rules - -See `.cursor/rules/tailwind.mdc` for comprehensive guidelines. Key points: - -### Breaking Changes (ALWAYS use v4 syntax) - -| ❌ Deprecated | ✅ Replacement | -|---------------|----------------| -| `bg-opacity-*` | `bg-black/50` | -| `bg-gradient-*` | `bg-linear-*` | -| `shadow-sm` | `shadow-xs` | -| `shadow` | `shadow-sm` | -| `rounded-sm` | `rounded-xs` | -| `rounded` | `rounded-sm` | -| `leading-*` | `text-base/7` (line-height modifier) | -| `space-x-*` in flex | `gap-*` | - -### Layout Rules - -- Always use `gap-*` in flex/grid, never `space-x-*` or `space-y-*` -- Use `min-h-dvh` instead of `min-h-screen` (mobile Safari bug) -- Use `size-*` over separate `w-*` and `h-*` for equal dimensions -- Never use `@apply` - -## CDK Infrastructure - -**Deploy order:** InfrastructureStack → AppApiStack → InferenceApiStack → FrontendStack → GatewayStack - -### DynamoDB Tables (AppApiStack) - -| Table | Purpose | -|-------|---------| -| `user-quotas` | Quota tier assignments | -| `quota-events` | Quota usage events | -| `sessions-metadata` | Message-level cost tracking | -| `user-cost-summary` | Aggregated user costs | -| `managed-models` | Model pricing/config | -| `users` | User profiles from JWT | -| `app-roles` | RBAC role definitions | - -## Environment Configuration +## Multi-Protocol Tool Architecture -### Backend (.env) +| Protocol | Location | Auth | +|----------|----------|------| +| Direct call | `agents/main_agent/tools/` | N/A | +| AWS SDK | `agents/main_agent/tools/` | IAM | +| MCP + SigV4 | Cloud Lambda (Gateway) | AWS SigV4 | +| A2A | Cloud Runtime | AgentCore auth | -Located at `backend/src/.env`: +## Cross-Package Contracts -```bash -AWS_REGION=us-west-2 -AWS_PROFILE= -AGENTCORE_MEMORY_ID= -AGENTCORE_PROJECT_PREFIX= -DYNAMODB_AUTH_PROVIDERS_TABLE_NAME=-auth-providers -AUTH_PROVIDER_SECRETS_ARN= -# ... plus all DynamoDB table names, S3 buckets, etc. -``` - -### Frontend (environment.ts) - -Located at `frontend/ai.client/src/environments/`: - -```typescript -export const environment = { - production: false, - appApiUrl: 'http://localhost:8000', - inferenceApiUrl: 'http://localhost:8001', - enableAuthentication: true -}; -``` - -## Local Development Gotchas - -### AWS_PROFILE override - -`load_dotenv` uses `override=True` so the `.env` file's `AWS_PROFILE` wins over your shell environment. This is intentional — without it, a shell-level `AWS_PROFILE` pointing to a different account causes `ResourceNotFoundException` errors on all DynamoDB tables because boto3 connects to the wrong AWS account. - -### Auth Provider Secrets - -OIDC client secrets (e.g., Entra ID) are stored in AWS Secrets Manager, NOT in `.env`. The secret at `AUTH_PROVIDER_SECRETS_ARN` must be a JSON object keyed by provider ID: - -```json -{"entra-id": "", "other-provider": ""} -``` - -After a fresh stack deployment, the CDK-generated secret only contains a placeholder. You must manually add provider client secrets: - -```bash -aws secretsmanager put-secret-value \ - --secret-id \ - --secret-string '{"entra-id": ""}' -``` - -The auth provider config itself (client ID, issuer URL, endpoints) lives in the `auth-providers` DynamoDB table and is managed via the admin API. - -## Debugging - -**Tool not appearing:** Check export in `__init__.py`, RBAC permissions, `enabled_tools` list, ToolRegistry registration - -**Session not persisting:** Check AgentCore Memory config, session_id, TurnBasedSessionManager flush - -**SSE stream disconnecting:** Check 600-second timeout, client connection, quota exceeded events - -## Coding Standards - -### Python (Backend) -- **Naming**: `snake_case` for functions, variables, modules; `PascalCase` for classes -- **Imports**: Standard library first, then third-party, then local — separated by blank lines -- **Type hints**: Required on all function signatures -- **Strings**: Use f-strings for interpolation, double quotes preferred -- **Formatter**: Follow PEP 8 conventions - -### TypeScript (Frontend & CDK) -- **Naming**: `camelCase` for functions/variables/properties; `PascalCase` for classes, interfaces, and types; `UPPER_SNAKE_CASE` for constants -- **Interfaces**: Prefix with `I` only if project convention exists, otherwise plain `PascalCase` -- **Access modifiers**: Use `private`/`protected`/`public` explicitly on class members -- **Strict mode**: TypeScript strict mode is enabled — no `any` unless absolutely necessary - -### General -- No commented-out code in commits -- No `console.log` / `print()` left in production code -- Prefer early returns over deep nesting - -## Testing - -### Backend -- Run: `python -m pytest tests/ -v` from the `backend/` directory -- Test files: `test_.py` in `tests/` mirroring the source structure -- Use `pytest` fixtures for shared setup - -### Frontend -- Run: `npm test` from `frontend/ai.client/` (uses `ng test` under the hood) -- **Do NOT run Vitest directly** — always use `ng test` or `npm test` -- Scaffold tests using the Angular CLI (`ng generate` creates `.spec.ts` files automatically) -- Test files: `.spec.ts` co-located with the component - -### CDK -- Run: `npm test` from `infrastructure/` -- Snapshot tests for stack outputs - -## Git & Branching - -- **Branch from**: `develop` (never branch from `main` for feature work) -- **Branch naming**: `feature/` (e.g., `feature/add-quota-dashboard`) -- **Commits**: Use conventional commit messages — `feat:`, `fix:`, `refactor:`, `docs:`, `test:`, `chore:` -- **PRs**: Target `develop` for feature branches; `main` is updated via release merges only -- **Keep commits focused**: One logical change per commit - -## Dependency Management - -- **Never install new packages without explicit user approval.** Always ask first. -- When proposing a new dependency, explain why it's needed and whether an existing package already covers the use case. -- Backend dependencies go in `backend/pyproject.toml` -- Frontend dependencies go in `frontend/ai.client/package.json` -- CDK dependencies go in `infrastructure/package.json` - -## Cross-Package Boundaries - -Frontend and backend MUST agree on a shared API schema — this is the contract between them. - -- When adding or modifying an API endpoint, define the request/response types on **both sides** before implementing -- Backend route handlers define the shape; frontend TypeScript interfaces must match +- Backend route handlers define the API shape; frontend TypeScript interfaces must match - Breaking changes to an endpoint require updating both packages in the same PR -- SSE event types (documented above) are part of the contract — changes must be coordinated +- SSE event types are part of the contract — changes must be coordinated ## File Creation Rules -Follow the existing organizational structure. Do not create new top-level directories or invent new patterns. - | Change Type | Where It Goes | |-------------|---------------| -| New backend API route | `backend/src/apis/app_api//` with router + models | +| New API route | `backend/src/apis/app_api//` | | New admin endpoint | `backend/src/apis/app_api/admin//` | | New agent tool | `backend/src/agents/main_agent/tools/` + register in `__init__.py` | -| New Angular page | `frontend/ai.client/src/app//pages//` | -| New Angular component | `frontend/ai.client/src/app//components//` | -| New Angular service | `frontend/ai.client/src/app//services/` or `src/app/services/` if shared | +| New Angular page | `frontend/ai.client/src/app//` | | New CDK stack | `infrastructure/lib/-stack.ts` | -| Shared backend utilities | `backend/src/apis/shared/` | +| Shared backend utils | `backend/src/apis/shared/` | + +## Debugging Quick Reference -When in doubt, look at how an existing similar feature is organized and follow that pattern. +- **Tool not appearing:** Check `__init__.py` export, RBAC permissions, `enabled_tools`, ToolRegistry +- **Session not persisting:** Check AgentCore Memory config, session_id, TurnBasedSessionManager flush +- **SSE stream disconnecting:** Check 600s timeout, client connection, quota exceeded events -## Constraints +## Coding Standards + +### Python +- `snake_case` functions/variables, `PascalCase` classes +- Type hints required on all function signatures +- No `print()` in production — use `logging` + +### TypeScript +- `camelCase` functions/variables, `PascalCase` classes/interfaces, `UPPER_SNAKE_CASE` constants +- Strict mode enabled — no `any` unless absolutely necessary -1. Only implement what's explicitly requested -2. Watch for injection vulnerabilities (command, XSS, SQL) -3. Consider token usage when modifying agent prompts -4. Maintain multimodal compatibility -5. Respect turn-based buffering patterns -6. Use correct protocol for tool type -7. Errors should stream as conversational messages +### General +- No commented-out code in commits +- Prefer early returns over deep nesting +- One logical change per commit using conventional commits (`feat:`, `fix:`, `chore:`, etc.) -## Known Limitations +## Git Workflow -- AgentCore Gateway requires cloud deployment (not available locally) -- AgentCore Memory uses local file storage in development -- A2A Report Writer tools are work in progress -- Stream timeout: 600 seconds +- Branch from `develop`, never `main` +- PRs target `develop`; `main` is updated via squash-merge releases only +- Branch naming: `feature/` diff --git a/CODE_REVIEW_TOKEN_STORAGE.md b/CODE_REVIEW_TOKEN_STORAGE.md deleted file mode 100644 index 3b3ee2e7..00000000 --- a/CODE_REVIEW_TOKEN_STORAGE.md +++ /dev/null @@ -1,216 +0,0 @@ -# Code Review: Token Storage Security - -**Date:** 2025-03-24 -**Scope:** `frontend/ai.client/src/app/auth/auth.service.ts`, `auth.interceptor.ts`, `auth.guard.ts` -**Severity Scale:** 🔴 Critical · 🟠 High · 🟡 Medium · 🟢 Low - ---- - -## Executive Summary - -The application currently stores OAuth access tokens, refresh tokens, and token expiry timestamps in `localStorage`. While the PKCE implementation and CSRF state handling are solid (using `sessionStorage` correctly for ephemeral flow data), the long-lived token storage strategy exposes the application to well-documented attack vectors. This review identifies specific vulnerabilities and proposes a phased migration path. - ---- - -## Current Implementation - -### What's Done Well - -- **PKCE with S256**: The `login()` flow correctly generates a cryptographic code verifier and SHA-256 challenge. State and code verifier are stored in `sessionStorage` (ephemeral, tab-scoped) — this is correct. -- **CSRF state validation**: `handleCallback()` verifies the `state` parameter before exchanging the authorization code. -- **Token expiry buffer**: `isTokenExpired()` uses a 60-second buffer to preemptively refresh, avoiding edge-case 401s. -- **Interceptor retry logic**: The HTTP interceptor handles expired tokens gracefully with a single retry after refresh. -- **No implicit flow**: The app uses Authorization Code + PKCE exclusively, which aligns with current IETF best practice (draft-ietf-oauth-browser-based-apps-26). - -### What's Stored Where - -| Data | Storage | Concern | -|------|---------|---------| -| `access_token` | `localStorage` | 🔴 Accessible to any JS in the origin | -| `refresh_token` | `localStorage` | 🔴 Long-lived credential exposed to XSS | -| `token_expiry` | `localStorage` | 🟡 Leaks session timing info | -| `auth_provider_id` | `localStorage` | 🟢 Non-sensitive display data | -| `auth_state` | `sessionStorage` | ✅ Correct — ephemeral CSRF token | -| `auth_code_verifier` | `sessionStorage` | ✅ Correct — ephemeral PKCE data | -| `auth_return_url` | `sessionStorage` | ✅ Correct — ephemeral navigation state | - ---- - -## Findings - -### 🔴 F-01: Refresh Token in localStorage - -**File:** `auth.service.ts:286` -```typescript -localStorage.setItem(this.refreshTokenKey, response.refresh_token); -``` - -**Risk:** A single XSS vulnerability anywhere in the origin gives an attacker the refresh token. Unlike access tokens (short-lived), a stolen refresh token grants the attacker the ability to mint new access tokens independently, potentially for hours or days, even after the user closes their browser. - -**References:** -- OWASP HTML5 Security Cheat Sheet: *"Do not store session identifiers in local storage as the data is always accessible by JavaScript. Cookies can mitigate this risk using the httpOnly flag."* -- IETF draft-ietf-oauth-browser-based-apps-26, Section 8.5: *"localStorage persists between page reloads as well as is shared across all tabs... localStorage does not protect against unauthorized access from malicious JavaScript."* -- Auth0 Refresh Token Best Practices: Refresh tokens in SPAs should use rotation with automatic reuse detection to limit blast radius. - -**Impact:** An attacker with XSS can silently exfiltrate the refresh token and use it from their own machine to generate access tokens. The user would have no indication of compromise. The attacker maintains access until the refresh token expires or is revoked. - ---- - -### 🔴 F-02: Access Token in localStorage - -**File:** `auth.service.ts:284` -```typescript -localStorage.setItem(this.tokenKey, response.access_token); -``` - -**Risk:** The access token is readable by any script running in the same origin. While access tokens are shorter-lived than refresh tokens, `localStorage` persists across tabs and browser restarts, meaning a token could remain available long after the user thinks they've left the application. - -**References:** -- IETF draft-ietf-oauth-browser-based-apps-26, Section 8.4: In-memory storage is preferred over persistent storage for access tokens, as it *"limits the exposure of the tokens to the current execution context only."* -- OWASP JWT Cheat Sheet, Token Sidejacking section: Recommends binding tokens to a browser fingerprint via HttpOnly cookies to prevent XSS-based theft. - ---- - -### 🟠 F-03: No Token Binding / Sidejacking Protection - -**Risk:** The tokens are pure bearer tokens with no binding to the browser session. If exfiltrated, they work from any HTTP client. The OWASP JWT Cheat Sheet recommends a "user context" fingerprint — a random value sent as an HttpOnly cookie with a SHA-256 hash embedded in the token — so that a stolen token is useless without the corresponding cookie. - -**Current state:** The application has no mechanism to detect or prevent token replay from a different client/device. - ---- - -### 🟠 F-04: Token Expiry Stored as Plaintext Timestamp - -**File:** `auth.service.ts:289` -```typescript -const expiryTime = Date.now() + response.expires_in * 1000; -localStorage.setItem(this.tokenExpiryKey, expiryTime.toString()); -``` - -**Risk:** An attacker (or malicious browser extension) can trivially modify this value to extend the perceived validity of a stolen token, bypassing the client-side expiry check. The server still validates expiry, but the client will continue sending the expired token without attempting a refresh, which could cause confusing UX failures. - -**Note:** This is a medium-severity issue because server-side validation is the real enforcement boundary. However, client-side expiry should not be trivially tamperable. - ---- - -### 🟡 F-05: localStorage Persists After Logout Intent - -**File:** `auth.service.ts:298-307` - -The `clearTokens()` method does remove tokens from `localStorage`, but if the browser crashes, the tab is force-closed, or the user simply closes the browser without clicking "logout," the tokens remain in `localStorage` indefinitely (until they expire server-side). `sessionStorage` would at least clear on tab close. - ---- - -### 🟡 F-06: id_token Received but Not Stored or Validated - -**File:** `auth.service.ts:7` -```typescript -id_token?: string; -``` - -The `TokenRefreshResponse` interface includes `id_token`, but the `storeTokens()` method silently discards it. If the ID token is being used elsewhere (e.g., decoded for user profile info), it should be validated (signature, issuer, audience, expiry). If it's not needed, the interface should document why it's ignored. - ---- - -### 🟡 F-07: Cross-Tab Token Synchronization Gap - -The `storeTokens()` method dispatches a custom `token-stored` event for same-tab notification, but `localStorage` changes in other tabs are only detectable via the native `storage` event. There's no listener for the `storage` event, meaning if a user has multiple tabs open and one tab refreshes the token, other tabs may continue using the old (now potentially rotated/invalid) token until they independently detect expiry. - ---- - -## Recommended Changes - -### Option A: Backend-For-Frontend (BFF) Pattern — Recommended - -This is the strongest option and is explicitly recommended by the IETF draft for *"business applications, sensitive applications, and applications that handle personal data."* AgentCore handles student data at an institution — this qualifies. - -**How it works:** -1. The App API (FastAPI) handles the entire OAuth code exchange server-side -2. Tokens are stored server-side, associated with a session ID -3. The browser receives only an HttpOnly, Secure, SameSite=Strict cookie containing the session ID -4. The App API proxies requests to the Inference API / resource servers, attaching the access token server-side -5. The frontend never sees or stores any OAuth tokens - -**What changes:** - -| Component | Change | -|-----------|--------| -| `auth.service.ts` | Remove all `localStorage` token operations. Login redirects to App API `/auth/login` endpoint. Session state tracked via cookie presence. | -| `auth.interceptor.ts` | Remove token attachment logic. Cookies are sent automatically. Handle 401 by redirecting to login. | -| `auth.guard.ts` | Check session via a lightweight `/auth/session` API call instead of inspecting local tokens. | -| App API | New `/auth/login`, `/auth/callback`, `/auth/session`, `/auth/logout` endpoints. Server-side token storage (DynamoDB or in-memory with Redis). | -| Cookie config | `HttpOnly`, `Secure`, `SameSite=Strict`, `__Host-` prefix, `Path=/` | - -**Mitigates:** F-01, F-02, F-03, F-04, F-05, F-07 - -**Trade-offs:** -- All API traffic to external resource servers must proxy through the BFF (adds latency, increases backend load) -- Requires server-side session storage infrastructure -- More complex deployment - ---- - -### Option B: Web Worker Token Isolation — Moderate Improvement - -If a full BFF is too large a change, isolating the refresh token in a Web Worker is the next best option. This is explicitly called out in the IETF draft (Section 8.3) as a practical pattern. - -**How it works:** -1. A dedicated Web Worker handles all token exchange and refresh operations -2. The refresh token never leaves the Web Worker's memory -3. The Web Worker provides the access token to the main thread on request -4. Access tokens are held in-memory only (closure variable), never in `localStorage` - -**What changes:** - -| Component | Change | -|-----------|--------| -| New `token-worker.ts` | Web Worker that performs code exchange, stores refresh token in its own scope, handles refresh flows | -| `auth.service.ts` | Communicates with the worker via `postMessage`. No `localStorage` for tokens. Access token held in a private variable. | -| `auth.interceptor.ts` | Gets token from `AuthService` in-memory variable instead of `localStorage` | - -**Mitigates:** F-01 (fully), F-02 (partially — access token still in main thread memory but not persisted), F-05 - -**Trade-offs:** -- Access token is still in-memory in the main thread (vulnerable to sophisticated XSS, but not to simple `localStorage` reads) -- Page refresh requires re-obtaining the access token from the worker (or re-triggering a silent auth flow) -- Does not protect against the "Acquisition and Extraction of New Tokens" attack (Section 5.1.3 of the IETF draft) — an attacker with XSS can still run their own OAuth flow - ---- - -### Option C: Minimum Viable Hardening — Quick Wins - -If neither Option A nor B is feasible short-term, these changes reduce risk with minimal refactoring: - -| # | Change | Addresses | -|---|--------|-----------| -| 1 | **Move tokens from `localStorage` to `sessionStorage`**. Tokens are scoped to the tab and cleared on browser close. This is a one-line change per `getItem`/`setItem` call. | F-05 | -| 2 | **Move refresh token to in-memory only** (private class variable). Accept that page refresh requires a silent re-auth or new login. Keep access token in `sessionStorage` for tab persistence. | F-01 | -| 3 | **Add `storage` event listener** to sync token changes across tabs, or invalidate stale tabs. | F-07 | -| 4 | **Validate or discard `id_token`** explicitly. If used, validate signature/claims. If not, remove from interface or add a comment. | F-06 | -| 5 | **Derive expiry from the token itself** (decode the JWT `exp` claim) rather than storing a separate tamperable timestamp. | F-04 | -| 6 | **Configure Cognito refresh token rotation** if not already enabled. Ensures a stolen refresh token is invalidated after one use. | F-01 | -| 7 | **Shorten access token lifetime** to 5-15 minutes (Cognito default is 60 min). Reduces the window of exploitation for stolen access tokens. | F-02 | - ---- - -## Prioritized Action Plan - -| Priority | Action | Effort | Impact | -|----------|--------|--------|--------| -| P0 | Move refresh token to in-memory storage (Option C, item 2) | Small | Eliminates the highest-risk finding | -| P0 | Enable Cognito refresh token rotation (Option C, item 6) | Config change | Defense-in-depth for refresh token theft | -| P1 | Move access token from `localStorage` to `sessionStorage` (Option C, item 1) | Small | Reduces persistence and cross-tab exposure | -| P1 | Shorten access token lifetime to 5-15 min (Option C, item 7) | Config change | Limits blast radius of stolen access tokens | -| P2 | Derive expiry from JWT `exp` claim (Option C, item 5) | Small | Removes tamperable client-side state | -| P2 | Add cross-tab token sync via `storage` event (Option C, item 3) | Small | Prevents stale token usage | -| P3 | Evaluate and plan BFF migration (Option A) | Large | Comprehensive long-term fix | - ---- - -## References - -1. [IETF draft-ietf-oauth-browser-based-apps-26](https://datatracker.ietf.org/doc/html/draft-ietf-oauth-browser-based-apps) — OAuth 2.0 for Browser-Based Applications (December 2025) -2. [OWASP HTML5 Security Cheat Sheet — Local Storage](https://cheatsheetseries.owasp.org/cheatsheets/HTML5_Security_Cheat_Sheet.html#local-storage) -3. [OWASP JWT Cheat Sheet — Token Sidejacking](https://cheatsheetseries.owasp.org/cheatsheets/JSON_Web_Token_for_Java_Cheat_Sheet.html#token-sidejacking) -4. [OWASP Session Management Cheat Sheet](https://cheatsheetseries.owasp.org/cheatsheets/Session_Management_Cheat_Sheet.html) -5. [Auth0 — Refresh Tokens: What They Are and When to Use Them](https://auth0.com/blog/refresh-tokens-what-are-they-and-when-to-use-them/) diff --git a/GEMINI.md b/GEMINI.md deleted file mode 100644 index 9c022924..00000000 --- a/GEMINI.md +++ /dev/null @@ -1,88 +0,0 @@ -# AgentCore Public Stack - Developer Context - -## Project Overview - -**Name:** AgentCore Public Stack -**Purpose:** A production-ready multi-agent conversational AI system using AWS Bedrock AgentCore and Strands Agents. -**Key Features:** -* **Multi-Agent Orchestration:** Uses Strands Agent. -* **MCP Tool Integration:** Connects to Wikipedia, ArXiv, Google Search, etc., via Model Context Protocol (MCP) and AgentCore Gateway. -* **Multimodal:** Supports text, images, and document inputs/outputs. -* **Memory:** Two-tier memory system (session-based short-term and persistent long-term). -* **Full-Stack:** Angular frontend, Python FastAPI backend, AWS CDK infrastructure. - -## Architecture & Tech Stack - -### Frontend (`frontend/ai.client`) -* **Framework:** Angular v21 -* **Styling:** Tailwind CSS v4.1 -* **Language:** TypeScript -* **State Management:** Signals, RxJS -* **Key Dependencies:** `@microsoft/fetch-event-source` (SSE), `marked` (Markdown), `mermaid`, `katex`. - -### Backend (`backend`) -* **Framework:** FastAPI (Python 3.9+) -* **AI Orchestration:** Strands Agents (`strands-agents`) -* **AWS SDK:** Boto3 -* **API Pattern:** - * `app_api`: Main application logic, chat, auth. - * `inference_api`: Bedrock inference handling. -* **Streaming:** Server-Sent Events (SSE). - -### Infrastructure (`infrastructure`) -* **IaC:** AWS CDK v2 (TypeScript) -* **Compute:** AWS Fargate (ECS) for APIs, Lambda for Gateway tools. -* **Storage:** DynamoDB (sessions, user data), S3 (assets). -* **Networking:** VPC, ALB, CloudFront. - -## Directory Structure - -* **`backend/`**: Python backend source code. - * `src/agents`: Main agent logic and tools. - * `src/apis`: API route definitions (`app_api`, `inference_api`). -* **`frontend/`**: Angular frontend source code. - * `ai.client/src/app`: Application components and services. -* **`infrastructure/`**: AWS CDK stacks. - * `lib/`: Stack definitions (`app-api-stack`, `frontend-stack`, `gateway-stack`, etc.). -* **`scripts/`**: Utility scripts for build, deploy, and test. - -## Development Workflow - -### Prerequisites -* Node.js 18+ -* Python 3.13+ -* Docker -* AWS CLI configured - -### Setup & Run -1. **Setup Dependencies:** - ```bash - ./setup.sh - ``` -2. **Configure Environment:** - * Copy `backend/src/.env.example` to `backend/src/.env`. - * Fill in AWS credentials and region. -3. **Start Locally:** - ```bash - ./start.sh - ``` - * Frontend: `http://localhost:4200` - * Backend: `http://localhost:8000` - -### Testing -* **Backend:** `pytest` (run from `backend/src`) -* **Frontend:** `ng test` (run from `frontend/ai.client`) - -## Key Conventions - -* **Tooling:** Tools are defined in `backend/src/agents/main_agent/tools`. Local tools use the `@tool` decorator. -* **Styling:** Use Tailwind utility classes. -* **State:** Use Angular Signals for reactive state management. -* **API Communication:** The frontend communicates with the backend via HTTP and SSE for chat streaming. - -## Important Files -* `README.md`: Comprehensive project documentation. -* `CLAUDE.MD`: Specific instructions for AI agents (contains architecture diagrams and detailed flows). -* `backend/pyproject.toml`: Python dependencies. -* `frontend/ai.client/package.json`: Frontend dependencies. -* `infrastructure/cdk.json`: CDK configuration. diff --git a/README.md b/README.md index 399775d7..2432411f 100644 --- a/README.md +++ b/README.md @@ -8,7 +8,7 @@ **An open-source, production-ready Generative AI platform for institutions** *Built by Boise State University, designed for everyone.* -[![Release](https://img.shields.io/badge/Release-v1.0.0--beta.20-6366f1?style=flat&logo=github&logoColor=white)](RELEASE_NOTES.md) +[![Release](https://img.shields.io/badge/Release-v1.0.0--beta.22-6366f1?style=flat&logo=github&logoColor=white)](RELEASE_NOTES.md) [![Nightly](https://github.com/Boise-State-Development/agentcore-public-stack/actions/workflows/nightly.yml/badge.svg)](https://github.com/Boise-State-Development/agentcore-public-stack/actions/workflows/nightly.yml) ![Python](https://img.shields.io/badge/Python-3.13+-3776AB?style=flat&logo=python&logoColor=white) @@ -220,7 +220,7 @@ The fastest path to production is the **GitHub Actions pipeline**, which automat ./start.sh ``` --> -See [backend/README.md](backend/README.md) for detailed backend setup, including authentication provider bootstrapping. +See [backend/README.md](backend/README.md) for detailed backend setup. Authentication is handled by Cognito's first-boot flow — the first user to access the application creates the admin account directly. --- @@ -229,7 +229,6 @@ See [backend/README.md](backend/README.md) for detailed backend setup, including ``` agentcore-public-stack/ ├── backend/ -│ ├── lambda-functions/ # Runtime provisioner & updater │ └── src/ │ ├── agents/main_agent/ # Agent core: factory, tools, memory, streaming │ └── apis/ @@ -257,7 +256,7 @@ agentcore-public-stack/ See [RELEASE_NOTES.md](RELEASE_NOTES.md) for the full changelog, including new features, bug fixes, platform upgrades, and deployment notes for each release. -**Current release:** v1.0.0-beta.20 +**Current release:** v1.0.0-beta.22 --- diff --git a/RELEASE_NOTES.md b/RELEASE_NOTES.md index 409b42ad..9919654e 100644 --- a/RELEASE_NOTES.md +++ b/RELEASE_NOTES.md @@ -1,3 +1,200 @@ +# Release Notes — v1.0.0-beta.22 + +**Release Date:** April 8, 2026 +**Previous Release:** v1.0.0-beta.20 (April 1, 2026) + +--- + +## Highlights + +This release replaces the authentication system end-to-end with a **Cognito-native identity broker** and zero-configuration first-boot experience. The previous generic OIDC flow, backend token exchange, and manual auth provider seeding are gone entirely. Alongside the auth migration, **CORS handling is unified** across all six CDK stacks via a shared `buildCorsOrigins` helper, the **RBAC authorization layer is consolidated** to a single `require_app_roles` dependency with role enrichment from stored user profiles, and a **documentation cleanup** purges 54,000+ lines of outdated specs and AI-generated artifacts. + +--- + +## ⚠️ Breaking Change — Cognito Authentication Migration + +**This is a breaking change release.** The entire authentication system has been replaced with AWS Cognito as the sole identity broker. The previous generic OIDC implementation — including the backend token exchange service, OIDC discovery endpoint, PKCE flow, and multi-provider auth bootstrapping — has been removed. There is no backward compatibility layer and no migration path that preserves the old auth flow. The legacy implementation is not supported going forward. + +**If you are upgrading an existing deployment**, you must: + +1. Deploy the Infrastructure stack first to provision the new Cognito User Pool, App Client, and Domain +2. Reconfigure any federated identity providers (e.g., Entra ID, Okta) as Cognito federated IdPs — the old auth provider table format is not compatible +3. Re-bootstrap your admin user via the new first-boot flow (the first user to access the app after upgrade creates the admin account) +4. Update all CI/CD workflows with `CDK_DOMAIN_NAME` and `CDK_CORS_ORIGINS` environment variables + +**If you are deploying fresh**, the new first-boot experience handles everything automatically — no manual seeding or Secrets Manager configuration required. + +--- + +## Cognito First-Boot Authentication + +The entire authentication architecture has been rearchitected around AWS Cognito as the native identity provider. The previous generic OIDC flow — including manual auth provider seeding, Secrets Manager client secret configuration, and the multi-step bootstrap process — has been removed with no backward compatibility. + +### First-Boot Experience + +On initial deployment, the first user to access the application is presented with a setup page to create the admin account directly in Cognito. This eliminates the previous multi-step bootstrap process (seed auth provider secrets, configure OIDC endpoints, create initial user). The first-boot flow uses race-condition-safe DynamoDB writes to ensure only one admin account is created. + +### Infrastructure + +A Cognito User Pool, App Client, and Domain are now provisioned in the Infrastructure CDK stack. SSM parameters wire the Cognito configuration across stacks. The AgentCore Runtime is configured with a single Cognito JWT authorizer, replacing the previous generic OIDC validator. + +### Backend + +- New `CognitoJWTValidator` replaces `GenericOIDCJWTValidator` with Cognito-specific JWKS validation and claim extraction +- New `system/` module (`cognito_service.py`, `repository.py`, `routes.py`, `models.py`) handles first-boot setup, system status, and Cognito user/group management +- New `cognito_idp_service.py` in `shared/auth_providers/` manages federated identity provider CRUD via Cognito IdP APIs +- `add_user_to_group` method manages Cognito group membership with rollback on failure +- Bootstrap script (`seed_bootstrap_data.py`) simplified — no longer seeds auth provider secrets, focuses on RBAC roles and JWT mappings +- Runtime-provisioner and runtime-updater Lambda functions removed entirely (2,800+ lines deleted) + +### Frontend + +- New first-boot page (`first-boot.page.ts`) with admin account creation form and `first-boot.guard.ts` route guard +- Login page simplified — delegates to Cognito OAuth 2.0 + PKCE flow instead of managing tokens directly +- `auth-api.service.ts` removed — frontend communicates directly with Cognito +- `callback.service.ts` rewritten for Cognito token exchange +- Auth provider form now displays the required Cognito redirect URI (`{cognitoDomainUrl}/oauth2/idpresponse`) with a copy button for zero-friction IdP registration +- Provider list page simplified — runtime status UI and unused icon imports removed +- Updated favicon and logo assets with refreshed branding and cross-platform icon support + +### Test Coverage + +1,177 lines of new `CognitoIdPService` tests, 316 lines of `CognitoJWTValidator` tests, 286 lines of first-boot tests, 278 lines of system service tests, plus updated auth route, dependency, RBAC, and auth sweep tests. Frontend gains `SystemService` unit tests and updated auth guard/callback/interceptor specs. + +--- + +## Cognito-Managed Auth Flow Migration + +The backend OIDC authentication service and token exchange layer have been removed entirely with no compatibility shim. The frontend now communicates directly with Cognito for all auth operations. The legacy OIDC implementation is not supported and will not be restored. + +### Removed + +- Backend `auth/models.py`, `auth/service.py`, and associated test files (`test_oidc_auth_service.py`, `test_pkce.py`) +- Token refresh and logout endpoints from backend auth routes +- OIDC discovery endpoint (`POST /discover`) from admin auth provider routes +- 1,318 lines of backend auth code deleted + +### Simplified + +- Auth routes reduced to a single public provider listing endpoint +- User service updated to work with Cognito-provided user information +- Auth provider repository gains JSON parsing error handling for malformed Secrets Manager values + +--- + +## RBAC Authorization Consolidation + +The authorization system has been consolidated from multiple role-checking functions to a single `require_app_roles` dependency that resolves permissions through `AppRoleService`. + +### Removed + +- `require_roles`, `require_all_roles`, `has_any_role`, `has_all_roles` +- Role-specific decorators: `require_faculty`, `require_staff`, `require_developer`, `require_aws_ai_access` +- Auth module exports simplified to only `require_app_roles` and `require_admin` + +### Added + +- User roles enriched from stored DynamoDB profile during token processing, ensuring RBAC uses correct IdP-mapped roles instead of Cognito provider group names +- User profile cache invalidation on `sync_my_profile` — subsequent requests pick up fresh roles immediately instead of waiting for the 5-minute cache TTL +- JSON array parsing for `custom:roles` claim (`CognitoJWTValidator`) — supports both `'["Admin","Staff"]'` and comma-separated formats for Entra ID role mapping +- `parseRolesFromToken` utility function on the frontend with 118 lines of test coverage +- `jwt_role_mappings` updates now allowed on `system_admin` role — validation changed from error-raising to silent field filtering with logging +- Role priority maximum increased from 999 to 1000 + +--- + +## CORS Unification + +All six CDK stacks now use a single shared `buildCorsOrigins()` helper in `config.ts` that builds CORS origins from `CDK_DOMAIN_NAME` (always), `localhost:4200` (always, for local dev), and optional per-section `additionalCorsOrigins`. This replaces the previous per-stack `corsOrigins` fields that were inconsistent and error-prone. + +### Changes + +- S3 CORS configuration made conditional — `undefined` when no origins are configured, preventing empty CORS rules +- RAG CORS Lambda fix: `ExposedHeaders` corrected to `ExposeHeaders` (the valid boto3 S3 CORS parameter name), fixing CloudFormation custom resource failures during frontend stack deployment +- Both Python APIs (`app_api`, `inference_api`) read `CORS_ORIGINS` env var, replacing hardcoded `allow_origins=['*']` with an env-driven allowlist +- Regression tests added for CORS_ORIGINS in app-api and inference-api stack tests + +--- + +## Bootstrap & Seeding Fixes + +- Bootstrap script (`seed_bootstrap_data.py`) is now the sole owner of RBAC role seeding — `ensure_system_roles()` removed from app-api startup to prevent overwriting admin customizations on every boot +- `system_admin` role seeded with `jwt_role_mappings=['system_admin']` instead of empty array — fixes the issue where Cognito first-boot admin users had the right `cognito:groups` claim but no matching AppRole +- Additive JWT mapping seeding: if the role exists but is missing required mappings, they're added without removing existing custom mappings + +--- + +## CI/CD Improvements + +- `CDK_DOMAIN_NAME` and `CDK_CORS_ORIGINS` added to all workflow jobs that run synth or deploy (previously missing from `inference-api.yml` and `gateway.yml`, causing `loadConfig` validation failures) +- `CDK_CORS_ORIGINS` and `CDK_FILE_UPLOAD_CORS_ORIGINS` added to nightly deploy pipeline +- SSM `StringParameter` creation guarded with conditional check to prevent empty string values (SSM parameter tier rejects empty strings) +- File upload CORS validation softened from hard error to warning since `loadConfig` runs for all stacks +- Infrastructure workflow updated with Cognito context values +- Trivy image scanning action upgraded from `v0.28.0` to `v0.35.0` with corrected SHA pin — the previous pin (`18f2510`) was actually the `v0.29.0` commit SHA mislabeled as `v0.28.0`, and was among the tags compromised in the [March 2026 trivy-action supply chain attack](https://github.com/aquasecurity/trivy/security/advisories/GHSA-69fq-xp46-6x23). The new pin (`57a97c7e`) points to the post-remediation immutable `v0.35.0` release +- App API `synth-cdk` job now actually skipped on pull requests — the `if: github.event_name != 'pull_request'` guard was missing despite being documented in beta.20. PRs no longer require AWS credentials or ARM runners for the app-api workflow + +--- + +## Bug Fixes + +- Model form validation summary now displayed above submit button showing all invalid fields — fixes the greyed-out submit button with no visible errors on edit +- "Add Model" button and "Browse Bedrock/Gemini/OpenAI Models" links uncommented on manage models page +- `SystemService` tests stabilized against shared fetch spy by filtering assertions by URL +- Inference API endpoints updated with `/invocations` path and URL-encoded ARN to prevent parsing errors with AgentCore runtime ARNs +- ALB listener rule updated with `requestHeaderConfiguration` to propagate `Authorization` header to inference API +- AWS Marketplace permissions (`ViewSubscriptions`, `Subscribe`) added to runtime execution role for marketplace-gated Bedrock models + +--- + +## Documentation Cleanup + +54,665 lines of outdated AI specs, feature summaries, and documentation purged across 121 files. Removed content includes completed spec directories (agent-core-tests, api-route-tests, auth-rbac-tests, bootstrap-data-seeding, config-cleanup-audit, environment-agnostic-refactor, and 12 others), duplicate docs under `docs/specs/`, the `GEMINI.md` agent config, `codeql-alerts.json` dump, and the `CODE_REVIEW_TOKEN_STORAGE.md` document. The Cognito first-boot auth and reliable document deletion specs were added as replacements. + +--- + +## Dependency Upgrades + +| Component | From | To | +|---|---|---| +| Angular packages | 21.2.6 | 21.2.7 | +| @angular/cdk | 21.2.4 | 21.2.5 | +| @angular/build | 21.2.5 | 21.2.6 | +| @angular/cli | 21.2.5 | 21.2.6 | +| katex | 0.16.44 | 0.16.45 | +| marked | 17.0.5 | 17.0.6 | +| mermaid | 11.13.0 | 11.14.0 | +| @analogjs/vite-plugin-angular | 3.0.0-alpha.18 | 3.0.0-alpha.26 | +| @analogjs/vitest-angular | 3.0.0-alpha.18 | 3.0.0-alpha.26 | +| aws-cdk-lib | 2.245.0 | 2.248.0 | +| aws-cdk (CLI) | 2.1115.0 | 2.1117.0 | +| @types/node | 25.5.0 | 25.5.2 | +| ts-jest | 29.4.6 | 29.4.9 | +| fastapi | 0.135.2 | 0.135.3 | +| uvicorn | 0.42.0 | 0.44.0 | +| boto3 | 1.42.78 | 1.42.83 | +| strands-agents | 1.33.0 | 1.34.1 | +| bedrock-agentcore | 1.4.8 | 1.6.0 | +| google-genai | 1.69.0 | 1.70.0 | +| hypothesis | 6.151.10 | 6.151.11 | +| ruff | 0.15.8 | 0.15.9 | +| mypy | 1.19.1 | 1.20.0 | + +--- + +## Deployment Notes + +**This release contains breaking changes.** See the migration steps at the top of this document. + +- **Infrastructure:** Deploy first. The stack now provisions a Cognito User Pool, App Client, and Domain. New CDK context values required: `CDK_DOMAIN_NAME` and `CDK_CORS_ORIGINS` must be set in all workflow environments. +- **Backend:** The App API no longer handles token exchange or OIDC discovery. The `GenericOIDCJWTValidator`, `auth/service.py`, `auth/models.py`, and all token management endpoints have been deleted. The `runtime-provisioner` and `runtime-updater` Lambda functions have been removed. Restart all containers. +- **Frontend:** Full rebuild and deploy required. The auth flow now uses Cognito OAuth 2.0 + PKCE directly. The `auth-api.service.ts` has been removed. The first user to access a fresh deployment will see the first-boot setup page. +- **Federated IdPs:** Existing Entra ID, Okta, or other OIDC providers must be reconfigured as Cognito federated identity providers. The old auth provider table format and Secrets Manager secret structure are no longer used. Register the Cognito redirect URI (`{cognitoDomainUrl}/oauth2/idpresponse`) in your external IdP. +- **Bootstrap:** The seed script no longer seeds auth provider secrets or OIDC configuration. It only handles RBAC roles and JWT mappings. +- **Nightly/CI:** All workflows now require `CDK_DOMAIN_NAME` and `CDK_CORS_ORIGINS` environment variables. + +--- + # Release Notes — v1.0.0-beta.20 **Release Date:** April 1, 2026 diff --git a/VERSION b/VERSION index ec46bbaa..137ddac9 100644 --- a/VERSION +++ b/VERSION @@ -1 +1 @@ -1.0.0-beta.20 +1.0.0-beta.22 diff --git a/backend/README.md b/backend/README.md index f94543ea..ff7ee027 100644 --- a/backend/README.md +++ b/backend/README.md @@ -58,13 +58,6 @@ echo "AWS_PROFILE=my-profile" >> src/.env export AWS_PROFILE=my-profile ``` -📖 **See [AWS_PROFILE_GUIDE.md](../docs/AWS_PROFILE_GUIDE.md) for detailed configuration options including:** -- Multiple AWS accounts/profiles -- AWS SSO (IAM Identity Center) -- Environment variable fallback -- CI/CD configuration -- Troubleshooting - ## Project Structure ``` diff --git a/backend/lambda-functions/runtime-provisioner/README.md b/backend/lambda-functions/runtime-provisioner/README.md deleted file mode 100644 index 735d4ad7..00000000 --- a/backend/lambda-functions/runtime-provisioner/README.md +++ /dev/null @@ -1,199 +0,0 @@ -# Runtime Provisioner Lambda - -Automatically provisions, updates, and deletes AWS Bedrock AgentCore Runtimes based on DynamoDB Stream events from the Auth Providers table. - -## Overview - -This Lambda function implements the multi-runtime architecture for OIDC authentication providers. When an admin adds, updates, or deletes an authentication provider via the UI, this function automatically manages the corresponding AgentCore Runtime. - -## Event Flow - -- **INSERT**: Create new runtime with provider's JWT authorizer configuration -- **MODIFY**: Update runtime if JWT-relevant fields changed (issuer URL, client ID, JWKS URI) -- **REMOVE**: Delete runtime and clean up SSM parameters - -## Environment Variables - -Required environment variables: - -- `PROJECT_PREFIX`: Project prefix for resource naming (e.g., "bsu") -- `AWS_REGION`: AWS region (e.g., "us-east-1") -- `AUTH_PROVIDERS_TABLE`: DynamoDB table name for auth providers - -## IAM Permissions Required - -The Lambda execution role needs the following permissions: - -### DynamoDB -- `dynamodb:GetRecords` - Read stream events -- `dynamodb:GetShardIterator` - Process stream -- `dynamodb:DescribeStream` - Stream metadata -- `dynamodb:ListStreams` - List streams -- `dynamodb:UpdateItem` - Update provider runtime status - -### Bedrock AgentCore -- `bedrock-agentcore:CreateAgentRuntime` - Create new runtimes -- `bedrock-agentcore:UpdateAgentRuntime` - Update existing runtimes -- `bedrock-agentcore:DeleteAgentRuntime` - Delete runtimes -- `bedrock-agentcore:GetAgentRuntime` - Fetch runtime configuration - -### SSM Parameter Store -- `ssm:GetParameter` - Read configuration parameters -- `ssm:PutParameter` - Store runtime ARNs -- `ssm:DeleteParameter` - Clean up runtime ARNs - -### ECR -- `ecr:DescribeRepositories` - Get repository details -- `ecr:DescribeImages` - Get image details - -### IAM -- `iam:PassRole` - Pass runtime execution role to AgentCore - -### CloudWatch Logs -- `logs:CreateLogGroup` - Create log groups -- `logs:CreateLogStream` - Create log streams -- `logs:PutLogEvents` - Write logs - -## SSM Parameters Used - -### Read Parameters -- `/${PROJECT_PREFIX}/inference-api/image-tag` - Container image tag -- `/${PROJECT_PREFIX}/inference-api/ecr-repository-uri` - ECR repository URI -- `/${PROJECT_PREFIX}/inference-api/runtime-execution-role-arn` - Runtime IAM role ARN - -### Write Parameters -- `/${PROJECT_PREFIX}/runtimes/{provider_id}/arn` - Runtime ARN for each provider - -## Runtime Creation Process - -1. Extract provider details from DynamoDB Stream event -2. Fetch current container image tag from SSM -3. Construct runtime name: `{projectPrefix}_agentcore_runtime_{provider_id}` -4. Determine OIDC discovery URL from issuer URL -5. Call `CreateAgentRuntime` API with: - - Container image URI from ECR - - JWT authorizer config (discovery URL, allowed audience) - - Runtime execution role ARN - - Network configuration (PUBLIC mode) - - Environment variables (project prefix, region, provider ID) -6. Store runtime ARN, ID, and endpoint URL in DynamoDB -7. Store runtime ARN in SSM for cross-stack reference - -## Runtime Update Process - -1. Check if JWT-relevant fields changed (issuer URL, client ID, JWKS URI) -2. If no changes, skip update -3. Fetch current runtime configuration via `GetAgentRuntime` -4. Call `UpdateAgentRuntime` with new JWT authorizer config -5. Preserve all other settings (container image, network, role) -6. Update DynamoDB status to READY - -## Runtime Deletion Process - -1. Extract runtime ID from DynamoDB Stream event -2. Call `DeleteAgentRuntime` API -3. Delete runtime ARN from SSM Parameter Store -4. Handle ResourceNotFoundException gracefully (already deleted) - -## Error Handling - -All exceptions during runtime operations are caught and handled: - -1. Log detailed error information to CloudWatch -2. Update DynamoDB with FAILED status and error message -3. Don't re-raise exception (let DynamoDB Streams retry logic handle it) - -## Retry Logic - -Retry logic is handled by Lambda DynamoDB Stream integration: -- 3 automatic retry attempts -- Exponential backoff between retries -- Failed records sent to DLQ (if configured) - -## Runtime Naming Convention - -Runtime names follow the pattern: `{projectPrefix}_agentcore_runtime_{provider_id}` - -Rules: -- Replace hyphens with underscores (AgentCore requirement) -- Use provider ID from database -- Include project prefix for multi-tenant isolation - -Examples: -- `bsu_agentcore_runtime_entra_id` -- `bsu_agentcore_runtime_okta_prod` -- `bsu_agentcore_runtime_google_workspace` - -## Runtime Endpoint URL - -The runtime endpoint URL is constructed as: -``` -https://bedrock-agentcore.{region}.amazonaws.com/runtimes/{runtime_arn}/invocations -``` - -This URL is stored in DynamoDB and used by the frontend to route requests to the correct runtime. - -## DynamoDB Updates - -The function updates the following fields in the Auth Providers table: - -- `agentcoreRuntimeArn` - Runtime ARN -- `agentcoreRuntimeId` - Runtime ID -- `agentcoreRuntimeEndpointUrl` - Runtime endpoint URL -- `agentcoreRuntimeStatus` - Status (PENDING, CREATING, READY, UPDATING, FAILED, UPDATE_FAILED) -- `agentcoreRuntimeError` - Error message (if failed) -- `updatedAt` - Timestamp - -## Monitoring - -CloudWatch Logs: -- All operations logged with INFO level -- Errors logged with ERROR level and stack traces -- Runtime creation/update/deletion events logged - -CloudWatch Metrics (custom): -- Runtime creation success/failure count -- Runtime update success/failure count -- Runtime deletion success/failure count - -## Testing - -Local testing with sample DynamoDB Stream events: - -```python -# Sample INSERT event -{ - "Records": [{ - "eventName": "INSERT", - "dynamodb": { - "NewImage": { - "providerId": {"S": "test-provider"}, - "issuerUrl": {"S": "https://login.microsoftonline.com/tenant-id/v2.0"}, - "clientId": {"S": "client-id-123"}, - "jwksUri": {"S": "https://login.microsoftonline.com/tenant-id/discovery/v2.0/keys"} - } - } - }] -} -``` - -## Deployment - -This Lambda function is deployed via the RuntimeProvisionerStack CDK stack: - -1. Package Lambda code and dependencies -2. Create Lambda function resource -3. Configure DynamoDB Stream event source -4. Set environment variables -5. Attach IAM role with required permissions -6. Configure CloudWatch log group with retention - -## Dependencies - -- `boto3==1.35.93` - AWS SDK for Python - -## Related Documentation - -- [Multi-Runtime Authentication Providers Design](../../../.kiro/specs/multi-runtime-auth-providers/design.md) -- [Multi-Runtime Authentication Providers Requirements](../../../.kiro/specs/multi-runtime-auth-providers/requirements.md) -- [AWS Bedrock AgentCore Documentation](https://docs.aws.amazon.com/bedrock-agentcore/) diff --git a/backend/lambda-functions/runtime-provisioner/lambda_function.py b/backend/lambda-functions/runtime-provisioner/lambda_function.py deleted file mode 100644 index f82c891f..00000000 --- a/backend/lambda-functions/runtime-provisioner/lambda_function.py +++ /dev/null @@ -1,1113 +0,0 @@ -""" -Runtime Provisioner Lambda for AgentCore Multi-Runtime Architecture - -Automatically provisions, updates, and deletes AgentCore Runtimes based on -DynamoDB Stream events from the Auth Providers table. - -Event Flow: -- INSERT: Create new runtime with provider's JWT config -- MODIFY: Update runtime if JWT-relevant fields changed -- REMOVE: Delete runtime and clean up SSM parameters -""" -import json -import os -import logging -from typing import Dict, Any, Optional -from datetime import datetime -import sys - -# Install latest boto3 at runtime to get newest API support -from pip._internal import main -main(['install', '-I', '-q', 'boto3', '--target', '/tmp/', '--no-cache-dir', '--disable-pip-version-check']) -sys.path.insert(0, '/tmp/') - -logger = logging.getLogger() -logger.setLevel(logging.INFO) - -import boto3 -from botocore.exceptions import ClientError - -# AWS clients -dynamodb = boto3.client('dynamodb') -ssm = boto3.client('ssm') -ecr = boto3.client('ecr') -bedrock_agentcore = boto3.client('bedrock-agentcore-control') - -# Environment variables -PROJECT_PREFIX = os.environ['PROJECT_PREFIX'] -AWS_REGION = os.environ['AWS_REGION'] -AUTH_PROVIDERS_TABLE = os.environ['AUTH_PROVIDERS_TABLE'] - - -def lambda_handler(event, context): - """ - Lambda handler for DynamoDB Stream events from Auth Providers table - - Processes INSERT, MODIFY, and REMOVE events to manage AgentCore Runtimes - """ - try: - logger.info(f"Event: {json.dumps(event)}") - - # Process each record in the stream - for record in event.get('Records', []): - event_name = record['eventName'] - - logger.info(f"Processing {event_name} event") - - if event_name == 'INSERT': - handle_insert(record) - elif event_name == 'MODIFY': - handle_modify(record) - elif event_name == 'REMOVE': - handle_remove(record) - else: - logger.warning(f"Unknown event type: {event_name}") - - return { - 'statusCode': 200, - 'body': json.dumps({'message': 'Successfully processed stream events'}) - } - - except Exception as e: - logger.error(f"Error processing stream events: {str(e)}", exc_info=True) - # Re-raise to trigger Lambda retry - raise - - -def handle_insert(record: Dict[str, Any]) -> None: - """ - Handle INSERT event - create new AgentCore Runtime - - Args: - record: DynamoDB Stream record with NewImage - """ - try: - # Extract provider details from NewImage - new_image = record['dynamodb']['NewImage'] - provider_id = deserialize_dynamodb_value(new_image['providerId']) - - logger.info(f"Creating runtime for provider: {provider_id}") - - # Parse provider configuration - provider_config = parse_provider_from_stream(new_image) - - # Create runtime - runtime_info = create_runtime(provider_id, provider_config) - - # Update DynamoDB with runtime details - update_provider_runtime_info( - provider_id=provider_id, - runtime_arn=runtime_info['runtime_arn'], - runtime_id=runtime_info['runtime_id'], - endpoint_url=runtime_info['endpoint_url'], - status='READY' - ) - - # Store runtime ARN in SSM for cross-stack reference - store_runtime_arn_in_ssm(provider_id, runtime_info['runtime_arn']) - - logger.info(f"✅ Successfully created runtime for provider {provider_id}") - - except Exception as e: - logger.error(f"Failed to create runtime: {str(e)}", exc_info=True) - - # Update DynamoDB with error status - provider_id = deserialize_dynamodb_value(record['dynamodb']['NewImage']['providerId']) - update_provider_runtime_error(provider_id, str(e)) - - # Don't re-raise - let DynamoDB Streams retry logic handle it - - -def handle_modify(record: Dict[str, Any]) -> None: - """ - Handle MODIFY event - update runtime if JWT config changed - - Args: - record: DynamoDB Stream record with OldImage and NewImage - """ - try: - old_image = record['dynamodb'].get('OldImage', {}) - new_image = record['dynamodb']['NewImage'] - - provider_id = deserialize_dynamodb_value(new_image['providerId']) - - logger.info(f"Checking if runtime update needed for provider: {provider_id}") - - # Check if JWT-relevant fields changed - jwt_fields = ['issuerUrl', 'clientId', 'jwksUri'] - jwt_changed = any( - deserialize_dynamodb_value(old_image.get(field, {})) != - deserialize_dynamodb_value(new_image.get(field, {})) - for field in jwt_fields - ) - - if not jwt_changed: - logger.info(f"No JWT config changes for {provider_id}, skipping update") - return - - logger.info(f"JWT config changed for {provider_id}, updating runtime") - - # Get runtime ID from DynamoDB - runtime_id = deserialize_dynamodb_value(new_image.get('agentcoreRuntimeId', {})) - - if not runtime_id: - logger.warning(f"No runtime ID found for {provider_id}, cannot update") - return - - # Parse new provider configuration - provider_config = parse_provider_from_stream(new_image) - - # Update runtime - update_runtime(runtime_id, provider_config, provider_id) - - # Update DynamoDB status - update_provider_runtime_status(provider_id, 'READY') - - logger.info(f"✅ Successfully updated runtime for provider {provider_id}") - - except Exception as e: - logger.error(f"Failed to update runtime: {str(e)}", exc_info=True) - - # Update DynamoDB with error status - provider_id = deserialize_dynamodb_value(record['dynamodb']['NewImage']['providerId']) - update_provider_runtime_error(provider_id, str(e), status='UPDATE_FAILED') - - -def handle_remove(record: Dict[str, Any]) -> None: - """ - Handle REMOVE event - delete runtime and clean up SSM - - Args: - record: DynamoDB Stream record with OldImage - """ - try: - old_image = record['dynamodb']['OldImage'] - provider_id = deserialize_dynamodb_value(old_image['providerId']) - runtime_id = deserialize_dynamodb_value(old_image.get('agentcoreRuntimeId', {})) - - logger.info(f"Deleting runtime for provider: {provider_id}") - - if not runtime_id: - logger.warning(f"No runtime ID found for {provider_id}, nothing to delete") - return - - # Reconstruct runtime name for observability cleanup - safe_prefix = PROJECT_PREFIX.replace('-', '_') - safe_provider_id = provider_id.replace('-', '_') - base_name = f"{safe_prefix}_runtime_{safe_provider_id}" - runtime_name = base_name[:48] if len(base_name) <= 48 else f"r_{safe_provider_id}"[:48] - - # Clean up observability (log deliveries) before deleting runtime - cleanup_runtime_observability(runtime_name) - - # Delete runtime - delete_runtime(runtime_id) - - # Clean up SSM parameter - delete_runtime_arn_from_ssm(provider_id) - - logger.info(f"✅ Successfully deleted runtime for provider {provider_id}") - - except Exception as e: - logger.error(f"Failed to delete runtime: {str(e)}", exc_info=True) - # Don't re-raise - provider is already deleted from DynamoDB - - -def create_runtime(provider_id: str, provider_config: Dict[str, Any]) -> Dict[str, str]: - """ - Create new AgentCore Runtime with provider's JWT configuration - - Args: - provider_id: Unique provider identifier - provider_config: Provider configuration from DynamoDB - - Returns: - Dict with runtime_arn, runtime_id, endpoint_url - """ - # Fetch container image tag from SSM - image_tag = get_container_image_tag() - - # Construct runtime name (replace ALL hyphens with underscores for AWS validation) - # Max length is 48 characters: [a-zA-Z][a-zA-Z0-9_]{0,47} - safe_prefix = PROJECT_PREFIX.replace('-', '_') - safe_provider_id = provider_id.replace('-', '_') - base_name = f"{safe_prefix}_runtime_{safe_provider_id}" - - # Truncate if necessary to fit within 48 character limit - if len(base_name) > 48: - # Keep the provider_id recognizable by truncating the prefix - max_provider_id_length = 48 - len("_runtime_") - 1 # -1 for first character - truncated_provider_id = safe_provider_id[:max_provider_id_length] - runtime_name = f"r_{truncated_provider_id}" # 'r_' prefix to ensure it starts with letter - # Ensure we're still under 48 chars - runtime_name = runtime_name[:48] - else: - runtime_name = base_name - - logger.info(f"Runtime name: {runtime_name} (length: {len(runtime_name)})") - - # Get container image URI from ECR - image_uri = get_container_image_uri(image_tag) - - # Determine discovery URL from issuer URL or JWKS URI - discovery_url = determine_discovery_url( - provider_config['issuer_url'], - provider_config.get('jwks_uri') - ) - - # Fetch runtime execution role ARN from SSM - execution_role_arn = get_runtime_execution_role_arn() - - # Fetch shared resource IDs from SSM - shared_resources = get_shared_resource_ids() - - # Fetch all required environment variables from SSM - runtime_env_vars = get_runtime_environment_variables(provider_id, shared_resources) - - logger.info(f"Creating runtime: {runtime_name}") - logger.info(f"Discovery URL: {discovery_url}") - logger.info(f"Client ID: {provider_config['client_id']}") - - # Log boto3 version for debugging - import boto3 - logger.info(f"Boto3 version: {boto3.__version__}") - - # Call CreateAgentRuntime API - response = bedrock_agentcore.create_agent_runtime( - agentRuntimeName=runtime_name, - agentRuntimeArtifact={ - 'containerConfiguration': { - 'containerUri': image_uri - } - }, - authorizerConfiguration={ - 'customJWTAuthorizer': { - 'discoveryUrl': discovery_url, - 'allowedAudience': [provider_config['client_id']] - } - }, - requestHeaderConfiguration={ - 'requestHeaderAllowlist': ['Authorization'] - }, - roleArn=execution_role_arn, - networkConfiguration={ - 'networkMode': 'PUBLIC' - }, - environmentVariables=runtime_env_vars - ) - - runtime_arn = response['agentRuntimeArn'] - runtime_id = response['agentRuntimeId'] - - # Construct endpoint URL with properly encoded runtime ARN - # The runtime ARN contains colons and slashes that must be URL-encoded - from urllib.parse import quote - encoded_runtime_arn = quote(runtime_arn, safe='') - endpoint_url = f"https://bedrock-agentcore.{AWS_REGION}.amazonaws.com/runtimes/{encoded_runtime_arn}/invocations" - - logger.info(f"Runtime created: {runtime_arn}") - logger.info(f"Endpoint URL: {endpoint_url}") - - # Configure observability (log deliveries + tracing) for the new runtime - workload_identity_arn = response.get('workloadIdentityDetails', {}).get('workloadIdentityArn') - configure_runtime_observability(runtime_arn, runtime_name, workload_identity_arn) - - return { - 'runtime_arn': runtime_arn, - 'runtime_id': runtime_id, - 'endpoint_url': endpoint_url - } - - -def update_runtime(runtime_id: str, provider_config: Dict[str, Any], provider_id: str) -> None: - """ - Update existing AgentCore Runtime with new JWT configuration - - Args: - runtime_id: Runtime ID to update - provider_config: New provider configuration - provider_id: Provider ID for environment variable construction - """ - # Determine discovery URL - discovery_url = determine_discovery_url( - provider_config['issuer_url'], - provider_config.get('jwks_uri') - ) - - logger.info(f"Updating runtime {runtime_id}") - logger.info(f"New discovery URL: {discovery_url}") - - # Fetch current runtime configuration to preserve settings - current_runtime = bedrock_agentcore.get_agent_runtime(agentRuntimeId=runtime_id) - - # Get current container image and other required fields - current_artifact = current_runtime['agentRuntimeArtifact'] - current_network_config = current_runtime['networkConfiguration'] - current_role_arn = current_runtime['roleArn'] - - # Build the update params, preserving all existing config - update_params = { - 'agentRuntimeId': runtime_id, - 'agentRuntimeArtifact': current_artifact, - 'authorizerConfiguration': { - 'customJWTAuthorizer': { - 'discoveryUrl': discovery_url, - 'allowedAudience': [provider_config['client_id']] - } - }, - 'requestHeaderConfiguration': { - 'requestHeaderAllowlist': ['Authorization'] - }, - 'networkConfiguration': current_network_config, - 'roleArn': current_role_arn - } - - # Preserve existing custom headers alongside Authorization - if 'requestHeaderConfiguration' in current_runtime: - existing_headers = set( - current_runtime['requestHeaderConfiguration'].get('requestHeaderAllowlist', []) - ) - existing_headers.add('Authorization') - update_params['requestHeaderConfiguration'] = { - 'requestHeaderAllowlist': sorted(existing_headers) - } - - # Re-fetch environment variables from SSM to pick up any changes - # (e.g., renamed tables, new parameters added since runtime creation). - # Previously we preserved stale env vars from the existing runtime, - # which caused issues when SSM parameter values changed between deploys. - try: - shared_resources = get_shared_resource_ids() - fresh_env_vars = get_runtime_environment_variables(provider_id, shared_resources) - update_params['environmentVariables'] = fresh_env_vars - logger.info(f"Refreshed {len(fresh_env_vars)} environment variables from SSM") - except Exception as e: - logger.warning( - f"Failed to refresh env vars from SSM: {e}. " - "Falling back to existing runtime env vars." - ) - if 'environmentVariables' in current_runtime: - update_params['environmentVariables'] = current_runtime['environmentVariables'] - - bedrock_agentcore.update_agent_runtime(**update_params) - - logger.info(f"Runtime {runtime_id} updated successfully") - - -def delete_runtime(runtime_id: str) -> None: - """ - Delete AgentCore Runtime - - Args: - runtime_id: Runtime ID to delete - """ - logger.info(f"Deleting runtime {runtime_id}") - - try: - bedrock_agentcore.delete_agent_runtime(agentRuntimeId=runtime_id) - logger.info(f"Runtime {runtime_id} deleted successfully") - except ClientError as e: - if e.response['Error']['Code'] == 'ResourceNotFoundException': - logger.warning(f"Runtime {runtime_id} not found, already deleted") - else: - raise - - -# ============================================================================= -# Observability: Vended Log Deliveries for Runtime -# ============================================================================= - -logs_client = boto3.client('logs') - - -def configure_runtime_observability(runtime_arn: str, runtime_name: str, workload_identity_arn: Optional[str] = None) -> None: - """ - Configure vended log deliveries and tracing for a newly created runtime. - - Sets up: - - Runtime: APPLICATION_LOGS delivery → CloudWatch Logs - - Runtime: TRACES delivery → X-Ray - - WorkloadIdentity: APPLICATION_LOGS delivery → CloudWatch Logs (if ARN available) - - Uses the CloudWatch Logs vended logs API (PutDeliverySource, PutDeliveryDestination, - CreateDelivery) as documented at: - https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/observability-configure.html - - Args: - runtime_arn: ARN of the newly created runtime - runtime_name: Name of the runtime (used for naming delivery resources) - workload_identity_arn: ARN of the auto-created WorkloadIdentity (from create_agent_runtime response) - """ - try: - # Truncate runtime_name to keep delivery resource names under limits - short_name = runtime_name[:40] - - # --- Runtime: APPLICATION_LOGS delivery --- - _setup_application_logs_delivery(runtime_arn, short_name) - - # --- Runtime: TRACES delivery --- - _setup_traces_delivery(runtime_arn, short_name) - - # --- WorkloadIdentity: APPLICATION_LOGS delivery --- - if workload_identity_arn: - _setup_identity_logs_delivery(workload_identity_arn, short_name) - else: - logger.warning("No workloadIdentityArn in create_agent_runtime response, skipping identity log delivery") - - logger.info(f"✅ Observability configured for runtime {runtime_name}") - - except Exception as e: - # Don't fail runtime creation if observability setup fails - logger.warning(f"⚠️ Failed to configure observability for runtime {runtime_name}: {e}") - logger.warning("Runtime was created successfully but log deliveries may need manual setup") - - -def _setup_application_logs_delivery(runtime_arn: str, short_name: str) -> None: - """Set up APPLICATION_LOGS delivery from runtime to CloudWatch Logs.""" - try: - log_group_name = f"/aws/vendedlogs/bedrock-agentcore/runtime/{short_name}" - - # Create log group (ignore if exists) - try: - logs_client.create_log_group(logGroupName=log_group_name) - logger.info(f"Created log group: {log_group_name}") - except ClientError as e: - if e.response['Error']['Code'] == 'ResourceAlreadyExistsException': - logger.info(f"Log group already exists: {log_group_name}") - else: - raise - - log_group_arn = f"arn:aws:logs:{AWS_REGION}:{boto3.client('sts').get_caller_identity()['Account']}:log-group:{log_group_name}" - - # Create delivery source - source_name = f"{short_name}-app-logs" - logs_client.put_delivery_source( - name=source_name, - logType="APPLICATION_LOGS", - resourceArn=runtime_arn - ) - logger.info(f"Created delivery source: {source_name}") - - # Create delivery destination - dest_name = f"{short_name}-app-logs-dest" - dest_response = logs_client.put_delivery_destination( - name=dest_name, - deliveryDestinationType='CWL', - deliveryDestinationConfiguration={ - 'destinationResourceArn': log_group_arn, - } - ) - logger.info(f"Created delivery destination: {dest_name}") - - # Create delivery (connect source to destination) - logs_client.create_delivery( - deliverySourceName=source_name, - deliveryDestinationArn=dest_response['deliveryDestination']['arn'] - ) - logger.info(f"Created APPLICATION_LOGS delivery for runtime {short_name}") - - except Exception as e: - logger.warning(f"Failed to set up APPLICATION_LOGS delivery: {e}") - - -def _setup_traces_delivery(runtime_arn: str, short_name: str) -> None: - """Set up TRACES delivery from runtime to X-Ray.""" - try: - # Create delivery source for traces - source_name = f"{short_name}-traces" - logs_client.put_delivery_source( - name=source_name, - logType="TRACES", - resourceArn=runtime_arn - ) - logger.info(f"Created traces delivery source: {source_name}") - - # Create delivery destination (X-Ray - no resource ARN needed) - dest_name = f"{short_name}-traces-dest" - dest_response = logs_client.put_delivery_destination( - name=dest_name, - deliveryDestinationType='XRAY' - ) - logger.info(f"Created traces delivery destination: {dest_name}") - - # Create delivery (connect source to destination) - logs_client.create_delivery( - deliverySourceName=source_name, - deliveryDestinationArn=dest_response['deliveryDestination']['arn'] - ) - logger.info(f"Created TRACES delivery for runtime {short_name}") - - except Exception as e: - logger.warning(f"Failed to set up TRACES delivery: {e}") - - -def _setup_identity_logs_delivery(identity_arn: str, short_name: str) -> None: - """Set up APPLICATION_LOGS delivery from WorkloadIdentity to CloudWatch Logs.""" - try: - log_group_name = f"/aws/vendedlogs/bedrock-agentcore/identity/{short_name}" - - # Create log group (ignore if exists) - try: - logs_client.create_log_group(logGroupName=log_group_name) - logger.info(f"Created identity log group: {log_group_name}") - except ClientError as e: - if e.response['Error']['Code'] == 'ResourceAlreadyExistsException': - logger.info(f"Identity log group already exists: {log_group_name}") - else: - raise - - log_group_arn = f"arn:aws:logs:{AWS_REGION}:{boto3.client('sts').get_caller_identity()['Account']}:log-group:{log_group_name}" - - # Create delivery source - source_name = f"{short_name}-identity-logs" - logs_client.put_delivery_source( - name=source_name, - logType="APPLICATION_LOGS", - resourceArn=identity_arn - ) - logger.info(f"Created identity delivery source: {source_name}") - - # Create delivery destination - dest_name = f"{short_name}-identity-logs-dest" - dest_response = logs_client.put_delivery_destination( - name=dest_name, - deliveryDestinationType='CWL', - deliveryDestinationConfiguration={ - 'destinationResourceArn': log_group_arn, - } - ) - logger.info(f"Created identity delivery destination: {dest_name}") - - # Create delivery (connect source to destination) - logs_client.create_delivery( - deliverySourceName=source_name, - deliveryDestinationArn=dest_response['deliveryDestination']['arn'] - ) - logger.info(f"Created APPLICATION_LOGS delivery for identity {short_name}") - - except Exception as e: - logger.warning(f"Failed to set up identity APPLICATION_LOGS delivery: {e}") - - -def cleanup_runtime_observability(runtime_name: str) -> None: - """ - Clean up vended log delivery resources when a runtime is deleted. - - Args: - runtime_name: Name of the runtime being deleted - """ - short_name = runtime_name[:40] - - delivery_names = [ - (f"{short_name}-app-logs", f"{short_name}-app-logs-dest"), - (f"{short_name}-traces", f"{short_name}-traces-dest"), - (f"{short_name}-identity-logs", f"{short_name}-identity-logs-dest"), - ] - - for source_name, dest_name in delivery_names: - try: - # List and delete deliveries for this source - try: - deliveries = logs_client.describe_deliveries() - for delivery in deliveries.get('deliveries', []): - if delivery.get('deliverySourceName') == source_name: - logs_client.delete_delivery(id=delivery['id']) - logger.info(f"Deleted delivery: {delivery['id']}") - except Exception as e: - logger.warning(f"Failed to delete deliveries for {source_name}: {e}") - - # Delete source - try: - logs_client.delete_delivery_source(name=source_name) - logger.info(f"Deleted delivery source: {source_name}") - except ClientError as e: - if e.response['Error']['Code'] != 'ResourceNotFoundException': - logger.warning(f"Failed to delete delivery source {source_name}: {e}") - - # Delete destination - try: - logs_client.delete_delivery_destination(name=dest_name) - logger.info(f"Deleted delivery destination: {dest_name}") - except ClientError as e: - if e.response['Error']['Code'] != 'ResourceNotFoundException': - logger.warning(f"Failed to delete delivery destination {dest_name}: {e}") - - except Exception as e: - logger.warning(f"Failed to clean up observability for {source_name}: {e}") - - -# ============================================================================= -# Helper Functions -# ============================================================================= - - -def get_optional_parameter(parameter_name: str) -> Optional[str]: - """ - Fetch an optional SSM parameter, returning None if it doesn't exist. - - Args: - parameter_name: Full SSM parameter path - - Returns: - Parameter value if it exists, None otherwise - """ - try: - response = ssm.get_parameter( - Name=parameter_name, - WithDecryption=True - ) - return response['Parameter']['Value'] - except ClientError as e: - if e.response['Error']['Code'] == 'ParameterNotFound': - logger.info(f"Optional parameter {parameter_name} not found, skipping") - return None - else: - logger.error(f"Error fetching optional parameter {parameter_name}: {e}") - raise - - -def get_required_parameter(parameter_name: str) -> str: - """ - Fetch a required SSM parameter, raising an exception if it doesn't exist. - - Args: - parameter_name: Full SSM parameter path - - Returns: - Parameter value - - Raises: - ClientError: If the required parameter doesn't exist or other SSM errors - """ - try: - response = ssm.get_parameter( - Name=parameter_name, - WithDecryption=True - ) - return response['Parameter']['Value'] - except ClientError as e: - if e.response['Error']['Code'] == 'ParameterNotFound': - logger.error(f"Required parameter {parameter_name} not found") - raise - else: - logger.error(f"Error fetching required parameter {parameter_name}: {e}") - raise - - -def normalize_url(url: str) -> str: - """ - Normalize a URL by ensuring it has a protocol. - - If the URL doesn't start with http:// or https://, prepends https://. - - Args: - url: URL or domain name - - Returns: - Normalized URL with protocol - """ - url = url.strip() - if not url: - return url - - # If already has protocol, return as-is - if url.startswith(('http://', 'https://')): - return url - - # Auto-prepend https:// for domain names - return f"https://{url}" - - -def validate_url(url: str, parameter_name: str) -> str: - """ - Validate and normalize a URL parameter. - - Args: - url: URL string to validate - parameter_name: Parameter name for error messages - - Returns: - Normalized URL with protocol - - Raises: - ValueError: If URL is empty - """ - if not url or not url.strip(): - raise ValueError(f"Empty URL value for {parameter_name}") - - # Normalize the URL (add https:// if missing) - normalized = normalize_url(url) - - return normalized - - -def parse_provider_from_stream(image: Dict[str, Any]) -> Dict[str, Any]: - """Parse provider configuration from DynamoDB Stream image""" - return { - 'issuer_url': deserialize_dynamodb_value(image['issuerUrl']), - 'client_id': deserialize_dynamodb_value(image['clientId']), - 'jwks_uri': deserialize_dynamodb_value(image.get('jwksUri', {})) - } - - -def deserialize_dynamodb_value(value: Dict[str, Any]) -> Any: - """Deserialize DynamoDB attribute value""" - if not value: - return None - - if 'S' in value: - return value['S'] - elif 'N' in value: - return value['N'] - elif 'BOOL' in value: - return value['BOOL'] - elif 'NULL' in value: - return None - elif 'L' in value: - return [deserialize_dynamodb_value(item) for item in value['L']] - elif 'M' in value: - return {k: deserialize_dynamodb_value(v) for k, v in value['M'].items()} - else: - return None - - -def determine_discovery_url(issuer_url: str, jwks_uri: Optional[str]) -> str: - """ - Determine OIDC discovery URL from issuer URL or JWKS URI - - Args: - issuer_url: OIDC issuer URL - jwks_uri: Optional JWKS URI - - Returns: - Discovery URL for JWT validation - """ - # If JWKS URI is provided, use issuer URL for discovery - # AgentCore will fetch JWKS from the discovery document - if issuer_url.endswith('/'): - issuer_url = issuer_url.rstrip('/') - - # Standard OIDC discovery endpoint - return f"{issuer_url}/.well-known/openid-configuration" - - -def get_container_image_tag() -> str: - """Fetch current container image tag from SSM""" - param_name = f"/{PROJECT_PREFIX}/inference-api/image-tag" - - try: - response = ssm.get_parameter(Name=param_name) - return response['Parameter']['Value'] - except ClientError as e: - logger.error(f"Failed to get image tag from SSM: {e}") - raise ValueError(f"Image tag not found in SSM: {param_name}") - - -def get_container_image_uri(image_tag: str) -> str: - """ - Get full container image URI from ECR - - Args: - image_tag: Image tag (e.g., 'latest', 'v1.0.0') - - Returns: - Full ECR image URI - """ - # Get ECR repository URI from SSM - repo_param = f"/{PROJECT_PREFIX}/inference-api/ecr-repository-uri" - - try: - response = ssm.get_parameter(Name=repo_param) - repo_uri = response['Parameter']['Value'] - return f"{repo_uri}:{image_tag}" - except ClientError as e: - logger.error(f"Failed to get ECR repository URI: {e}") - raise ValueError(f"ECR repository URI not found in SSM: {repo_param}") - - -def get_runtime_execution_role_arn() -> str: - """Fetch runtime execution role ARN from SSM""" - param_name = f"/{PROJECT_PREFIX}/inference-api/runtime-execution-role-arn" - - try: - response = ssm.get_parameter(Name=param_name) - return response['Parameter']['Value'] - except ClientError as e: - logger.error(f"Failed to get execution role ARN: {e}") - raise ValueError(f"Execution role ARN not found in SSM: {param_name}") - - -def store_runtime_arn_in_ssm(provider_id: str, runtime_arn: str) -> None: - """Store runtime ARN in SSM for cross-stack reference""" - param_name = f"/{PROJECT_PREFIX}/runtimes/{provider_id}/arn" - - try: - ssm.put_parameter( - Name=param_name, - Value=runtime_arn, - Type='String', - Description=f"AgentCore Runtime ARN for provider {provider_id}", - Overwrite=True - ) - logger.info(f"Stored runtime ARN in SSM: {param_name}") - except ClientError as e: - logger.error(f"Failed to store runtime ARN in SSM: {e}") - # Don't raise - this is not critical - - -def delete_runtime_arn_from_ssm(provider_id: str) -> None: - """Delete runtime ARN from SSM""" - param_name = f"/{PROJECT_PREFIX}/runtimes/{provider_id}/arn" - - try: - ssm.delete_parameter(Name=param_name) - logger.info(f"Deleted runtime ARN from SSM: {param_name}") - except ClientError as e: - if e.response['Error']['Code'] == 'ParameterNotFound': - logger.warning(f"SSM parameter not found: {param_name}") - else: - logger.error(f"Failed to delete runtime ARN from SSM: {e}") - - -def update_provider_runtime_info( - provider_id: str, - runtime_arn: str, - runtime_id: str, - endpoint_url: str, - status: str -) -> None: - """Update provider record in DynamoDB with runtime information""" - try: - dynamodb.update_item( - TableName=AUTH_PROVIDERS_TABLE, - Key={ - 'PK': {'S': f"AUTH_PROVIDER#{provider_id}"}, - 'SK': {'S': f"AUTH_PROVIDER#{provider_id}"} - }, - UpdateExpression='SET agentcoreRuntimeArn = :arn, agentcoreRuntimeId = :id, ' - 'agentcoreRuntimeEndpointUrl = :url, agentcoreRuntimeStatus = :status, ' - 'updatedAt = :updated', - ExpressionAttributeValues={ - ':arn': {'S': runtime_arn}, - ':id': {'S': runtime_id}, - ':url': {'S': endpoint_url}, - ':status': {'S': status}, - ':updated': {'S': datetime.utcnow().isoformat() + 'Z'} - } - ) - logger.info(f"Updated provider {provider_id} with runtime info") - except ClientError as e: - logger.error(f"Failed to update provider runtime info: {e}") - raise - - -def update_provider_runtime_status(provider_id: str, status: str) -> None: - """Update provider runtime status in DynamoDB""" - try: - dynamodb.update_item( - TableName=AUTH_PROVIDERS_TABLE, - Key={ - 'PK': {'S': f"AUTH_PROVIDER#{provider_id}"}, - 'SK': {'S': f"AUTH_PROVIDER#{provider_id}"} - }, - UpdateExpression='SET agentcoreRuntimeStatus = :status, updatedAt = :updated', - ExpressionAttributeValues={ - ':status': {'S': status}, - ':updated': {'S': datetime.utcnow().isoformat() + 'Z'} - } - ) - logger.info(f"Updated provider {provider_id} status to {status}") - except ClientError as e: - logger.error(f"Failed to update provider status: {e}") - - -def update_provider_runtime_error( - provider_id: str, - error_message: str, - status: str = 'FAILED' -) -> None: - """Update provider record with error status and message""" - try: - dynamodb.update_item( - TableName=AUTH_PROVIDERS_TABLE, - Key={ - 'PK': {'S': f"AUTH_PROVIDER#{provider_id}"}, - 'SK': {'S': f"AUTH_PROVIDER#{provider_id}"} - }, - UpdateExpression='SET agentcoreRuntimeStatus = :status, ' - 'agentcoreRuntimeError = :error, updatedAt = :updated', - ExpressionAttributeValues={ - ':status': {'S': status}, - ':error': {'S': error_message[:1000]}, # Limit error message length - ':updated': {'S': datetime.utcnow().isoformat() + 'Z'} - } - ) - logger.info(f"Updated provider {provider_id} with error status") - except ClientError as e: - logger.error(f"Failed to update provider error status: {e}") - - -def get_shared_resource_ids() -> Dict[str, str]: - """ - Fetch shared AgentCore resource IDs from SSM - - Returns: - Dict with memory_arn, memory_id, code_interpreter_id, browser_id, gateway_url - """ - try: - # Fetch all required SSM parameters in batch - param_names = [ - f"/{PROJECT_PREFIX}/inference-api/memory-arn", - f"/{PROJECT_PREFIX}/inference-api/memory-id", - f"/{PROJECT_PREFIX}/inference-api/code-interpreter-id", - f"/{PROJECT_PREFIX}/inference-api/browser-id", - f"/{PROJECT_PREFIX}/gateway/gateway-url", - ] - - response = ssm.get_parameters(Names=param_names, WithDecryption=False) - - # Build result dictionary - params = {p['Name']: p['Value'] for p in response['Parameters']} - - return { - 'memory_arn': params.get(f"/{PROJECT_PREFIX}/inference-api/memory-arn", ''), - 'memory_id': params.get(f"/{PROJECT_PREFIX}/inference-api/memory-id", ''), - 'code_interpreter_id': params.get(f"/{PROJECT_PREFIX}/inference-api/code-interpreter-id", ''), - 'browser_id': params.get(f"/{PROJECT_PREFIX}/inference-api/browser-id", ''), - 'gateway_url': params.get(f"/{PROJECT_PREFIX}/gateway/gateway-url", ''), - } - except ClientError as e: - logger.error(f"Failed to fetch shared resource IDs from SSM: {e}") - raise ValueError(f"Could not fetch shared resource IDs: {e}") - - -def get_runtime_environment_variables(provider_id: str, shared_resources: Dict[str, str]) -> Dict[str, str]: - """ - Construct complete environment variable dictionary for runtime - - Args: - provider_id: Provider ID for this runtime - shared_resources: Dict with shared resource IDs from get_shared_resource_ids() - - Returns: - Dict of environment variables for runtime creation - """ - try: - # Define required parameters - required_params = [ - # DynamoDB tables - f"/{PROJECT_PREFIX}/users/users-table-name", - f"/{PROJECT_PREFIX}/rbac/app-roles-table-name", - f"/{PROJECT_PREFIX}/auth/oidc-state-table-name", - f"/{PROJECT_PREFIX}/auth/api-keys-table-name", - f"/{PROJECT_PREFIX}/oauth/providers-table-name", - f"/{PROJECT_PREFIX}/oauth/user-tokens-table-name", - f"/{PROJECT_PREFIX}/rag/assistants-table-name", - # Quota & cost tracking tables - f"/{PROJECT_PREFIX}/quota/user-quotas-table-name", - f"/{PROJECT_PREFIX}/quota/quota-events-table-name", - f"/{PROJECT_PREFIX}/cost-tracking/sessions-metadata-table-name", - f"/{PROJECT_PREFIX}/cost-tracking/user-cost-summary-table-name", - f"/{PROJECT_PREFIX}/cost-tracking/system-cost-rollup-table-name", - f"/{PROJECT_PREFIX}/admin/managed-models-table-name", - # User settings - f"/{PROJECT_PREFIX}/settings/user-settings-table-name", - # File upload - f"/{PROJECT_PREFIX}/user-file-uploads/table-name", - # Auth provider secrets - f"/{PROJECT_PREFIX}/auth/auth-provider-secrets-arn", - # OAuth configuration - f"/{PROJECT_PREFIX}/oauth/token-encryption-key-arn", - f"/{PROJECT_PREFIX}/oauth/client-secrets-arn", - f"/{PROJECT_PREFIX}/oauth/callback-url", - # S3 buckets - f"/{PROJECT_PREFIX}/rag/vector-bucket-name", - f"/{PROJECT_PREFIX}/rag/vector-index-name", - # URLs - f"/{PROJECT_PREFIX}/network/alb-url", - f"/{PROJECT_PREFIX}/frontend/url", - f"/{PROJECT_PREFIX}/frontend/cors-origins", - ] - - # Fetch all required parameters - params = {} - for param_name in required_params: - params[param_name] = get_required_parameter(param_name) - - # Validate and normalize URLs - alb_url = validate_url(params[f"/{PROJECT_PREFIX}/network/alb-url"], "alb-url") - frontend_url = validate_url(params[f"/{PROJECT_PREFIX}/frontend/url"], "frontend-url") - callback_url = validate_url(params[f"/{PROJECT_PREFIX}/oauth/callback-url"], "oauth-callback-url") - - # Construct environment variables dictionary - env_vars = { - # Basic configuration - 'LOG_LEVEL': 'INFO', - 'PROJECT_NAME': PROJECT_PREFIX, - 'AWS_REGION': AWS_REGION, - 'AWS_DEFAULT_REGION': AWS_REGION, - 'PROVIDER_ID': provider_id, - - # DynamoDB tables - 'DYNAMODB_USERS_TABLE_NAME': params[f"/{PROJECT_PREFIX}/users/users-table-name"], - 'DYNAMODB_APP_ROLES_TABLE_NAME': params[f"/{PROJECT_PREFIX}/rbac/app-roles-table-name"], - 'DYNAMODB_OIDC_STATE_TABLE_NAME': params[f"/{PROJECT_PREFIX}/auth/oidc-state-table-name"], - 'DYNAMODB_API_KEYS_TABLE_NAME': params[f"/{PROJECT_PREFIX}/auth/api-keys-table-name"], - 'DYNAMODB_OAUTH_PROVIDERS_TABLE_NAME': params[f"/{PROJECT_PREFIX}/oauth/providers-table-name"], - 'DYNAMODB_OAUTH_USER_TOKENS_TABLE_NAME': params[f"/{PROJECT_PREFIX}/oauth/user-tokens-table-name"], - 'DYNAMODB_ASSISTANTS_TABLE_NAME': params[f"/{PROJECT_PREFIX}/rag/assistants-table-name"], - - # Quota & cost tracking tables - 'DYNAMODB_QUOTA_TABLE': params[f"/{PROJECT_PREFIX}/quota/user-quotas-table-name"], - 'DYNAMODB_QUOTA_EVENTS_TABLE': params[f"/{PROJECT_PREFIX}/quota/quota-events-table-name"], - 'DYNAMODB_SESSIONS_METADATA_TABLE_NAME': params[f"/{PROJECT_PREFIX}/cost-tracking/sessions-metadata-table-name"], - 'DYNAMODB_COST_SUMMARY_TABLE_NAME': params[f"/{PROJECT_PREFIX}/cost-tracking/user-cost-summary-table-name"], - 'DYNAMODB_SYSTEM_ROLLUP_TABLE_NAME': params[f"/{PROJECT_PREFIX}/cost-tracking/system-cost-rollup-table-name"], - 'DYNAMODB_MANAGED_MODELS_TABLE_NAME': params[f"/{PROJECT_PREFIX}/admin/managed-models-table-name"], - 'DYNAMODB_USER_SETTINGS_TABLE_NAME': params[f"/{PROJECT_PREFIX}/settings/user-settings-table-name"], - 'DYNAMODB_USER_FILES_TABLE_NAME': params[f"/{PROJECT_PREFIX}/user-file-uploads/table-name"], - - # Auth providers - 'DYNAMODB_AUTH_PROVIDERS_TABLE_NAME': AUTH_PROVIDERS_TABLE, - 'AUTH_PROVIDER_SECRETS_ARN': params[f"/{PROJECT_PREFIX}/auth/auth-provider-secrets-arn"], - - # OAuth configuration - 'OAUTH_TOKEN_ENCRYPTION_KEY_ARN': params[f"/{PROJECT_PREFIX}/oauth/token-encryption-key-arn"], - 'OAUTH_CLIENT_SECRETS_ARN': params[f"/{PROJECT_PREFIX}/oauth/client-secrets-arn"], - 'OAUTH_CALLBACK_URL': callback_url, - - # AgentCore resources (from shared_resources parameter) - 'MEMORY_ARN': shared_resources['memory_arn'], - 'MEMORY_ID': shared_resources['memory_id'], - 'CODE_INTERPRETER_ID': shared_resources['code_interpreter_id'], - 'BROWSER_ID': shared_resources['browser_id'], - 'GATEWAY_URL': shared_resources['gateway_url'], - - # AgentCore Memory configuration - 'AGENTCORE_MEMORY_TYPE': 'dynamodb', - 'AGENTCORE_MEMORY_ID': shared_resources['memory_id'], - - # S3 storage - 'S3_ASSISTANTS_VECTOR_STORE_BUCKET_NAME': params[f"/{PROJECT_PREFIX}/rag/vector-bucket-name"], - 'S3_ASSISTANTS_VECTOR_STORE_INDEX_NAME': params[f"/{PROJECT_PREFIX}/rag/vector-index-name"], - - # Authentication - 'ENABLE_AUTHENTICATION': 'true', - - # Directories (runtime-specific paths) - 'UPLOAD_DIR': '/tmp/uploads', - 'OUTPUT_DIR': '/tmp/output', - 'GENERATED_IMAGES_DIR': '/tmp/generated_images', - - # URLs - 'API_URL': alb_url, - 'FRONTEND_URL': frontend_url, - 'CORS_ORIGINS': params[f"/{PROJECT_PREFIX}/frontend/cors-origins"], - } - - logger.info(f"Constructed {len(env_vars)} environment variables for runtime") - return env_vars - - except ClientError as e: - logger.error(f"Failed to fetch environment variables from SSM: {e}") - raise ValueError(f"Could not fetch environment variables: {e}") diff --git a/backend/lambda-functions/runtime-provisioner/requirements.txt b/backend/lambda-functions/runtime-provisioner/requirements.txt deleted file mode 100644 index 2990fb2a..00000000 --- a/backend/lambda-functions/runtime-provisioner/requirements.txt +++ /dev/null @@ -1 +0,0 @@ -boto3==1.42.51 diff --git a/backend/lambda-functions/runtime-provisioner/tests/__init__.py b/backend/lambda-functions/runtime-provisioner/tests/__init__.py deleted file mode 100644 index e69de29b..00000000 diff --git a/backend/lambda-functions/runtime-provisioner/tests/conftest.py b/backend/lambda-functions/runtime-provisioner/tests/conftest.py deleted file mode 100644 index b635dfcc..00000000 --- a/backend/lambda-functions/runtime-provisioner/tests/conftest.py +++ /dev/null @@ -1,333 +0,0 @@ -""" -Test fixtures for runtime-provisioner Lambda. - -Handles the tricky module-level side effects: - - pip install at import time (lines 20-22) - - boto3 client creation at module level (lines 31-34) - - os.environ reads at module level (lines 37-39) -""" -import importlib -import os -import sys -from unittest.mock import MagicMock, patch - -import boto3 -import pytest -from moto import mock_aws - -# --------------------------------------------------------------------------- -# Constants -# --------------------------------------------------------------------------- -PROJECT_PREFIX = "test-project" -AWS_REGION = "us-east-1" -AUTH_PROVIDERS_TABLE = "test-auth-providers" - -# All SSM parameters the Lambda reads, with deterministic test values. -SSM_PARAMS: dict[str, str] = { - # DynamoDB tables (get_runtime_environment_variables) - f"/{PROJECT_PREFIX}/users/users-table-name": "test-users-table", - f"/{PROJECT_PREFIX}/rbac/app-roles-table-name": "test-app-roles-table", - f"/{PROJECT_PREFIX}/auth/oidc-state-table-name": "test-oidc-state-table", - f"/{PROJECT_PREFIX}/auth/api-keys-table-name": "test-api-keys-table", - f"/{PROJECT_PREFIX}/oauth/providers-table-name": "test-oauth-providers-table", - f"/{PROJECT_PREFIX}/oauth/user-tokens-table-name": "test-user-tokens-table", - f"/{PROJECT_PREFIX}/rag/assistants-table-name": "test-assistants-table", - f"/{PROJECT_PREFIX}/quota/user-quotas-table-name": "test-user-quotas-table", - f"/{PROJECT_PREFIX}/quota/quota-events-table-name": "test-quota-events-table", - f"/{PROJECT_PREFIX}/cost-tracking/sessions-metadata-table-name": "test-sessions-metadata-table", - f"/{PROJECT_PREFIX}/cost-tracking/user-cost-summary-table-name": "test-user-cost-summary-table", - f"/{PROJECT_PREFIX}/cost-tracking/system-cost-rollup-table-name": "test-system-cost-rollup-table", - f"/{PROJECT_PREFIX}/admin/managed-models-table-name": "test-managed-models-table", - # File upload - f"/{PROJECT_PREFIX}/user-file-uploads/table-name": "test-user-files-table", - # Auth / OAuth secrets & URLs - f"/{PROJECT_PREFIX}/auth/auth-provider-secrets-arn": "arn:aws:secretsmanager:us-east-1:123456789012:secret:test-auth-secrets", - f"/{PROJECT_PREFIX}/oauth/token-encryption-key-arn": "arn:aws:kms:us-east-1:123456789012:key/test-token-key", - f"/{PROJECT_PREFIX}/oauth/client-secrets-arn": "arn:aws:secretsmanager:us-east-1:123456789012:secret:test-client-secrets", - f"/{PROJECT_PREFIX}/oauth/callback-url": "https://app.example.com/oauth/callback", - # S3 / RAG - f"/{PROJECT_PREFIX}/rag/vector-bucket-name": "test-vector-bucket", - f"/{PROJECT_PREFIX}/rag/vector-index-name": "test-vector-index", - # Network / Frontend - f"/{PROJECT_PREFIX}/network/alb-url": "https://alb.example.com", - f"/{PROJECT_PREFIX}/frontend/url": "https://app.example.com", - f"/{PROJECT_PREFIX}/frontend/cors-origins": "https://app.example.com", - # create_runtime() params - f"/{PROJECT_PREFIX}/inference-api/image-tag": "latest", - f"/{PROJECT_PREFIX}/inference-api/ecr-repository-uri": "123456789012.dkr.ecr.us-east-1.amazonaws.com/test-repo", - f"/{PROJECT_PREFIX}/inference-api/runtime-execution-role-arn": "arn:aws:iam::123456789012:role/test-runtime-role", - # Shared resources (get_shared_resource_ids) - f"/{PROJECT_PREFIX}/inference-api/memory-arn": "arn:aws:bedrock:us-east-1:123456789012:memory/test-memory", - f"/{PROJECT_PREFIX}/inference-api/memory-id": "test-memory-id", - f"/{PROJECT_PREFIX}/inference-api/code-interpreter-id": "test-code-interpreter-id", - f"/{PROJECT_PREFIX}/inference-api/browser-id": "test-browser-id", - f"/{PROJECT_PREFIX}/gateway/gateway-url": "https://gateway.example.com", -} - -# --------------------------------------------------------------------------- -# A – Environment variables (autouse so every test gets them) -# --------------------------------------------------------------------------- - -@pytest.fixture(autouse=True) -def _env_vars(monkeypatch): - """Set the environment variables the Lambda reads at module level.""" - monkeypatch.setenv("PROJECT_PREFIX", PROJECT_PREFIX) - monkeypatch.setenv("AWS_REGION", AWS_REGION) - monkeypatch.setenv("AWS_DEFAULT_REGION", AWS_REGION) - monkeypatch.setenv("AUTH_PROVIDERS_TABLE", AUTH_PROVIDERS_TABLE) - # moto needs a dummy credential set - monkeypatch.setenv("AWS_ACCESS_KEY_ID", "testing") - monkeypatch.setenv("AWS_SECRET_ACCESS_KEY", "testing") - monkeypatch.setenv("AWS_SECURITY_TOKEN", "testing") - monkeypatch.setenv("AWS_SESSION_TOKEN", "testing") - - -# --------------------------------------------------------------------------- -# B – pip install no-op -# --------------------------------------------------------------------------- - -@pytest.fixture() -def _patch_pip(): - """Prevent the Lambda from running pip install at import time.""" - with patch("pip._internal.main", return_value=None): - yield - - -# --------------------------------------------------------------------------- -# C / D / E – moto-backed AWS services + bedrock mock + module import -# --------------------------------------------------------------------------- - -def _make_mock_bedrock_client() -> MagicMock: - """Return a MagicMock that behaves like a bedrock-agentcore-control client.""" - client = MagicMock(name="bedrock-agentcore-control") - client.create_agent_runtime.return_value = { - "agentRuntimeArn": "arn:aws:bedrock:us-east-1:123456789012:agent-runtime/test-runtime-id", - "agentRuntimeId": "test-runtime-id", - } - client.update_agent_runtime.return_value = {} - client.delete_agent_runtime.return_value = {} - client.get_agent_runtime.return_value = { - "agentRuntimeId": "test-runtime-id", - "agentRuntimeArn": "arn:aws:bedrock:us-east-1:123456789012:agent-runtime/test-runtime-id", - "agentRuntimeName": "test_project_runtime_provider1", - "agentRuntimeArtifact": { - "containerConfiguration": { - "containerUri": "123456789012.dkr.ecr.us-east-1.amazonaws.com/test-repo:latest", - } - }, - "authorizerConfiguration": { - "customJWTAuthorizer": { - "discoveryUrl": "https://auth.example.com/.well-known/openid-configuration", - "allowedAudience": ["test-client-id"], - } - }, - "networkConfiguration": {"networkMode": "PUBLIC"}, - "roleArn": "arn:aws:iam::123456789012:role/test-runtime-role", - "requestHeaderConfiguration": { - "requestHeaderAllowlist": ["Authorization"] - }, - "environmentVariables": {"TABLE_NAME": "my-table", "API_KEY": "secret-123"}, - "status": "ACTIVE", - } - return client - - -@pytest.fixture() -def mock_bedrock_client(): - """Expose the mock bedrock-agentcore-control client for assertions.""" - return _make_mock_bedrock_client() - - -@pytest.fixture() -def lambda_module(_env_vars, _patch_pip, mock_bedrock_client): - """Import (or reimport) lambda_function inside fully-mocked AWS context. - - Yields a tuple of ``(module, mock_bedrock_client)`` so tests can - both invoke handlers and assert on the bedrock mock. - """ - bedrock_mock = mock_bedrock_client - - # Intercept boto3.client: route bedrock-agentcore-control to our mock, - # let everything else fall through to moto. - _real_boto3_client = boto3.client - - def _patched_client(service_name, *args, **kwargs): - if service_name == "bedrock-agentcore-control": - return bedrock_mock - return _real_boto3_client(service_name, *args, **kwargs) - - with mock_aws(): - # Pre-populate moto resources BEFORE the module import so that - # module-level code (and any eager reads) find them. - _create_dynamodb_table() - _create_ssm_parameters() - - with patch("boto3.client", side_effect=_patched_client): - # Remove cached module so the reload picks up our patches. - sys.modules.pop("lambda_function", None) - - # Ensure the Lambda directory is on sys.path so the bare - # ``import lambda_function`` inside the fixture works. - lambda_dir = os.path.join( - os.path.dirname(__file__), os.pardir - ) - abs_lambda_dir = os.path.abspath(lambda_dir) - if abs_lambda_dir not in sys.path: - sys.path.insert(0, abs_lambda_dir) - - import lambda_function # noqa: F811 - - importlib.reload(lambda_function) - - # Replace module-level client refs so test-time calls also - # go through moto / mock (reload already did this, but be - # explicit for safety). - lambda_function.bedrock_agentcore = bedrock_mock - - yield lambda_function, bedrock_mock - - # Cleanup: remove from sys.modules to avoid polluting other tests. - sys.modules.pop("lambda_function", None) - - -# --------------------------------------------------------------------------- -# D – DynamoDB table -# --------------------------------------------------------------------------- - -def _create_dynamodb_table(): - """Create the AuthProviders table in moto.""" - client = boto3.client("dynamodb", region_name=AWS_REGION) - client.create_table( - TableName=AUTH_PROVIDERS_TABLE, - KeySchema=[ - {"AttributeName": "PK", "KeyType": "HASH"}, - {"AttributeName": "SK", "KeyType": "RANGE"}, - ], - AttributeDefinitions=[ - {"AttributeName": "PK", "AttributeType": "S"}, - {"AttributeName": "SK", "AttributeType": "S"}, - ], - BillingMode="PAY_PER_REQUEST", - StreamSpecification={ - "StreamEnabled": True, - "StreamViewType": "NEW_AND_OLD_IMAGES", - }, - ) - - -@pytest.fixture() -def auth_providers_table(lambda_module): - """Return a ready-to-use DynamoDB table name (table already created).""" - return AUTH_PROVIDERS_TABLE - - -# --------------------------------------------------------------------------- -# E – SSM parameters -# --------------------------------------------------------------------------- - -def _create_ssm_parameters(): - """Seed all SSM parameters into moto.""" - client = boto3.client("ssm", region_name=AWS_REGION) - for name, value in SSM_PARAMS.items(): - client.put_parameter(Name=name, Value=value, Type="String") - - -# --------------------------------------------------------------------------- -# G – DynamoDB Stream event factories -# --------------------------------------------------------------------------- - -def make_insert_event( - provider_id: str, - issuer_url: str, - client_id: str, - jwks_uri: str | None = None, - display_name: str | None = None, -) -> dict: - """Create a DynamoDB Stream INSERT event.""" - new_image: dict = { - "PK": {"S": f"AUTH_PROVIDER#{provider_id}"}, - "SK": {"S": f"AUTH_PROVIDER#{provider_id}"}, - "providerId": {"S": provider_id}, - "issuerUrl": {"S": issuer_url}, - "clientId": {"S": client_id}, - "displayName": {"S": display_name or f"Test Provider {provider_id}"}, - } - if jwks_uri is not None: - new_image["jwksUri"] = {"S": jwks_uri} - return { - "Records": [ - { - "eventName": "INSERT", - "dynamodb": {"NewImage": new_image}, - } - ] - } - - -def make_modify_event( - provider_id: str, - old_issuer_url: str, - new_issuer_url: str, - old_client_id: str, - new_client_id: str, - runtime_id: str = "test-runtime-id", - old_jwks_uri: str | None = None, - new_jwks_uri: str | None = None, -) -> dict: - """Create a DynamoDB Stream MODIFY event.""" - old_image: dict = { - "PK": {"S": f"AUTH_PROVIDER#{provider_id}"}, - "SK": {"S": f"AUTH_PROVIDER#{provider_id}"}, - "providerId": {"S": provider_id}, - "issuerUrl": {"S": old_issuer_url}, - "clientId": {"S": old_client_id}, - "displayName": {"S": f"Test Provider {provider_id}"}, - "agentcoreRuntimeId": {"S": runtime_id}, - } - new_image: dict = { - "PK": {"S": f"AUTH_PROVIDER#{provider_id}"}, - "SK": {"S": f"AUTH_PROVIDER#{provider_id}"}, - "providerId": {"S": provider_id}, - "issuerUrl": {"S": new_issuer_url}, - "clientId": {"S": new_client_id}, - "displayName": {"S": f"Test Provider {provider_id}"}, - "agentcoreRuntimeId": {"S": runtime_id}, - } - if old_jwks_uri is not None: - old_image["jwksUri"] = {"S": old_jwks_uri} - if new_jwks_uri is not None: - new_image["jwksUri"] = {"S": new_jwks_uri} - return { - "Records": [ - { - "eventName": "MODIFY", - "dynamodb": { - "OldImage": old_image, - "NewImage": new_image, - }, - } - ] - } - - -def make_remove_event( - provider_id: str, - runtime_id: str | None = None, -) -> dict: - """Create a DynamoDB Stream REMOVE event.""" - old_image: dict = { - "PK": {"S": f"AUTH_PROVIDER#{provider_id}"}, - "SK": {"S": f"AUTH_PROVIDER#{provider_id}"}, - "providerId": {"S": provider_id}, - "displayName": {"S": f"Test Provider {provider_id}"}, - } - if runtime_id is not None: - old_image["agentcoreRuntimeId"] = {"S": runtime_id} - return { - "Records": [ - { - "eventName": "REMOVE", - "dynamodb": {"OldImage": old_image}, - } - ] - } diff --git a/backend/lambda-functions/runtime-provisioner/tests/test_handler.py b/backend/lambda-functions/runtime-provisioner/tests/test_handler.py deleted file mode 100644 index d89d5f78..00000000 --- a/backend/lambda-functions/runtime-provisioner/tests/test_handler.py +++ /dev/null @@ -1,113 +0,0 @@ -""" -Tests for runtime-provisioner lambda_handler event routing. -""" -import sys -import os - -_tests_dir = os.path.dirname(__file__) -if _tests_dir not in sys.path: - sys.path.insert(0, _tests_dir) - -from conftest import make_insert_event, make_modify_event, make_remove_event - - -def test_insert_event_routes_to_handle_insert(lambda_module): - """INSERT event calls create_runtime and updates DynamoDB.""" - mod, bedrock = lambda_module - event = make_insert_event("provider1", "https://auth.example.com", "client-1") - mod.lambda_handler(event, {}) - - bedrock.create_agent_runtime.assert_called_once() - - -def test_modify_event_routes_to_handle_modify(lambda_module): - """MODIFY event with JWT changes triggers update_agent_runtime.""" - mod, bedrock = lambda_module - event = make_modify_event( - "provider1", - old_issuer_url="https://old.example.com", - new_issuer_url="https://new.example.com", - old_client_id="old-client", - new_client_id="new-client", - ) - mod.lambda_handler(event, {}) - - bedrock.get_agent_runtime.assert_called_once() - bedrock.update_agent_runtime.assert_called_once() - - -def test_remove_event_routes_to_handle_remove(lambda_module): - """REMOVE event triggers delete_agent_runtime.""" - mod, bedrock = lambda_module - event = make_remove_event("provider1", runtime_id="test-runtime-id") - mod.lambda_handler(event, {}) - - bedrock.delete_agent_runtime.assert_called_once_with( - agentRuntimeId="test-runtime-id" - ) - - -def test_unknown_event_type_ignored(lambda_module): - """Event with unknown eventName logs warning but doesn't crash.""" - mod, bedrock = lambda_module - event = { - "Records": [ - { - "eventName": "UNKNOWN", - "dynamodb": {"NewImage": {}}, - } - ] - } - result = mod.lambda_handler(event, {}) - - assert result["statusCode"] == 200 - bedrock.create_agent_runtime.assert_not_called() - bedrock.update_agent_runtime.assert_not_called() - bedrock.delete_agent_runtime.assert_not_called() - - -def test_multiple_records_processed(lambda_module): - """Event with 3 records (INSERT, MODIFY, REMOVE) all get processed.""" - mod, bedrock = lambda_module - - insert_rec = make_insert_event( - "prov-a", "https://auth.example.com", "client-a" - )["Records"][0] - modify_rec = make_modify_event( - "prov-b", - old_issuer_url="https://old.example.com", - new_issuer_url="https://new.example.com", - old_client_id="old-b", - new_client_id="new-b", - )["Records"][0] - remove_rec = make_remove_event( - "prov-c", runtime_id="rt-c" - )["Records"][0] - - event = {"Records": [insert_rec, modify_rec, remove_rec]} - mod.lambda_handler(event, {}) - - assert bedrock.create_agent_runtime.call_count == 1 - assert bedrock.update_agent_runtime.call_count == 1 - assert bedrock.delete_agent_runtime.call_count == 1 - - -def test_handler_returns_200_on_success(lambda_module): - """Handler returns statusCode 200 on successful processing.""" - mod, _ = lambda_module - event = make_insert_event("prov-ok", "https://auth.example.com", "cid") - result = mod.lambda_handler(event, {}) - - assert result["statusCode"] == 200 - - -def test_handler_reraises_on_exception(lambda_module): - """If the for-loop itself blows up, the handler re-raises.""" - mod, _ = lambda_module - # Records must be iterable; passing a non-iterable triggers TypeError - # inside the try block before any handle_* is called. - event = {"Records": "not-a-list"} - import pytest - - with pytest.raises(TypeError): - mod.lambda_handler(event, {}) diff --git a/backend/lambda-functions/runtime-provisioner/tests/test_helpers.py b/backend/lambda-functions/runtime-provisioner/tests/test_helpers.py deleted file mode 100644 index a3214981..00000000 --- a/backend/lambda-functions/runtime-provisioner/tests/test_helpers.py +++ /dev/null @@ -1,255 +0,0 @@ -"""Tests for runtime-provisioner helper functions.""" -import sys -import os - -import pytest -from botocore.exceptions import ClientError - -_tests_dir = os.path.dirname(__file__) -if _tests_dir not in sys.path: - sys.path.insert(0, _tests_dir) -from conftest import PROJECT_PREFIX, AUTH_PROVIDERS_TABLE, SSM_PARAMS - - -# ── deserialize_dynamodb_value ────────────────────────────────────────────── - -class TestDeserializeDynamoDBValue: - - def test_deserialize_string(self, lambda_module): - mod, _ = lambda_module - assert mod.deserialize_dynamodb_value({'S': 'hello'}) == 'hello' - - def test_deserialize_number(self, lambda_module): - mod, _ = lambda_module - assert mod.deserialize_dynamodb_value({'N': '42'}) == '42' - - def test_deserialize_bool_true(self, lambda_module): - mod, _ = lambda_module - assert mod.deserialize_dynamodb_value({'BOOL': True}) is True - - def test_deserialize_bool_false(self, lambda_module): - mod, _ = lambda_module - assert mod.deserialize_dynamodb_value({'BOOL': False}) is False - - def test_deserialize_null(self, lambda_module): - mod, _ = lambda_module - assert mod.deserialize_dynamodb_value({'NULL': True}) is None - - def test_deserialize_list(self, lambda_module): - mod, _ = lambda_module - result = mod.deserialize_dynamodb_value({'L': [{'S': 'a'}, {'N': '1'}]}) - assert result == ['a', '1'] - - def test_deserialize_map(self, lambda_module): - mod, _ = lambda_module - result = mod.deserialize_dynamodb_value({'M': {'key': {'S': 'val'}}}) - assert result == {'key': 'val'} - - def test_deserialize_empty(self, lambda_module): - mod, _ = lambda_module - assert mod.deserialize_dynamodb_value({}) is None - - def test_deserialize_none(self, lambda_module): - mod, _ = lambda_module - assert mod.deserialize_dynamodb_value(None) is None - - def test_deserialize_nested(self, lambda_module): - mod, _ = lambda_module - result = mod.deserialize_dynamodb_value( - {'M': {'items': {'L': [{'S': 'x'}]}}} - ) - assert result == {'items': ['x']} - - -# ── normalize_url ─────────────────────────────────────────────────────────── - -class TestNormalizeUrl: - - def test_normalize_url_with_https(self, lambda_module): - mod, _ = lambda_module - assert mod.normalize_url('https://example.com') == 'https://example.com' - - def test_normalize_url_with_http(self, lambda_module): - mod, _ = lambda_module - assert mod.normalize_url('http://example.com') == 'http://example.com' - - def test_normalize_url_bare_domain(self, lambda_module): - mod, _ = lambda_module - assert mod.normalize_url('example.com') == 'https://example.com' - - def test_normalize_url_empty(self, lambda_module): - mod, _ = lambda_module - assert mod.normalize_url('') == '' - - def test_normalize_url_whitespace(self, lambda_module): - mod, _ = lambda_module - assert mod.normalize_url(' example.com ') == 'https://example.com' - - -# ── validate_url ──────────────────────────────────────────────────────────── - -class TestValidateUrl: - - def test_validate_url_valid(self, lambda_module): - mod, _ = lambda_module - assert mod.validate_url('example.com', 'test_param') == 'https://example.com' - - def test_validate_url_empty_raises(self, lambda_module): - mod, _ = lambda_module - with pytest.raises(ValueError, match='Empty URL value for test_param'): - mod.validate_url('', 'test_param') - - def test_validate_url_whitespace_only_raises(self, lambda_module): - mod, _ = lambda_module - with pytest.raises(ValueError, match='Empty URL value for test_param'): - mod.validate_url(' ', 'test_param') - - -# ── determine_discovery_url ───────────────────────────────────────────────── - -class TestDetermineDiscoveryUrl: - - def test_discovery_url_basic(self, lambda_module): - mod, _ = lambda_module - result = mod.determine_discovery_url('https://auth.example.com', None) - assert result == 'https://auth.example.com/.well-known/openid-configuration' - - def test_discovery_url_trailing_slash(self, lambda_module): - mod, _ = lambda_module - result = mod.determine_discovery_url('https://auth.example.com/', None) - assert result == 'https://auth.example.com/.well-known/openid-configuration' - - -# ── SSM helpers ───────────────────────────────────────────────────────────── - -class TestSSMHelpers: - - def test_get_optional_parameter_found(self, lambda_module): - mod, _ = lambda_module - param = f"/{PROJECT_PREFIX}/inference-api/image-tag" - assert mod.get_optional_parameter(param) == 'latest' - - def test_get_optional_parameter_not_found(self, lambda_module): - mod, _ = lambda_module - assert mod.get_optional_parameter('/nonexistent/param') is None - - def test_get_required_parameter_found(self, lambda_module): - mod, _ = lambda_module - param = f"/{PROJECT_PREFIX}/inference-api/image-tag" - assert mod.get_required_parameter(param) == 'latest' - - def test_get_required_parameter_not_found_raises(self, lambda_module): - mod, _ = lambda_module - with pytest.raises(ClientError): - mod.get_required_parameter('/nonexistent/param') - - def test_get_container_image_tag(self, lambda_module): - mod, _ = lambda_module - assert mod.get_container_image_tag() == 'latest' - - def test_get_container_image_uri(self, lambda_module): - mod, _ = lambda_module - uri = mod.get_container_image_uri('latest') - expected = '123456789012.dkr.ecr.us-east-1.amazonaws.com/test-repo:latest' - assert uri == expected - - def test_get_runtime_execution_role_arn(self, lambda_module): - mod, _ = lambda_module - arn = mod.get_runtime_execution_role_arn() - assert arn == 'arn:aws:iam::123456789012:role/test-runtime-role' - - def test_get_shared_resource_ids(self, lambda_module): - mod, _ = lambda_module - result = mod.get_shared_resource_ids() - assert result['memory_arn'] == 'arn:aws:bedrock:us-east-1:123456789012:memory/test-memory' - assert result['memory_id'] == 'test-memory-id' - assert result['code_interpreter_id'] == 'test-code-interpreter-id' - assert result['browser_id'] == 'test-browser-id' - assert result['gateway_url'] == 'https://gateway.example.com' - - def test_store_runtime_arn_in_ssm(self, lambda_module): - mod, _ = lambda_module - mod.store_runtime_arn_in_ssm('prov1', 'arn:aws:bedrock:us-east-1:123456789012:runtime/rt-1') - resp = mod.ssm.get_parameter(Name=f'/{PROJECT_PREFIX}/runtimes/prov1/arn') - assert resp['Parameter']['Value'] == 'arn:aws:bedrock:us-east-1:123456789012:runtime/rt-1' - - def test_delete_runtime_arn_from_ssm(self, lambda_module): - mod, _ = lambda_module - mod.store_runtime_arn_in_ssm('prov2', 'arn:aws:bedrock:us-east-1:123456789012:runtime/rt-2') - mod.delete_runtime_arn_from_ssm('prov2') - with pytest.raises(ClientError): - mod.ssm.get_parameter(Name=f'/{PROJECT_PREFIX}/runtimes/prov2/arn') - - def test_delete_runtime_arn_not_found_ok(self, lambda_module): - mod, _ = lambda_module - # Should not raise even if param doesn't exist - mod.delete_runtime_arn_from_ssm('nonexistent-provider') - - -# ── DynamoDB update helpers ───────────────────────────────────────────────── - -def _insert_provider(mod, provider_id): - """Insert a minimal provider record for update tests.""" - mod.dynamodb.put_item( - TableName=AUTH_PROVIDERS_TABLE, - Item={ - 'PK': {'S': f'AUTH_PROVIDER#{provider_id}'}, - 'SK': {'S': f'AUTH_PROVIDER#{provider_id}'}, - 'providerId': {'S': provider_id}, - }, - ) - - -def _get_provider(mod, provider_id): - """Read back a provider record.""" - resp = mod.dynamodb.get_item( - TableName=AUTH_PROVIDERS_TABLE, - Key={ - 'PK': {'S': f'AUTH_PROVIDER#{provider_id}'}, - 'SK': {'S': f'AUTH_PROVIDER#{provider_id}'}, - }, - ) - return resp['Item'] - - -class TestDynamoDBUpdateHelpers: - - def test_update_provider_runtime_info(self, lambda_module): - mod, _ = lambda_module - _insert_provider(mod, 'prov1') - mod.update_provider_runtime_info( - 'prov1', - 'arn:aws:bedrock:us-east-1:123456789012:runtime/rt-1', - 'rt-1', - 'https://endpoint.example.com', - 'READY', - ) - item = _get_provider(mod, 'prov1') - assert item['agentcoreRuntimeArn']['S'] == 'arn:aws:bedrock:us-east-1:123456789012:runtime/rt-1' - assert item['agentcoreRuntimeId']['S'] == 'rt-1' - assert item['agentcoreRuntimeEndpointUrl']['S'] == 'https://endpoint.example.com' - assert item['agentcoreRuntimeStatus']['S'] == 'READY' - assert 'updatedAt' in item - - def test_update_provider_runtime_status(self, lambda_module): - mod, _ = lambda_module - _insert_provider(mod, 'prov2') - mod.update_provider_runtime_status('prov2', 'PROVISIONING') - item = _get_provider(mod, 'prov2') - assert item['agentcoreRuntimeStatus']['S'] == 'PROVISIONING' - - def test_update_provider_runtime_error(self, lambda_module): - mod, _ = lambda_module - _insert_provider(mod, 'prov3') - mod.update_provider_runtime_error('prov3', 'Something went wrong') - item = _get_provider(mod, 'prov3') - assert item['agentcoreRuntimeStatus']['S'] == 'FAILED' - assert item['agentcoreRuntimeError']['S'] == 'Something went wrong' - - def test_update_provider_runtime_error_truncation(self, lambda_module): - mod, _ = lambda_module - _insert_provider(mod, 'prov4') - long_error = 'x' * 2000 - mod.update_provider_runtime_error('prov4', long_error) - item = _get_provider(mod, 'prov4') - assert len(item['agentcoreRuntimeError']['S']) == 1000 diff --git a/backend/lambda-functions/runtime-provisioner/tests/test_insert.py b/backend/lambda-functions/runtime-provisioner/tests/test_insert.py deleted file mode 100644 index cd70562b..00000000 --- a/backend/lambda-functions/runtime-provisioner/tests/test_insert.py +++ /dev/null @@ -1,199 +0,0 @@ -""" -Tests for runtime-provisioner INSERT / create-runtime flow. -""" -import sys -import os -from urllib.parse import quote - -_tests_dir = os.path.dirname(__file__) -if _tests_dir not in sys.path: - sys.path.insert(0, _tests_dir) - -from conftest import make_insert_event, PROJECT_PREFIX - -RUNTIME_ARN = "arn:aws:bedrock:us-east-1:123456789012:agent-runtime/test-runtime-id" -RUNTIME_ID = "test-runtime-id" - - -def _get_ddb_item(mod, provider_id): - """Read the auth-provider item back from moto DynamoDB.""" - resp = mod.dynamodb.get_item( - TableName="test-auth-providers", - Key={ - "PK": {"S": f"AUTH_PROVIDER#{provider_id}"}, - "SK": {"S": f"AUTH_PROVIDER#{provider_id}"}, - }, - ) - return resp.get("Item") - - -# ── 1. Happy-path: bedrock create called ────────────────────────────────── - -def test_insert_creates_runtime(lambda_module): - """INSERT event → bedrock create_agent_runtime is called.""" - mod, bedrock = lambda_module - event = make_insert_event("prov1", "https://issuer.example.com", "cid-1") - mod.lambda_handler(event, {}) - - bedrock.create_agent_runtime.assert_called_once() - - -# ── 2. DynamoDB updated with runtime info ───────────────────────────────── - -def test_insert_updates_dynamodb_with_runtime_info(lambda_module): - """After create, DynamoDB has runtime ARN, ID, endpoint URL, status READY.""" - mod, _ = lambda_module - event = make_insert_event("prov2", "https://issuer.example.com", "cid-2") - mod.lambda_handler(event, {}) - - item = _get_ddb_item(mod, "prov2") - assert item is not None - assert item["agentcoreRuntimeArn"]["S"] == RUNTIME_ARN - assert item["agentcoreRuntimeId"]["S"] == RUNTIME_ID - assert item["agentcoreRuntimeStatus"]["S"] == "READY" - assert "agentcoreRuntimeEndpointUrl" in item - - -# ── 3. SSM param stored ────────────────────────────────────────────────── - -def test_insert_stores_runtime_arn_in_ssm(lambda_module): - """SSM param /{prefix}/runtimes/{provider_id}/arn is created.""" - mod, _ = lambda_module - event = make_insert_event("prov3", "https://issuer.example.com", "cid-3") - mod.lambda_handler(event, {}) - - ssm_resp = mod.ssm.get_parameter( - Name=f"/{PROJECT_PREFIX}/runtimes/prov3/arn" - ) - assert ssm_resp["Parameter"]["Value"] == RUNTIME_ARN - - -# ── 4. Runtime name format ──────────────────────────────────────────────── - -def test_insert_runtime_name_format(lambda_module): - """Runtime name uses underscores: {safe_prefix}_runtime_{safe_provider_id}.""" - mod, bedrock = lambda_module - event = make_insert_event("my-provider", "https://issuer.example.com", "cid") - mod.lambda_handler(event, {}) - - call_kwargs = bedrock.create_agent_runtime.call_args[1] - name = call_kwargs["agentRuntimeName"] - assert "_" in name - assert "-" not in name - expected = f"{PROJECT_PREFIX.replace('-', '_')}_runtime_my_provider" - assert name == expected - - -# ── 5. JWT authorizer config ───────────────────────────────────────────── - -def test_insert_jwt_authorizer_config(lambda_module): - """CreateAgentRuntime has correct discoveryUrl and allowedAudience.""" - mod, bedrock = lambda_module - event = make_insert_event("prov5", "https://issuer.example.com", "aud-5") - mod.lambda_handler(event, {}) - - call_kwargs = bedrock.create_agent_runtime.call_args[1] - auth_cfg = call_kwargs["authorizerConfiguration"]["customJWTAuthorizer"] - assert auth_cfg["discoveryUrl"] == "https://issuer.example.com/.well-known/openid-configuration" - assert auth_cfg["allowedAudience"] == ["aud-5"] - - -# ── 6. Container image from SSM ────────────────────────────────────────── - -def test_insert_container_image_from_ssm(lambda_module): - """Container URI built from SSM ecr-repository-uri + image-tag.""" - mod, bedrock = lambda_module - event = make_insert_event("prov6", "https://issuer.example.com", "cid-6") - mod.lambda_handler(event, {}) - - call_kwargs = bedrock.create_agent_runtime.call_args[1] - uri = call_kwargs["agentRuntimeArtifact"]["containerConfiguration"]["containerUri"] - assert uri == "123456789012.dkr.ecr.us-east-1.amazonaws.com/test-repo:latest" - - -# ── 7. Environment variables passed ────────────────────────────────────── - -def test_insert_environment_variables_passed(lambda_module): - """All 30+ env vars passed to CreateAgentRuntime.""" - mod, bedrock = lambda_module - event = make_insert_event("prov7", "https://issuer.example.com", "cid-7") - mod.lambda_handler(event, {}) - - call_kwargs = bedrock.create_agent_runtime.call_args[1] - env_vars = call_kwargs["environmentVariables"] - assert len(env_vars) >= 30 - assert env_vars["PROJECT_NAME"] == PROJECT_PREFIX - assert env_vars["PROVIDER_ID"] == "prov7" - assert env_vars["ENABLE_AUTHENTICATION"] == "true" - - -# ── 8. Endpoint URL encoded ────────────────────────────────────────────── - -def test_insert_endpoint_url_encoded(lambda_module): - """Endpoint URL has URL-encoded runtime ARN.""" - mod, _ = lambda_module - event = make_insert_event("prov8", "https://issuer.example.com", "cid-8") - mod.lambda_handler(event, {}) - - item = _get_ddb_item(mod, "prov8") - endpoint = item["agentcoreRuntimeEndpointUrl"]["S"] - encoded_arn = quote(RUNTIME_ARN, safe="") - assert encoded_arn in endpoint - assert endpoint.startswith("https://bedrock-agentcore.") - assert endpoint.endswith("/invocations") - - -# ── 9. Failure updates DynamoDB with error ──────────────────────────────── - -def test_insert_failure_updates_dynamodb_error(lambda_module): - """When bedrock create fails, DynamoDB gets FAILED status + error message.""" - mod, bedrock = lambda_module - bedrock.create_agent_runtime.side_effect = Exception("Boom!") - - event = make_insert_event("prov9", "https://issuer.example.com", "cid-9") - mod.lambda_handler(event, {}) - - item = _get_ddb_item(mod, "prov9") - assert item is not None - assert item["agentcoreRuntimeStatus"]["S"] == "FAILED" - assert "Boom!" in item["agentcoreRuntimeError"]["S"] - - -# ── 10. Failure does NOT re-raise ───────────────────────────────────────── - -def test_insert_failure_does_not_reraise(lambda_module): - """Error in handle_insert is caught; handler still returns 200.""" - mod, bedrock = lambda_module - bedrock.create_agent_runtime.side_effect = Exception("kaboom") - - event = make_insert_event("prov10", "https://issuer.example.com", "cid-10") - result = mod.lambda_handler(event, {}) - - assert result["statusCode"] == 200 - - -# ── 11. Discovery URL from issuer ──────────────────────────────────────── - -def test_insert_discovery_url_from_issuer(lambda_module): - """Discovery URL is {issuerUrl}/.well-known/openid-configuration.""" - mod, bedrock = lambda_module - event = make_insert_event("prov11", "https://login.example.com", "cid-11") - mod.lambda_handler(event, {}) - - call_kwargs = bedrock.create_agent_runtime.call_args[1] - disc = call_kwargs["authorizerConfiguration"]["customJWTAuthorizer"]["discoveryUrl"] - assert disc == "https://login.example.com/.well-known/openid-configuration" - - -# ── 12. Trailing slash stripped ─────────────────────────────────────────── - -def test_insert_issuer_url_trailing_slash_stripped(lambda_module): - """Trailing slash on issuerUrl is removed before constructing discovery URL.""" - mod, bedrock = lambda_module - event = make_insert_event("prov12", "https://login.example.com/", "cid-12") - mod.lambda_handler(event, {}) - - call_kwargs = bedrock.create_agent_runtime.call_args[1] - disc = call_kwargs["authorizerConfiguration"]["customJWTAuthorizer"]["discoveryUrl"] - assert disc == "https://login.example.com/.well-known/openid-configuration" - assert "//." not in disc diff --git a/backend/lambda-functions/runtime-provisioner/tests/test_modify.py b/backend/lambda-functions/runtime-provisioner/tests/test_modify.py deleted file mode 100644 index f9d71786..00000000 --- a/backend/lambda-functions/runtime-provisioner/tests/test_modify.py +++ /dev/null @@ -1,370 +0,0 @@ -"""Tests for handle_modify (MODIFY/update runtime flow).""" - -import os -import sys - -import pytest -from botocore.exceptions import ClientError - -_tests_dir = os.path.dirname(__file__) -if _tests_dir not in sys.path: - sys.path.insert(0, _tests_dir) - -from conftest import make_modify_event, AUTH_PROVIDERS_TABLE - - -# --------------------------------------------------------------------------- -# Helpers -# --------------------------------------------------------------------------- - -def _seed_provider(mod, pid, runtime_id="test-runtime-id"): - """Insert a provider record so DynamoDB status updates succeed.""" - mod.dynamodb.put_item( - TableName=AUTH_PROVIDERS_TABLE, - Item={ - "PK": {"S": f"AUTH_PROVIDER#{pid}"}, - "SK": {"S": f"AUTH_PROVIDER#{pid}"}, - "providerId": {"S": pid}, - "agentcoreRuntimeId": {"S": runtime_id}, - "agentcoreRuntimeStatus": {"S": "CREATING"}, - }, - ) - - -def _get_provider(mod, pid): - """Read back the provider record from DynamoDB.""" - resp = mod.dynamodb.get_item( - TableName=AUTH_PROVIDERS_TABLE, - Key={ - "PK": {"S": f"AUTH_PROVIDER#{pid}"}, - "SK": {"S": f"AUTH_PROVIDER#{pid}"}, - }, - ) - return resp.get("Item", {}) - - -# --------------------------------------------------------------------------- -# Tests -# --------------------------------------------------------------------------- - - -class TestModifyDetectsChanges: - """Verify that changes to each JWT field trigger an update.""" - - def test_modify_detects_issuer_url_change(self, lambda_module): - mod, bedrock = lambda_module - pid = "prov-issuer" - _seed_provider(mod, pid) - - event = make_modify_event( - provider_id=pid, - old_issuer_url="https://old.example.com", - new_issuer_url="https://new.example.com", - old_client_id="same-client", - new_client_id="same-client", - ) - mod.lambda_handler(event, {}) - - bedrock.update_agent_runtime.assert_called_once() - - def test_modify_detects_client_id_change(self, lambda_module): - mod, bedrock = lambda_module - pid = "prov-client" - _seed_provider(mod, pid) - - event = make_modify_event( - provider_id=pid, - old_issuer_url="https://same.example.com", - new_issuer_url="https://same.example.com", - old_client_id="old-client", - new_client_id="new-client", - ) - mod.lambda_handler(event, {}) - - bedrock.update_agent_runtime.assert_called_once() - - def test_modify_detects_jwks_uri_change(self, lambda_module): - mod, bedrock = lambda_module - pid = "prov-jwks" - _seed_provider(mod, pid) - - event = make_modify_event( - provider_id=pid, - old_issuer_url="https://same.example.com", - new_issuer_url="https://same.example.com", - old_client_id="same-client", - new_client_id="same-client", - old_jwks_uri="https://old.example.com/.well-known/jwks.json", - new_jwks_uri="https://new.example.com/.well-known/jwks.json", - ) - mod.lambda_handler(event, {}) - - bedrock.update_agent_runtime.assert_called_once() - - -class TestModifyNoOp: - """No bedrock call when JWT fields are unchanged.""" - - def test_modify_noop_when_jwt_unchanged(self, lambda_module): - mod, bedrock = lambda_module - - event = make_modify_event( - provider_id="prov-noop", - old_issuer_url="https://same.example.com", - new_issuer_url="https://same.example.com", - old_client_id="same-client", - new_client_id="same-client", - ) - mod.lambda_handler(event, {}) - - bedrock.update_agent_runtime.assert_not_called() - - -class TestModifyUpdateDetails: - """Validate what gets sent to bedrock on update.""" - - def test_modify_updates_authorizer_config(self, lambda_module): - mod, bedrock = lambda_module - pid = "prov-auth" - _seed_provider(mod, pid) - - event = make_modify_event( - provider_id=pid, - old_issuer_url="https://old.example.com", - new_issuer_url="https://new.example.com", - old_client_id="old-client", - new_client_id="new-client", - ) - mod.lambda_handler(event, {}) - - call_kwargs = bedrock.update_agent_runtime.call_args[1] - auth_cfg = call_kwargs["authorizerConfiguration"]["customJWTAuthorizer"] - - assert "new.example.com" in auth_cfg["discoveryUrl"] - assert auth_cfg["allowedAudience"] == ["new-client"] - - def test_modify_preserves_existing_config(self, lambda_module): - mod, bedrock = lambda_module - pid = "prov-preserve" - _seed_provider(mod, pid) - - event = make_modify_event( - provider_id=pid, - old_issuer_url="https://old.example.com", - new_issuer_url="https://new.example.com", - old_client_id="old-client", - new_client_id="new-client", - ) - mod.lambda_handler(event, {}) - - call_kwargs = bedrock.update_agent_runtime.call_args[1] - - # Container artifact preserved from get_agent_runtime mock - assert call_kwargs["agentRuntimeArtifact"] == { - "containerConfiguration": { - "containerUri": "123456789012.dkr.ecr.us-east-1.amazonaws.com/test-repo:latest", - } - } - # Network config preserved - assert call_kwargs["networkConfiguration"] == {"networkMode": "PUBLIC"} - # Role ARN preserved - assert call_kwargs["roleArn"] == "arn:aws:iam::123456789012:role/test-runtime-role" - - -class TestModifyDynamoDBStatus: - """DynamoDB status updates after modify.""" - - def test_modify_updates_dynamodb_status_ready(self, lambda_module): - mod, bedrock = lambda_module - pid = "prov-ready" - _seed_provider(mod, pid) - - event = make_modify_event( - provider_id=pid, - old_issuer_url="https://old.example.com", - new_issuer_url="https://new.example.com", - old_client_id="same-client", - new_client_id="same-client", - ) - mod.lambda_handler(event, {}) - - item = _get_provider(mod, pid) - assert item["agentcoreRuntimeStatus"]["S"] == "READY" - - -class TestModifyEdgeCases: - """Edge cases: missing runtime ID, bedrock failure.""" - - def test_modify_missing_runtime_id_skips(self, lambda_module): - mod, bedrock = lambda_module - - # Build event without agentcoreRuntimeId in NewImage - event = make_modify_event( - provider_id="prov-noid", - old_issuer_url="https://old.example.com", - new_issuer_url="https://new.example.com", - old_client_id="same-client", - new_client_id="same-client", - runtime_id="", # will produce empty string - ) - # Remove the runtime id key entirely from NewImage - del event["Records"][0]["dynamodb"]["NewImage"]["agentcoreRuntimeId"] - del event["Records"][0]["dynamodb"]["OldImage"]["agentcoreRuntimeId"] - - mod.lambda_handler(event, {}) - - bedrock.update_agent_runtime.assert_not_called() - - def test_modify_failure_sets_update_failed(self, lambda_module): - mod, bedrock = lambda_module - pid = "prov-fail" - _seed_provider(mod, pid) - - bedrock.update_agent_runtime.side_effect = ClientError( - {"Error": {"Code": "ValidationException", "Message": "bad config"}}, - "UpdateAgentRuntime", - ) - - event = make_modify_event( - provider_id=pid, - old_issuer_url="https://old.example.com", - new_issuer_url="https://new.example.com", - old_client_id="same-client", - new_client_id="same-client", - ) - mod.lambda_handler(event, {}) - - item = _get_provider(mod, pid) - assert item["agentcoreRuntimeStatus"]["S"] == "UPDATE_FAILED" - assert "agentcoreRuntimeError" in item - - -class TestModifyRefreshesEnvironmentVariables: - """Environment variables must be refreshed from SSM on every update.""" - - def test_modify_refreshes_env_vars_from_ssm(self, lambda_module): - """Even if the runtime has stale env vars, update should fetch - fresh values from SSM Parameter Store.""" - mod, bedrock = lambda_module - pid = "prov-envvars" - _seed_provider(mod, pid) - - event = make_modify_event( - provider_id=pid, - old_issuer_url="https://old.example.com", - new_issuer_url="https://new.example.com", - old_client_id="same-client", - new_client_id="same-client", - ) - mod.lambda_handler(event, {}) - - call_kwargs = bedrock.update_agent_runtime.call_args[1] - env_vars = call_kwargs["environmentVariables"] - # Env vars should come from SSM, not from the runtime's existing values - assert "DYNAMODB_USERS_TABLE_NAME" in env_vars - assert env_vars["DYNAMODB_USERS_TABLE_NAME"] == "test-users-table" - assert env_vars["PROVIDER_ID"] == pid - assert env_vars["PROJECT_NAME"] == "test-project" - - def test_modify_refreshes_env_vars_even_when_runtime_has_none(self, lambda_module): - """If the runtime has no env vars, update should still fetch - fresh values from SSM and include them.""" - mod, bedrock = lambda_module - pid = "prov-noenv" - _seed_provider(mod, pid) - - # Override mock to return a runtime with no env vars - runtime_resp = bedrock.get_agent_runtime.return_value.copy() - del runtime_resp["environmentVariables"] - bedrock.get_agent_runtime.return_value = runtime_resp - - event = make_modify_event( - provider_id=pid, - old_issuer_url="https://old.example.com", - new_issuer_url="https://new.example.com", - old_client_id="same-client", - new_client_id="same-client", - ) - mod.lambda_handler(event, {}) - - call_kwargs = bedrock.update_agent_runtime.call_args[1] - # Should still have env vars from SSM - assert "environmentVariables" in call_kwargs - env_vars = call_kwargs["environmentVariables"] - assert "DYNAMODB_USERS_TABLE_NAME" in env_vars - - -class TestModifyAlwaysIncludesAuthorizationHeader: - """Authorization header must always be in the allowlist.""" - - def test_modify_always_includes_authorization(self, lambda_module): - mod, bedrock = lambda_module - pid = "prov-auth-hdr" - _seed_provider(mod, pid) - - event = make_modify_event( - provider_id=pid, - old_issuer_url="https://old.example.com", - new_issuer_url="https://new.example.com", - old_client_id="same-client", - new_client_id="same-client", - ) - mod.lambda_handler(event, {}) - - call_kwargs = bedrock.update_agent_runtime.call_args[1] - allowlist = call_kwargs["requestHeaderConfiguration"]["requestHeaderAllowlist"] - assert "Authorization" in allowlist - - def test_modify_includes_authorization_even_when_field_missing(self, lambda_module): - """If get_agent_runtime omits requestHeaderConfiguration entirely, - Authorization must still be set.""" - mod, bedrock = lambda_module - pid = "prov-no-hdr" - _seed_provider(mod, pid) - - # Override mock to return a runtime with no header config - runtime_resp = bedrock.get_agent_runtime.return_value.copy() - del runtime_resp["requestHeaderConfiguration"] - bedrock.get_agent_runtime.return_value = runtime_resp - - event = make_modify_event( - provider_id=pid, - old_issuer_url="https://old.example.com", - new_issuer_url="https://new.example.com", - old_client_id="same-client", - new_client_id="same-client", - ) - mod.lambda_handler(event, {}) - - call_kwargs = bedrock.update_agent_runtime.call_args[1] - allowlist = call_kwargs["requestHeaderConfiguration"]["requestHeaderAllowlist"] - assert "Authorization" in allowlist - - def test_modify_preserves_custom_headers(self, lambda_module): - mod, bedrock = lambda_module - pid = "prov-custom-hdr" - _seed_provider(mod, pid) - - # Override mock to include a custom header alongside Authorization - runtime_resp = bedrock.get_agent_runtime.return_value.copy() - runtime_resp["requestHeaderConfiguration"] = { - "requestHeaderAllowlist": [ - "Authorization", - "X-Amzn-Bedrock-AgentCore-Runtime-Custom-Trace-Id", - ] - } - bedrock.get_agent_runtime.return_value = runtime_resp - - event = make_modify_event( - provider_id=pid, - old_issuer_url="https://old.example.com", - new_issuer_url="https://new.example.com", - old_client_id="same-client", - new_client_id="same-client", - ) - mod.lambda_handler(event, {}) - - call_kwargs = bedrock.update_agent_runtime.call_args[1] - allowlist = call_kwargs["requestHeaderConfiguration"]["requestHeaderAllowlist"] - assert "Authorization" in allowlist - assert "X-Amzn-Bedrock-AgentCore-Runtime-Custom-Trace-Id" in allowlist diff --git a/backend/lambda-functions/runtime-provisioner/tests/test_remove.py b/backend/lambda-functions/runtime-provisioner/tests/test_remove.py deleted file mode 100644 index 41a10329..00000000 --- a/backend/lambda-functions/runtime-provisioner/tests/test_remove.py +++ /dev/null @@ -1,103 +0,0 @@ -"""Tests for handle_remove (REMOVE/delete runtime flow).""" - -import os -import sys - -import pytest -from botocore.exceptions import ClientError - -_tests_dir = os.path.dirname(__file__) -if _tests_dir not in sys.path: - sys.path.insert(0, _tests_dir) - -from conftest import make_remove_event, PROJECT_PREFIX - - -# --------------------------------------------------------------------------- -# Tests -# --------------------------------------------------------------------------- - - -class TestRemoveDeletesRuntime: - """Verify runtime deletion via bedrock.""" - - def test_remove_deletes_runtime(self, lambda_module): - mod, bedrock = lambda_module - - event = make_remove_event(provider_id="prov1", runtime_id="rt-abc") - mod.lambda_handler(event, {}) - - bedrock.delete_agent_runtime.assert_called_once_with(agentRuntimeId="rt-abc") - - -class TestRemoveSSM: - """SSM parameter cleanup on remove.""" - - def test_remove_deletes_ssm_parameter(self, lambda_module): - mod, bedrock = lambda_module - pid = "prov-ssm" - param_name = f"/{PROJECT_PREFIX}/runtimes/{pid}/arn" - - # Pre-create the SSM parameter - mod.ssm.put_parameter( - Name=param_name, - Value="arn:aws:bedrock:us-east-1:123456789012:agent-runtime/rt-xyz", - Type="String", - ) - - event = make_remove_event(provider_id=pid, runtime_id="rt-xyz") - mod.lambda_handler(event, {}) - - # Parameter should be gone - with pytest.raises(ClientError) as exc_info: - mod.ssm.get_parameter(Name=param_name) - assert exc_info.value.response["Error"]["Code"] == "ParameterNotFound" - - def test_remove_ssm_parameter_not_found_ok(self, lambda_module): - """SSM ParameterNotFound during cleanup does not crash.""" - mod, bedrock = lambda_module - pid = "prov-ssm-missing" - - # Do NOT create the SSM parameter — it shouldn't exist - event = make_remove_event(provider_id=pid, runtime_id="rt-missing") - # Should not raise - mod.lambda_handler(event, {}) - - -class TestRemoveGracefulErrors: - """Error handling in remove path.""" - - def test_remove_handles_resource_not_found(self, lambda_module): - """ResourceNotFoundException from delete_agent_runtime → no crash.""" - mod, bedrock = lambda_module - - bedrock.delete_agent_runtime.side_effect = ClientError( - {"Error": {"Code": "ResourceNotFoundException", "Message": "Not found"}}, - "DeleteAgentRuntime", - ) - - event = make_remove_event(provider_id="prov-gone", runtime_id="rt-gone") - # Should not raise - mod.lambda_handler(event, {}) - - def test_remove_missing_runtime_id_skips(self, lambda_module): - """No agentcoreRuntimeId → no delete attempt.""" - mod, bedrock = lambda_module - - event = make_remove_event(provider_id="prov-noid") # runtime_id=None - mod.lambda_handler(event, {}) - - bedrock.delete_agent_runtime.assert_not_called() - - def test_remove_does_not_reraise(self, lambda_module): - """Any error in handle_remove is caught (doesn't propagate).""" - mod, bedrock = lambda_module - - bedrock.delete_agent_runtime.side_effect = ClientError( - {"Error": {"Code": "InternalServerError", "Message": "boom"}}, - "DeleteAgentRuntime", - ) - - event = make_remove_event(provider_id="prov-err", runtime_id="rt-err") - # Should NOT raise despite InternalServerError - mod.lambda_handler(event, {}) diff --git a/backend/lambda-functions/runtime-provisioner/tests/test_runtime_name.py b/backend/lambda-functions/runtime-provisioner/tests/test_runtime_name.py deleted file mode 100644 index 070c8093..00000000 --- a/backend/lambda-functions/runtime-provisioner/tests/test_runtime_name.py +++ /dev/null @@ -1,65 +0,0 @@ -"""Tests for runtime name generation edge cases.""" -import sys -import os - -_tests_dir = os.path.dirname(__file__) -if _tests_dir not in sys.path: - sys.path.insert(0, _tests_dir) -from conftest import make_insert_event, PROJECT_PREFIX - - -class TestRuntimeNameGeneration: - - def _get_runtime_name(self, mod, bedrock, provider_id): - """Fire an INSERT event and return the agentRuntimeName passed to bedrock.""" - event = make_insert_event( - provider_id=provider_id, - issuer_url='https://auth.example.com', - client_id='client1', - ) - mod.lambda_handler(event, {}) - call_kwargs = bedrock.create_agent_runtime.call_args[1] - return call_kwargs['agentRuntimeName'] - - def test_name_simple(self, lambda_module): - mod, bedrock = lambda_module - name = self._get_runtime_name(mod, bedrock, 'prov1') - assert name == 'test_project_runtime_prov1' - - def test_name_hyphens_replaced(self, lambda_module): - mod, bedrock = lambda_module - name = self._get_runtime_name(mod, bedrock, 'my-provider') - assert name == 'test_project_runtime_my_provider' - - def test_name_exactly_48_chars(self, lambda_module): - mod, bedrock = lambda_module - # "test_project_runtime_" is 21 chars, so we need 27 more - provider_id = 'a' * 27 - name = self._get_runtime_name(mod, bedrock, provider_id) - assert len(name) == 48 - assert name == f'test_project_runtime_{provider_id}' - - def test_name_over_48_chars(self, lambda_module): - mod, bedrock = lambda_module - provider_id = 'a' * 40 - name = self._get_runtime_name(mod, bedrock, provider_id) - assert len(name) <= 48 - assert name.startswith('r_') - - def test_name_truncated_format(self, lambda_module): - mod, bedrock = lambda_module - provider_id = 'very-long-provider-id-that-exceeds-the-maximum-allowed-length' - name = self._get_runtime_name(mod, bedrock, provider_id) - assert name.startswith('r_') - assert len(name) <= 48 - - def test_name_all_hyphens_converted(self, lambda_module): - mod, bedrock = lambda_module - name = self._get_runtime_name(mod, bedrock, 'a-b-c') - assert '-' not in name - assert name == 'test_project_runtime_a_b_c' - - def test_name_short_provider(self, lambda_module): - mod, bedrock = lambda_module - name = self._get_runtime_name(mod, bedrock, 'x') - assert name == 'test_project_runtime_x' diff --git a/backend/lambda-functions/runtime-updater/README.md b/backend/lambda-functions/runtime-updater/README.md deleted file mode 100644 index fbdfeeac..00000000 --- a/backend/lambda-functions/runtime-updater/README.md +++ /dev/null @@ -1,198 +0,0 @@ -# Runtime Updater Lambda - -Automatically updates all AgentCore provider runtimes when new container images are deployed. - -## Overview - -This Lambda function is triggered by EventBridge when the SSM parameter for the inference API image tag changes. It queries all providers with existing runtimes and updates them in parallel with the new container image. - -## Trigger - -- **EventBridge Rule**: Detects changes to `/${PROJECT_PREFIX}/inference-api/image-tag` SSM parameter -- **Event Type**: SSM Parameter Store change notification - -## Functionality - -### Core Features - -1. **Parallel Updates**: Updates up to 5 runtimes concurrently to minimize total update time -2. **Retry Logic**: Retries failed updates up to 3 times with exponential backoff (2s, 4s, 8s) -3. **Status Tracking**: Updates DynamoDB with runtime status (UPDATING, READY, UPDATE_FAILED) -4. **SNS Notifications**: Sends summary notifications with success/failure counts -5. **Error Isolation**: Individual runtime failures don't affect other updates - -### Update Process - -1. Extract new image tag from EventBridge event -2. Query DynamoDB for all providers with existing runtimes -3. Fetch new container image URI from ECR -4. Update runtimes in parallel (max 5 concurrent): - - Fetch current runtime configuration via `GetAgentRuntime` - - Call `UpdateAgentRuntime` with new container image - - Preserve all other configuration (JWT auth, network, environment) - - Retry up to 3 times with exponential backoff -5. Update DynamoDB status for each provider -6. Send SNS notification summary - -## Environment Variables - -- `PROJECT_PREFIX`: Project prefix for resource naming -- `AWS_REGION`: AWS region -- `AUTH_PROVIDERS_TABLE`: DynamoDB table name for auth providers -- `SNS_TOPIC_ARN`: SNS topic ARN for alerts - -## IAM Permissions Required - -- `bedrock-agentcore:GetAgentRuntime` -- `bedrock-agentcore:UpdateAgentRuntime` -- `dynamodb:Scan` (Auth Providers table) -- `dynamodb:UpdateItem` (Auth Providers table) -- `ssm:GetParameter` (image tag and ECR repository URI) -- `ecr:DescribeRepositories` -- `ecr:DescribeImages` -- `sns:Publish` (for alerts) - -## Configuration - -- **Max Concurrent Updates**: 5 runtimes at a time -- **Max Retry Attempts**: 3 attempts per runtime -- **Retry Backoff**: Exponential (2s, 4s, 8s) -- **Timeout**: 15 minutes (for parallel updates) -- **Memory**: 512 MB - -## Error Handling - -### Retryable Errors -- `ThrottlingException`: API rate limiting -- `ServiceUnavailableException`: Temporary service issues - -### Non-Retryable Errors -- `ResourceNotFoundException`: Runtime not found (deleted externally) -- `ValidationException`: Invalid runtime configuration -- Other client errors - -### Error Recovery -- Failed updates are marked in DynamoDB with `UPDATE_FAILED` status -- Error messages stored in `agentcoreRuntimeError` field -- SNS alerts sent for all failures -- Admin can retry manually via UI or wait for next image deployment - -## SNS Notifications - -### Update Summary -Sent after all updates complete: -``` -Runtime Update Summary -====================== - -New Image Tag: v1.2.3 -Total Runtimes: 5 -Succeeded: 4 -Failed: 1 - -Failed Updates: --------------------------------------------------- -Provider: Okta Production (okta-prod) -Error: ThrottlingException: Rate exceeded -Attempts: 3 -``` - -### Critical Failure -Sent if Lambda encounters unrecoverable error: -``` -Critical Failure in Runtime Updater Lambda - -The Runtime Updater Lambda encountered a critical error and could not complete. - -Error: [error message] - -Action Required: Investigate Lambda logs and retry manually if needed. -``` - -## Monitoring - -### CloudWatch Logs -- All update attempts logged with provider ID and attempt number -- Success/failure status for each runtime -- Detailed error messages for failures - -### CloudWatch Metrics -Custom metrics published to `AgentCore/RuntimeUpdates` namespace: -- `UpdateSuccess`: Count of successful updates -- `UpdateFailure`: Count of failed updates -- `UpdateDuration`: Time taken to update all runtimes -- `RuntimeCount`: Total number of active runtimes - -### CloudWatch Alarms -- **Runtime Update Failures**: Triggers when `UpdateFailure > 0` -- **High Update Duration**: Triggers when `UpdateDuration > 30 minutes` - -## Testing - -### Local Testing -```bash -# Set environment variables -export PROJECT_PREFIX=bsu -export AWS_REGION=us-east-1 -export AUTH_PROVIDERS_TABLE=bsu-auth-providers -export SNS_TOPIC_ARN=arn:aws:sns:us-east-1:123456789012:runtime-update-alerts - -# Create test event -cat > test-event.json < Optional[str]: - """ - Extract image tag from EventBridge event - - Args: - event: EventBridge event from SSM parameter change - - Returns: - New image tag or None if not found - """ - try: - # EventBridge event structure for SSM parameter changes - detail = event.get('detail', {}) - - # Get parameter name from event - param_name = detail.get('name', '') - - # Verify this is the image tag parameter - expected_param = f"/{PROJECT_PREFIX}/inference-api/image-tag" - - if param_name == expected_param: - # SSM Parameter Store Change events don't include the value, - # so we always need to fetch it from SSM - return get_image_tag_from_ssm() - - logger.warning(f"Event parameter name mismatch: {param_name} != {expected_param}") - return None - - except Exception as e: - logger.error(f"Error extracting image tag: {e}") - return None - - -def get_image_tag_from_ssm() -> str: - """Fetch current image tag from SSM""" - param_name = f"/{PROJECT_PREFIX}/inference-api/image-tag" - - try: - response = ssm.get_parameter(Name=param_name) - return response['Parameter']['Value'] - except ClientError as e: - logger.error(f"Failed to get image tag from SSM: {e}") - raise ValueError(f"Image tag not found in SSM: {param_name}") - - -def get_container_image_uri(image_tag: str) -> str: - """ - Get full container image URI from ECR - - Args: - image_tag: Image tag (e.g., 'latest', 'v1.0.0') - - Returns: - Full ECR image URI - """ - # Get ECR repository URI from SSM - repo_param = f"/{PROJECT_PREFIX}/inference-api/ecr-repository-uri" - - try: - response = ssm.get_parameter(Name=repo_param) - repo_uri = response['Parameter']['Value'] - return f"{repo_uri}:{image_tag}" - except ClientError as e: - logger.error(f"Failed to get ECR repository URI: {e}") - raise ValueError(f"ECR repository URI not found in SSM: {repo_param}") - - -def get_providers_with_runtimes() -> List[Dict[str, Any]]: - """ - Query DynamoDB for all providers with existing runtimes - - Returns: - List of provider records with runtime information - """ - providers = [] - - try: - # Scan table for all providers - response = dynamodb.scan( - TableName=AUTH_PROVIDERS_TABLE, - FilterExpression='attribute_exists(agentcoreRuntimeId) AND agentcoreRuntimeStatus <> :failed', - ExpressionAttributeValues={ - ':failed': {'S': 'FAILED'} - } - ) - - for item in response.get('Items', []): - provider = { - 'provider_id': deserialize_dynamodb_value(item['providerId']), - 'runtime_id': deserialize_dynamodb_value(item.get('agentcoreRuntimeId', {})), - 'runtime_arn': deserialize_dynamodb_value(item.get('agentcoreRuntimeArn', {})), - 'display_name': deserialize_dynamodb_value(item.get('displayName', {})) - } - - if provider['runtime_id']: - providers.append(provider) - - # Handle pagination - while 'LastEvaluatedKey' in response: - response = dynamodb.scan( - TableName=AUTH_PROVIDERS_TABLE, - FilterExpression='attribute_exists(agentcoreRuntimeId) AND agentcoreRuntimeStatus <> :failed', - ExpressionAttributeValues={ - ':failed': {'S': 'FAILED'} - }, - ExclusiveStartKey=response['LastEvaluatedKey'] - ) - - for item in response.get('Items', []): - provider = { - 'provider_id': deserialize_dynamodb_value(item['providerId']), - 'runtime_id': deserialize_dynamodb_value(item.get('agentcoreRuntimeId', {})), - 'runtime_arn': deserialize_dynamodb_value(item.get('agentcoreRuntimeArn', {})), - 'display_name': deserialize_dynamodb_value(item.get('displayName', {})) - } - - if provider['runtime_id']: - providers.append(provider) - - return providers - - except ClientError as e: - logger.error(f"Failed to query providers: {e}") - raise - - -def update_runtimes_parallel( - providers: List[Dict[str, Any]], - new_image_uri: str -) -> List[Dict[str, Any]]: - """ - Update runtimes in parallel with max concurrency limit - - Args: - providers: List of provider records - new_image_uri: New container image URI - - Returns: - List of update results - """ - results = [] - - # Use ThreadPoolExecutor for parallel updates - with ThreadPoolExecutor(max_workers=MAX_CONCURRENT_UPDATES) as executor: - # Submit all update tasks - future_to_provider = { - executor.submit(update_runtime_with_retry, provider, new_image_uri): provider - for provider in providers - } - - # Collect results as they complete - for future in as_completed(future_to_provider): - provider = future_to_provider[future] - - try: - result = future.result() - results.append(result) - except Exception as e: - logger.error(f"Unexpected error updating {provider['provider_id']}: {e}") - results.append({ - 'provider_id': provider['provider_id'], - 'display_name': provider.get('display_name', 'Unknown'), - 'success': False, - 'error': str(e), - 'attempts': 0 - }) - - return results - - -def update_runtime_with_retry( - provider: Dict[str, Any], - new_image_uri: str -) -> Dict[str, Any]: - """ - Update runtime with retry logic and exponential backoff - - Args: - provider: Provider record with runtime information - new_image_uri: New container image URI - - Returns: - Update result dictionary - """ - provider_id = provider['provider_id'] - runtime_id = provider['runtime_id'] - display_name = provider.get('display_name', 'Unknown') - - logger.info(f"Updating runtime for provider: {provider_id}") - - # Update DynamoDB status to UPDATING - update_provider_status(provider_id, 'UPDATING') - - # Retry loop - for attempt in range(1, MAX_RETRY_ATTEMPTS + 1): - try: - logger.info(f"Attempt {attempt}/{MAX_RETRY_ATTEMPTS} for {provider_id}") - - # Fetch current runtime configuration - current_runtime = bedrock_agentcore.get_agent_runtime( - agentRuntimeId=runtime_id - ) - - # Update runtime with new container image - update_runtime(runtime_id, current_runtime, new_image_uri, provider_id) - - # Update DynamoDB status to READY - update_provider_status(provider_id, 'READY') - - logger.info(f"✅ Successfully updated runtime for {provider_id}") - - return { - 'provider_id': provider_id, - 'display_name': display_name, - 'success': True, - 'attempts': attempt - } - - except ClientError as e: - error_code = e.response['Error']['Code'] - error_msg = e.response['Error']['Message'] - - logger.warning( - f"Attempt {attempt} failed for {provider_id}: {error_code} - {error_msg}" - ) - - # Check if this is a retryable error - if error_code in ['ThrottlingException', 'ServiceUnavailableException']: - if attempt < MAX_RETRY_ATTEMPTS: - # Exponential backoff - sleep_time = RETRY_BACKOFF_BASE ** attempt - logger.info(f"Retrying in {sleep_time} seconds...") - time.sleep(sleep_time) - continue - - # Non-retryable error or max attempts reached - logger.error(f"❌ Failed to update runtime for {provider_id}: {error_msg}") - - # Update DynamoDB with error status - update_provider_error(provider_id, error_msg) - - return { - 'provider_id': provider_id, - 'display_name': display_name, - 'success': False, - 'error': error_msg, - 'attempts': attempt - } - - except Exception as e: - logger.error(f"Unexpected error for {provider_id}: {str(e)}", exc_info=True) - - if attempt < MAX_RETRY_ATTEMPTS: - sleep_time = RETRY_BACKOFF_BASE ** attempt - logger.info(f"Retrying in {sleep_time} seconds...") - time.sleep(sleep_time) - continue - - # Max attempts reached - update_provider_error(provider_id, str(e)) - - return { - 'provider_id': provider_id, - 'display_name': display_name, - 'success': False, - 'error': str(e), - 'attempts': attempt - } - - # Should not reach here, but handle it - error_msg = f"Failed after {MAX_RETRY_ATTEMPTS} attempts" - update_provider_error(provider_id, error_msg) - - return { - 'provider_id': provider_id, - 'display_name': display_name, - 'success': False, - 'error': error_msg, - 'attempts': MAX_RETRY_ATTEMPTS - } - - -def get_fresh_environment_variables(provider_id: str, current_runtime: Dict[str, Any]) -> Dict[str, str]: - """ - Re-fetch environment variables from SSM Parameter Store. - - This ensures that renamed tables, new parameters, or changed values - are picked up on every deploy — not carried forward stale from the - original create_runtime call. - - Non-SSM env vars (PROVIDER_ID, LOG_LEVEL, etc.) are reconstructed - from the current runtime's existing values and known defaults. - - Args: - provider_id: Provider ID for this runtime - current_runtime: Current runtime config (used for non-SSM values) - - Returns: - Complete dict of environment variables for the runtime - """ - existing_env = current_runtime.get('environmentVariables', {}) - - # Define SSM parameters to fetch (mirrors runtime-provisioner) - ssm_param_map = { - # DynamoDB tables - 'DYNAMODB_USERS_TABLE_NAME': f"/{PROJECT_PREFIX}/users/users-table-name", - 'DYNAMODB_APP_ROLES_TABLE_NAME': f"/{PROJECT_PREFIX}/rbac/app-roles-table-name", - 'DYNAMODB_OIDC_STATE_TABLE_NAME': f"/{PROJECT_PREFIX}/auth/oidc-state-table-name", - 'DYNAMODB_API_KEYS_TABLE_NAME': f"/{PROJECT_PREFIX}/auth/api-keys-table-name", - 'DYNAMODB_OAUTH_PROVIDERS_TABLE_NAME': f"/{PROJECT_PREFIX}/oauth/providers-table-name", - 'DYNAMODB_OAUTH_USER_TOKENS_TABLE_NAME': f"/{PROJECT_PREFIX}/oauth/user-tokens-table-name", - 'DYNAMODB_ASSISTANTS_TABLE_NAME': f"/{PROJECT_PREFIX}/rag/assistants-table-name", - # Quota & cost tracking - 'DYNAMODB_QUOTA_TABLE': f"/{PROJECT_PREFIX}/quota/user-quotas-table-name", - 'DYNAMODB_QUOTA_EVENTS_TABLE': f"/{PROJECT_PREFIX}/quota/quota-events-table-name", - 'DYNAMODB_SESSIONS_METADATA_TABLE_NAME': f"/{PROJECT_PREFIX}/cost-tracking/sessions-metadata-table-name", - 'DYNAMODB_COST_SUMMARY_TABLE_NAME': f"/{PROJECT_PREFIX}/cost-tracking/user-cost-summary-table-name", - 'DYNAMODB_SYSTEM_ROLLUP_TABLE_NAME': f"/{PROJECT_PREFIX}/cost-tracking/system-cost-rollup-table-name", - 'DYNAMODB_MANAGED_MODELS_TABLE_NAME': f"/{PROJECT_PREFIX}/admin/managed-models-table-name", - 'DYNAMODB_USER_FILES_TABLE_NAME': f"/{PROJECT_PREFIX}/user-file-uploads/table-name", - # Auth secrets - 'AUTH_PROVIDER_SECRETS_ARN': f"/{PROJECT_PREFIX}/auth/auth-provider-secrets-arn", - # OAuth - 'OAUTH_TOKEN_ENCRYPTION_KEY_ARN': f"/{PROJECT_PREFIX}/oauth/token-encryption-key-arn", - 'OAUTH_CLIENT_SECRETS_ARN': f"/{PROJECT_PREFIX}/oauth/client-secrets-arn", - 'OAUTH_CALLBACK_URL': f"/{PROJECT_PREFIX}/oauth/callback-url", - # S3 / RAG - 'S3_ASSISTANTS_VECTOR_STORE_BUCKET_NAME': f"/{PROJECT_PREFIX}/rag/vector-bucket-name", - 'S3_ASSISTANTS_VECTOR_STORE_INDEX_NAME': f"/{PROJECT_PREFIX}/rag/vector-index-name", - # URLs - 'API_URL': f"/{PROJECT_PREFIX}/network/alb-url", - 'FRONTEND_URL': f"/{PROJECT_PREFIX}/frontend/url", - 'CORS_ORIGINS': f"/{PROJECT_PREFIX}/frontend/cors-origins", - # Shared AgentCore resources - 'MEMORY_ARN': f"/{PROJECT_PREFIX}/inference-api/memory-arn", - 'MEMORY_ID': f"/{PROJECT_PREFIX}/inference-api/memory-id", - 'AGENTCORE_MEMORY_ID': f"/{PROJECT_PREFIX}/inference-api/memory-id", - 'CODE_INTERPRETER_ID': f"/{PROJECT_PREFIX}/inference-api/code-interpreter-id", - 'BROWSER_ID': f"/{PROJECT_PREFIX}/inference-api/browser-id", - 'GATEWAY_URL': f"/{PROJECT_PREFIX}/gateway/gateway-url", - } - - # Batch-fetch SSM parameters (GetParameters supports up to 10 at a time) - param_names = list(ssm_param_map.values()) - fetched_params = {} - - for i in range(0, len(param_names), 10): - batch = param_names[i:i + 10] - try: - response = ssm.get_parameters(Names=batch) - for param in response.get('Parameters', []): - fetched_params[param['Name']] = param['Value'] - invalid = response.get('InvalidParameters', []) - if invalid: - logger.warning(f"SSM parameters not found: {invalid}") - except ClientError as e: - logger.error(f"Failed to fetch SSM parameter batch: {e}") - raise - - # Build fresh env vars from SSM values - env_vars = {} - for env_key, ssm_name in ssm_param_map.items(): - if ssm_name in fetched_params: - env_vars[env_key] = fetched_params[ssm_name] - elif env_key in existing_env: - # Fall back to existing value if SSM param not found - logger.warning(f"SSM param {ssm_name} not found, keeping existing value for {env_key}") - env_vars[env_key] = existing_env[env_key] - - # Set non-SSM env vars (static config / derived values) - env_vars['LOG_LEVEL'] = existing_env.get('LOG_LEVEL', 'INFO') - env_vars['PROJECT_NAME'] = PROJECT_PREFIX - env_vars['AWS_REGION'] = AWS_REGION - env_vars['AWS_DEFAULT_REGION'] = AWS_REGION - env_vars['PROVIDER_ID'] = provider_id - env_vars['DYNAMODB_AUTH_PROVIDERS_TABLE_NAME'] = AUTH_PROVIDERS_TABLE - env_vars['AGENTCORE_MEMORY_TYPE'] = existing_env.get('AGENTCORE_MEMORY_TYPE', 'dynamodb') - env_vars['ENABLE_AUTHENTICATION'] = existing_env.get('ENABLE_AUTHENTICATION', 'true') - env_vars['UPLOAD_DIR'] = existing_env.get('UPLOAD_DIR', '/tmp/uploads') - env_vars['OUTPUT_DIR'] = existing_env.get('OUTPUT_DIR', '/tmp/output') - env_vars['GENERATED_IMAGES_DIR'] = existing_env.get('GENERATED_IMAGES_DIR', '/tmp/generated_images') - - # Preserve any extra env vars that aren't in our known set - # (e.g., custom vars added manually or by future features) - known_keys = set(env_vars.keys()) - for key, value in existing_env.items(): - if key not in known_keys: - env_vars[key] = value - - return env_vars - - -def update_runtime( - runtime_id: str, - current_runtime: Dict[str, Any], - new_image_uri: str, - provider_id: str -) -> None: - """ - Update AgentCore Runtime with new container image - - Args: - runtime_id: Runtime ID to update - current_runtime: Current runtime configuration from GetAgentRuntime - new_image_uri: New container image URI - provider_id: Provider ID for environment variable construction - """ - logger.info(f"Updating runtime {runtime_id} with image {new_image_uri}") - - # Preserve all current configuration except container image - update_params = { - 'agentRuntimeId': runtime_id, - 'agentRuntimeArtifact': { - 'containerConfiguration': { - 'containerUri': new_image_uri - } - }, - 'roleArn': current_runtime['roleArn'], - 'networkConfiguration': current_runtime['networkConfiguration'] - } - - # Preserve authorizer configuration if present - if 'authorizerConfiguration' in current_runtime: - update_params['authorizerConfiguration'] = current_runtime['authorizerConfiguration'] - - # ALWAYS set requestHeaderConfiguration with Authorization in the allowlist. - # The previous approach of conditionally preserving the existing config was - # fragile — if the GetAgentRuntime response ever omitted the field (API quirk, - # race condition, eventual consistency), the Authorization header would silently - # stop being forwarded, causing 401s on every request. - # We now build the allowlist from scratch, merging in any existing custom headers. - existing_headers = set() - if 'requestHeaderConfiguration' in current_runtime: - existing_headers = set( - current_runtime['requestHeaderConfiguration'].get('requestHeaderAllowlist', []) - ) - # Authorization MUST always be present — this is non-negotiable - existing_headers.add('Authorization') - update_params['requestHeaderConfiguration'] = { - 'requestHeaderAllowlist': sorted(existing_headers) - } - - # Re-fetch environment variables from SSM to pick up any changes - # (e.g., renamed tables, new parameters added since runtime creation). - # Previously we preserved stale env vars from the existing runtime, - # which caused issues when SSM parameter values changed between deploys. - try: - fresh_env_vars = get_fresh_environment_variables(provider_id, current_runtime) - update_params['environmentVariables'] = fresh_env_vars - logger.info(f"Refreshed {len(fresh_env_vars)} environment variables from SSM") - except Exception as e: - logger.warning( - f"Failed to refresh env vars from SSM: {e}. " - "Falling back to existing runtime env vars." - ) - if 'environmentVariables' in current_runtime: - update_params['environmentVariables'] = current_runtime['environmentVariables'] - - # Call UpdateAgentRuntime API - try: - bedrock_agentcore.update_agent_runtime(**update_params) - except ParamValidationError: - # SDK version doesn't support requestHeaderConfiguration yet — retry without it. - # This is a fallback; the boto3 version should be kept up to date to avoid this path. - logger.warning( - f"SDK does not support requestHeaderConfiguration (boto3 {boto3.__version__}). " - "Retrying without it. UPDATE BOTO3 to preserve Authorization header forwarding." - ) - update_params.pop('requestHeaderConfiguration', None) - bedrock_agentcore.update_agent_runtime(**update_params) - - logger.info(f"Runtime {runtime_id} update initiated") - - -def send_update_summary(results: List[Dict[str, Any]], image_tag: str) -> None: - """ - Send SNS notification with update summary - - Args: - results: List of update results - image_tag: New image tag - """ - success_count = sum(1 for r in results if r['success']) - failure_count = len(results) - success_count - - # Build message - subject = f"AgentCore Runtime Updates: {success_count} succeeded, {failure_count} failed" - - message_lines = [ - f"Runtime Update Summary", - f"======================", - f"", - f"New Image Tag: {image_tag}", - f"Total Runtimes: {len(results)}", - f"Succeeded: {success_count}", - f"Failed: {failure_count}", - f"", - ] - - # Add failure details if any - if failure_count > 0: - message_lines.append("Failed Updates:") - message_lines.append("-" * 50) - - for result in results: - if not result['success']: - message_lines.append( - f"Provider: {result['display_name']} ({result['provider_id']})" - ) - message_lines.append(f"Error: {result.get('error', 'Unknown error')}") - message_lines.append(f"Attempts: {result.get('attempts', 0)}") - message_lines.append("") - - message = "\n".join(message_lines) - - try: - sns.publish( - TopicArn=SNS_TOPIC_ARN, - Subject=subject, - Message=message - ) - logger.info("SNS notification sent") - except ClientError as e: - logger.error(f"Failed to send SNS notification: {e}") - - -def send_critical_failure_alert(error_message: str) -> None: - """ - Send SNS alert for critical Lambda failure - - Args: - error_message: Error message - """ - subject = "CRITICAL: AgentCore Runtime Updater Failed" - - message = f""" -Critical Failure in Runtime Updater Lambda - -The Runtime Updater Lambda encountered a critical error and could not complete. - -Error: {error_message} - -Action Required: Investigate Lambda logs and retry manually if needed. - -Timestamp: {datetime.utcnow().isoformat()}Z -""" - - try: - sns.publish( - TopicArn=SNS_TOPIC_ARN, - Subject=subject, - Message=message - ) - except ClientError as e: - logger.error(f"Failed to send critical failure alert: {e}") - - -# ============================================================================= -# DynamoDB Helper Functions -# ============================================================================= - - -def deserialize_dynamodb_value(value: Dict[str, Any]) -> Any: - """Deserialize DynamoDB attribute value""" - if not value: - return None - - if 'S' in value: - return value['S'] - elif 'N' in value: - return value['N'] - elif 'BOOL' in value: - return value['BOOL'] - elif 'NULL' in value: - return None - elif 'L' in value: - return [deserialize_dynamodb_value(item) for item in value['L']] - elif 'M' in value: - return {k: deserialize_dynamodb_value(v) for k, v in value['M'].items()} - else: - return None - - -def update_provider_status(provider_id: str, status: str) -> None: - """Update provider runtime status in DynamoDB""" - try: - dynamodb.update_item( - TableName=AUTH_PROVIDERS_TABLE, - Key={ - 'PK': {'S': f"AUTH_PROVIDER#{provider_id}"}, - 'SK': {'S': f"AUTH_PROVIDER#{provider_id}"} - }, - UpdateExpression='SET agentcoreRuntimeStatus = :status, updatedAt = :updated', - ExpressionAttributeValues={ - ':status': {'S': status}, - ':updated': {'S': datetime.utcnow().isoformat() + 'Z'} - } - ) - logger.info(f"Updated provider {provider_id} status to {status}") - except ClientError as e: - logger.error(f"Failed to update provider status: {e}") - - -def update_provider_error(provider_id: str, error_message: str) -> None: - """Update provider record with error status and message""" - try: - dynamodb.update_item( - TableName=AUTH_PROVIDERS_TABLE, - Key={ - 'PK': {'S': f"AUTH_PROVIDER#{provider_id}"}, - 'SK': {'S': f"AUTH_PROVIDER#{provider_id}"} - }, - UpdateExpression='SET agentcoreRuntimeStatus = :status, ' - 'agentcoreRuntimeError = :error, updatedAt = :updated', - ExpressionAttributeValues={ - ':status': {'S': 'UPDATE_FAILED'}, - ':error': {'S': error_message[:1000]}, # Limit error message length - ':updated': {'S': datetime.utcnow().isoformat() + 'Z'} - } - ) - logger.info(f"Updated provider {provider_id} with error status") - except ClientError as e: - logger.error(f"Failed to update provider error status: {e}") diff --git a/backend/lambda-functions/runtime-updater/requirements.txt b/backend/lambda-functions/runtime-updater/requirements.txt deleted file mode 100644 index 288abcb0..00000000 --- a/backend/lambda-functions/runtime-updater/requirements.txt +++ /dev/null @@ -1 +0,0 @@ -boto3==1.35.93 diff --git a/backend/lambda-functions/runtime-updater/tests/__init__.py b/backend/lambda-functions/runtime-updater/tests/__init__.py deleted file mode 100644 index e69de29b..00000000 diff --git a/backend/lambda-functions/runtime-updater/tests/conftest.py b/backend/lambda-functions/runtime-updater/tests/conftest.py deleted file mode 100644 index 44a58d57..00000000 --- a/backend/lambda-functions/runtime-updater/tests/conftest.py +++ /dev/null @@ -1,290 +0,0 @@ -""" -Test fixtures for the runtime-updater Lambda function. - -Handles the tricky module-level boto3 client creation by: -1. Setting env vars before any import -2. Using moto's mock_aws for DynamoDB, SSM, and SNS -3. Patching boto3.client to intercept 'bedrock-agentcore-control' (unsupported by moto) -4. Importing/reloading lambda_function inside the fixture -5. Replacing module-level client references after reload -""" - -import importlib -import os -import sys -from unittest.mock import MagicMock, patch - -import boto3 -import pytest -from moto import mock_aws - -# --------------------------------------------------------------------------- -# Constants -# --------------------------------------------------------------------------- -PROJECT_PREFIX = "test-project" -AWS_REGION = "us-east-1" -AUTH_PROVIDERS_TABLE = "test-auth-providers" -SNS_TOPIC_ARN = "arn:aws:sns:us-east-1:123456789012:test-runtime-update-alerts" - -# --------------------------------------------------------------------------- -# A. Environment variables — autouse so every test gets them -# --------------------------------------------------------------------------- - -@pytest.fixture(autouse=True) -def _env_vars(monkeypatch): - """Inject required environment variables before lambda_function is loaded.""" - monkeypatch.setenv("PROJECT_PREFIX", PROJECT_PREFIX) - monkeypatch.setenv("AWS_REGION", AWS_REGION) - monkeypatch.setenv("AWS_DEFAULT_REGION", AWS_REGION) - monkeypatch.setenv("AUTH_PROVIDERS_TABLE", AUTH_PROVIDERS_TABLE) - monkeypatch.setenv("SNS_TOPIC_ARN", SNS_TOPIC_ARN) - # Dummy credentials for moto - monkeypatch.setenv("AWS_ACCESS_KEY_ID", "testing") - monkeypatch.setenv("AWS_SECRET_ACCESS_KEY", "testing") - monkeypatch.setenv("AWS_SECURITY_TOKEN", "testing") - monkeypatch.setenv("AWS_SESSION_TOKEN", "testing") - - -# --------------------------------------------------------------------------- -# B. Mock bedrock-agentcore-control client -# --------------------------------------------------------------------------- - -def _make_mock_bedrock_client(): - """Return a MagicMock that simulates the bedrock-agentcore-control client.""" - mock_client = MagicMock(name="bedrock-agentcore-control") - - mock_client.get_agent_runtime.return_value = { - "agentRuntimeId": "rt-123", - "agentRuntimeArn": "arn:aws:bedrock-agentcore:us-east-1:123456789012:runtime/rt-123", - "roleArn": "arn:aws:iam::123456789012:role/test-runtime-role", - "networkConfiguration": { - "networkMode": "PUBLIC", - }, - "agentRuntimeArtifact": { - "containerConfiguration": { - "containerUri": "123456789012.dkr.ecr.us-east-1.amazonaws.com/test-repo:v0.9.0", - } - }, - "authorizerConfiguration": { - "customJWTAuthorizer": { - "discoveryUrl": "https://example.com/.well-known/openid-configuration", - "allowedAudience": ["test-audience"], - "allowedClients": ["test-client-id"], - } - }, - "environmentVariables": { - "ENV_VAR_1": "value1", - "ENV_VAR_2": "value2", - }, - "status": "READY", - } - mock_client.update_agent_runtime.return_value = {} - - return mock_client - - -@pytest.fixture() -def mock_bedrock_client(): - """Expose the mock bedrock-agentcore-control client for direct assertions.""" - return _make_mock_bedrock_client() - - -# --------------------------------------------------------------------------- -# C–E. lambda_module fixture (the "reload dance") -# --------------------------------------------------------------------------- - -@pytest.fixture() -def lambda_module(mock_bedrock_client): - """ - Import (or reload) lambda_function inside moto's mock_aws context so that - the module-level boto3 clients point at moto fakes for DynamoDB/SSM/SNS and - a MagicMock for bedrock-agentcore-control. - - Returns the module object so tests can call e.g. - result = lambda_module.lambda_handler(event, {}) - - Also creates the DynamoDB table, SSM parameters, and SNS topic that the - Lambda expects. - """ - with mock_aws(): - real_boto3_client = boto3.client - - def _patched_client(service_name, *args, **kwargs): - if service_name == "bedrock-agentcore-control": - return mock_bedrock_client - return real_boto3_client(service_name, *args, **kwargs) - - with patch("boto3.client", side_effect=_patched_client): - # Prevent the Lambda from running pip install at import time - with patch("pip._internal.main", return_value=None): - # Remove cached module so it re-executes top-level code - module_key = "lambda_function" - sys.modules.pop(module_key, None) - - # Ensure the Lambda directory is on sys.path for bare imports - lambda_dir = os.path.join( - os.path.dirname(__file__), os.pardir - ) - lambda_dir = os.path.normpath(lambda_dir) - if lambda_dir not in sys.path: - sys.path.insert(0, lambda_dir) - - import lambda_function # noqa: E402 - - # --- Create AWS resources inside moto --- - - # C. DynamoDB table - ddb = boto3.client("dynamodb", region_name=AWS_REGION) - ddb.create_table( - TableName=AUTH_PROVIDERS_TABLE, - KeySchema=[ - {"AttributeName": "PK", "KeyType": "HASH"}, - {"AttributeName": "SK", "KeyType": "RANGE"}, - ], - AttributeDefinitions=[ - {"AttributeName": "PK", "AttributeType": "S"}, - {"AttributeName": "SK", "AttributeType": "S"}, - ], - BillingMode="PAY_PER_REQUEST", - ) - - # D. SSM parameters - ssm = boto3.client("ssm", region_name=AWS_REGION) - ssm.put_parameter( - Name=f"/{PROJECT_PREFIX}/inference-api/image-tag", - Value="v1.0.0", - Type="String", - ) - ssm.put_parameter( - Name=f"/{PROJECT_PREFIX}/inference-api/ecr-repository-uri", - Value="123456789012.dkr.ecr.us-east-1.amazonaws.com/test-repo", - Type="String", - ) - - # E. SNS topic - sns = boto3.client("sns", region_name=AWS_REGION) - sns.create_topic(Name="test-runtime-update-alerts") - - # Replace module-level client references with our moto/mock clients - lambda_function.dynamodb = ddb - lambda_function.ssm = ssm - lambda_function.ecr = boto3.client("ecr", region_name=AWS_REGION) - lambda_function.bedrock_agentcore = mock_bedrock_client - lambda_function.sns = sns - - yield lambda_function - - # Clean up sys.modules to avoid cross-test pollution - sys.modules.pop("lambda_function", None) - - -# --------------------------------------------------------------------------- -# F. Convenience fixtures that pull from lambda_module -# --------------------------------------------------------------------------- - -@pytest.fixture() -def dynamodb_client(lambda_module): - """Return the moto-backed DynamoDB client used by the Lambda module.""" - return lambda_module.dynamodb - - -@pytest.fixture() -def ssm_client(lambda_module): - """Return the moto-backed SSM client used by the Lambda module.""" - return lambda_module.ssm - - -@pytest.fixture() -def sns_client(lambda_module): - """Return the moto-backed SNS client used by the Lambda module.""" - return lambda_module.sns - - -@pytest.fixture() -def bedrock_client(lambda_module): - """Return the mock bedrock-agentcore-control client used by the Lambda module.""" - return lambda_module.bedrock_agentcore - - -# --------------------------------------------------------------------------- -# G. EventBridge event factory -# --------------------------------------------------------------------------- - -def make_ssm_change_event(parameter_name=None, operation="Update"): - """Create an EventBridge SSM Parameter Store Change event.""" - return { - "source": "aws.ssm", - "detail-type": "Parameter Store Change", - "detail": { - "name": parameter_name - or f"/{PROJECT_PREFIX}/inference-api/image-tag", - "operation": operation, - }, - } - - -# --------------------------------------------------------------------------- -# H. Provider record factory -# --------------------------------------------------------------------------- - -def make_provider_record( - dynamodb_client, - provider_id, - runtime_id="rt-123", - runtime_arn="arn:aws:bedrock-agentcore:us-east-1:123456789012:runtime/rt-123", - status="READY", - display_name=None, -): - """Create a provider DynamoDB item and insert it into the moto table. - - Args: - dynamodb_client: The moto-backed DynamoDB client (from the fixture). - provider_id: Unique provider identifier. - runtime_id: AgentCore runtime ID. - runtime_arn: AgentCore runtime ARN. - status: Runtime status (READY, UPDATING, FAILED, etc.). - display_name: Human-readable name; defaults to "Provider {provider_id}". - - Returns: - The item dict (raw DynamoDB format) that was inserted. - """ - item = { - "PK": {"S": f"AUTH_PROVIDER#{provider_id}"}, - "SK": {"S": f"AUTH_PROVIDER#{provider_id}"}, - "providerId": {"S": provider_id}, - "agentcoreRuntimeId": {"S": runtime_id}, - "agentcoreRuntimeArn": {"S": runtime_arn}, - "agentcoreRuntimeStatus": {"S": status}, - "displayName": {"S": display_name or f"Provider {provider_id}"}, - } - - dynamodb_client.put_item( - TableName=AUTH_PROVIDERS_TABLE, - Item=item, - ) - - return item - - -# --------------------------------------------------------------------------- -# Tip: patching time.sleep for retry tests -# --------------------------------------------------------------------------- -# Use unittest.mock.patch on the module reference: -# with patch.object(lambda_module, 'time', wraps=time) as mock_time: -# mock_time.sleep = MagicMock() -# ... -# Or more directly: -# with patch('lambda_function.time.sleep'): -# ... -# -# --------------------------------------------------------------------------- -# Tip: importing factory helpers in test files -# --------------------------------------------------------------------------- -# Because pyproject.toml uses --import-mode=importlib, bare `from conftest` -# imports don't work automatically. In each test file add: -# -# import sys, os -# _tests_dir = os.path.dirname(__file__) -# if _tests_dir not in sys.path: -# sys.path.insert(0, _tests_dir) -# from conftest import make_provider_record, make_ssm_change_event diff --git a/backend/lambda-functions/runtime-updater/tests/test_event_parsing.py b/backend/lambda-functions/runtime-updater/tests/test_event_parsing.py deleted file mode 100644 index ef947d45..00000000 --- a/backend/lambda-functions/runtime-updater/tests/test_event_parsing.py +++ /dev/null @@ -1,85 +0,0 @@ -"""Tests for EventBridge event extraction and SSM parameter functions.""" - -import sys -import os - -import pytest - -_tests_dir = os.path.dirname(__file__) -if _tests_dir not in sys.path: - sys.path.insert(0, _tests_dir) - -from conftest import make_ssm_change_event, PROJECT_PREFIX - - -def test_extract_valid_event(lambda_module): - """Correct parameter name → returns image tag from SSM.""" - event = make_ssm_change_event() - result = lambda_module.extract_image_tag_from_event(event) - assert result == "v1.0.0" - - -def test_extract_wrong_parameter_name(lambda_module): - """Different SSM param name → returns None.""" - event = make_ssm_change_event(parameter_name="/other/project/param") - result = lambda_module.extract_image_tag_from_event(event) - assert result is None - - -def test_extract_missing_detail(lambda_module): - """No 'detail' key → returns None.""" - event = {"source": "aws.ssm", "detail-type": "Parameter Store Change"} - result = lambda_module.extract_image_tag_from_event(event) - assert result is None - - -def test_extract_empty_detail(lambda_module): - """Empty detail dict → returns None.""" - event = { - "source": "aws.ssm", - "detail-type": "Parameter Store Change", - "detail": {}, - } - result = lambda_module.extract_image_tag_from_event(event) - assert result is None - - -def test_extract_missing_name_field(lambda_module): - """detail has no 'name' → returns None.""" - event = { - "source": "aws.ssm", - "detail-type": "Parameter Store Change", - "detail": {"operation": "Update"}, - } - result = lambda_module.extract_image_tag_from_event(event) - assert result is None - - -def test_get_image_tag_from_ssm(lambda_module): - """Returns 'v1.0.0' (pre-populated by conftest).""" - tag = lambda_module.get_image_tag_from_ssm() - assert tag == "v1.0.0" - - -def test_get_image_tag_ssm_error(lambda_module): - """Delete the SSM param first, then call → raises ValueError.""" - lambda_module.ssm.delete_parameter( - Name=f"/{PROJECT_PREFIX}/inference-api/image-tag" - ) - with pytest.raises(ValueError, match="Image tag not found"): - lambda_module.get_image_tag_from_ssm() - - -def test_get_container_image_uri(lambda_module): - """Returns full {repo_uri}:{tag} format.""" - uri = lambda_module.get_container_image_uri("v2.0.0") - assert uri == "123456789012.dkr.ecr.us-east-1.amazonaws.com/test-repo:v2.0.0" - - -def test_get_container_image_uri_missing_repo(lambda_module): - """Delete ECR repo SSM param → raises ValueError.""" - lambda_module.ssm.delete_parameter( - Name=f"/{PROJECT_PREFIX}/inference-api/ecr-repository-uri" - ) - with pytest.raises(ValueError, match="ECR repository URI not found"): - lambda_module.get_container_image_uri("v2.0.0") diff --git a/backend/lambda-functions/runtime-updater/tests/test_handler.py b/backend/lambda-functions/runtime-updater/tests/test_handler.py deleted file mode 100644 index ca789a7a..00000000 --- a/backend/lambda-functions/runtime-updater/tests/test_handler.py +++ /dev/null @@ -1,181 +0,0 @@ -"""Tests for the runtime-updater Lambda handler and event flow.""" - -import json -import sys -import os -from unittest.mock import MagicMock, patch - -import pytest -from botocore.exceptions import ClientError - -_tests_dir = os.path.dirname(__file__) -if _tests_dir not in sys.path: - sys.path.insert(0, _tests_dir) - -from conftest import make_ssm_change_event, make_provider_record, PROJECT_PREFIX - - -def _setup_single_provider(lambda_module): - """Insert one provider and return the valid SSM change event.""" - make_provider_record(lambda_module.dynamodb, "provider-1") - return make_ssm_change_event() - - -def test_happy_path_single_provider(lambda_module): - """One provider with runtime → bedrock update called, returns 200 with succeeded=1.""" - event = _setup_single_provider(lambda_module) - - with patch("lambda_function.time.sleep"): - result = lambda_module.lambda_handler(event, {}) - - body = json.loads(result["body"]) - assert result["statusCode"] == 200 - assert body["succeeded"] == 1 - assert body["failed"] == 0 - assert body["total"] == 1 - lambda_module.bedrock_agentcore.get_agent_runtime.assert_called() - lambda_module.bedrock_agentcore.update_agent_runtime.assert_called() - - -def test_happy_path_multiple_providers(lambda_module): - """3 providers → all updated, correct counts.""" - make_provider_record(lambda_module.dynamodb, "provider-1") - make_provider_record(lambda_module.dynamodb, "provider-2", runtime_id="rt-456") - make_provider_record(lambda_module.dynamodb, "provider-3", runtime_id="rt-789") - event = make_ssm_change_event() - - with patch("lambda_function.time.sleep"): - result = lambda_module.lambda_handler(event, {}) - - body = json.loads(result["body"]) - assert result["statusCode"] == 200 - assert body["total"] == 3 - assert body["succeeded"] == 3 - assert body["failed"] == 0 - - -def test_invalid_event_returns_400(lambda_module): - """Wrong parameter name → returns statusCode 400.""" - event = make_ssm_change_event(parameter_name="/wrong/parameter/name") - - result = lambda_module.lambda_handler(event, {}) - - assert result["statusCode"] == 400 - body = json.loads(result["body"]) - assert "error" in body - - -def test_no_providers_returns_200(lambda_module): - """No providers in DynamoDB → returns 200 with 'No runtimes to update'.""" - event = make_ssm_change_event() - - result = lambda_module.lambda_handler(event, {}) - - assert result["statusCode"] == 200 - body = json.loads(result["body"]) - assert body["message"] == "No runtimes to update" - - -def test_critical_failure_sends_sns_alert(lambda_module): - """Force an exception → SNS publish called and exception re-raised.""" - event = make_ssm_change_event() - make_provider_record(lambda_module.dynamodb, "provider-1") - - # Replace SNS with a MagicMock so we can inspect calls - lambda_module.sns = MagicMock() - - # Force get_providers_with_runtimes to raise after it succeeds - # by making get_container_image_uri fail (delete ECR repo SSM param) - lambda_module.ssm.delete_parameter( - Name=f"/{PROJECT_PREFIX}/inference-api/ecr-repository-uri" - ) - - with pytest.raises(ValueError): - with patch("lambda_function.time.sleep"): - lambda_module.lambda_handler(event, {}) - - lambda_module.sns.publish.assert_called() - # Verify the alert subject contains "CRITICAL" - call_kwargs = lambda_module.sns.publish.call_args[1] - assert "CRITICAL" in call_kwargs["Subject"] - - -def test_response_body_has_correct_counts(lambda_module): - """Verify total, succeeded, failed in response body.""" - make_provider_record(lambda_module.dynamodb, "provider-1") - make_provider_record(lambda_module.dynamodb, "provider-2", runtime_id="rt-456") - event = make_ssm_change_event() - - with patch("lambda_function.time.sleep"): - result = lambda_module.lambda_handler(event, {}) - - body = json.loads(result["body"]) - assert body["message"] == "Runtime updates completed" - assert body["total"] == 2 - assert body["succeeded"] == 2 - assert body["failed"] == 0 - - -def test_mixed_success_failure_counts(lambda_module): - """One provider succeeds, one fails → correct counts.""" - make_provider_record(lambda_module.dynamodb, "provider-1", runtime_id="rt-success") - make_provider_record(lambda_module.dynamodb, "provider-2", runtime_id="rt-fail") - event = make_ssm_change_event() - - error_response = { - "Error": {"Code": "ValidationException", "Message": "Runtime not found"} - } - - def get_runtime_side_effect(**kwargs): - runtime_id = kwargs.get("agentRuntimeId", "") - if runtime_id == "rt-fail": - raise ClientError(error_response, "GetAgentRuntime") - return { - "agentRuntimeId": runtime_id, - "agentRuntimeArn": f"arn:aws:bedrock-agentcore:us-east-1:123456789012:runtime/{runtime_id}", - "roleArn": "arn:aws:iam::123456789012:role/test-runtime-role", - "networkConfiguration": {"networkMode": "PUBLIC"}, - "agentRuntimeArtifact": { - "containerConfiguration": { - "containerUri": "123456789012.dkr.ecr.us-east-1.amazonaws.com/test-repo:v0.9.0" - } - }, - "authorizerConfiguration": { - "customJWTAuthorizer": { - "discoveryUrl": "https://example.com/.well-known/openid-configuration", - "allowedAudience": ["test-audience"], - "allowedClients": ["test-client-id"], - } - }, - "environmentVariables": {"ENV_VAR_1": "value1"}, - "status": "READY", - } - - lambda_module.bedrock_agentcore.get_agent_runtime.side_effect = get_runtime_side_effect - - with patch("lambda_function.time.sleep"): - result = lambda_module.lambda_handler(event, {}) - - body = json.loads(result["body"]) - assert result["statusCode"] == 200 - assert body["total"] == 2 - assert body["succeeded"] == 1 - assert body["failed"] == 1 - - -def test_sends_update_summary_sns(lambda_module): - """After updates complete, SNS publish called with summary.""" - make_provider_record(lambda_module.dynamodb, "provider-1") - event = make_ssm_change_event() - - # Replace SNS with a MagicMock to inspect calls - lambda_module.sns = MagicMock() - - with patch("lambda_function.time.sleep"): - result = lambda_module.lambda_handler(event, {}) - - assert result["statusCode"] == 200 - lambda_module.sns.publish.assert_called() - call_kwargs = lambda_module.sns.publish.call_args[1] - assert "Summary" in call_kwargs["Subject"] or "succeeded" in call_kwargs["Subject"] - assert "v1.0.0" in call_kwargs["Message"] diff --git a/backend/lambda-functions/runtime-updater/tests/test_helpers.py b/backend/lambda-functions/runtime-updater/tests/test_helpers.py deleted file mode 100644 index 7a845e9a..00000000 --- a/backend/lambda-functions/runtime-updater/tests/test_helpers.py +++ /dev/null @@ -1,122 +0,0 @@ -"""Tests for helper functions — deserialize_dynamodb_value, update_provider_status, update_provider_error.""" - -import sys -import os - -_tests_dir = os.path.dirname(__file__) -if _tests_dir not in sys.path: - sys.path.insert(0, _tests_dir) -from conftest import make_provider_record, AUTH_PROVIDERS_TABLE - - -# ================================================================== -# deserialize_dynamodb_value -# ================================================================== - -def test_deserialize_string(lambda_module): - assert lambda_module.deserialize_dynamodb_value({"S": "hello"}) == "hello" - - -def test_deserialize_number(lambda_module): - assert lambda_module.deserialize_dynamodb_value({"N": "42"}) == "42" - - -def test_deserialize_bool(lambda_module): - assert lambda_module.deserialize_dynamodb_value({"BOOL": True}) is True - - -def test_deserialize_null(lambda_module): - assert lambda_module.deserialize_dynamodb_value({"NULL": True}) is None - - -def test_deserialize_list(lambda_module): - result = lambda_module.deserialize_dynamodb_value({"L": [{"S": "a"}, {"S": "b"}]}) - assert result == ["a", "b"] - - -def test_deserialize_map(lambda_module): - result = lambda_module.deserialize_dynamodb_value({"M": {"k": {"S": "v"}}}) - assert result == {"k": "v"} - - -def test_deserialize_empty(lambda_module): - assert lambda_module.deserialize_dynamodb_value({}) is None - - -def test_deserialize_none(lambda_module): - assert lambda_module.deserialize_dynamodb_value(None) is None - - -# ================================================================== -# update_provider_status -# ================================================================== - -def _get_item(dynamodb_client, provider_id): - resp = dynamodb_client.get_item( - TableName=AUTH_PROVIDERS_TABLE, - Key={ - "PK": {"S": f"AUTH_PROVIDER#{provider_id}"}, - "SK": {"S": f"AUTH_PROVIDER#{provider_id}"}, - }, - ) - return resp.get("Item", {}) - - -def test_update_provider_status(lambda_module, dynamodb_client): - make_provider_record(dynamodb_client, "prov1") - lambda_module.update_provider_status("prov1", "UPDATING") - - item = _get_item(dynamodb_client, "prov1") - assert item["agentcoreRuntimeStatus"]["S"] == "UPDATING" - - -def test_update_provider_status_sets_updated_at(lambda_module, dynamodb_client): - make_provider_record(dynamodb_client, "prov2") - lambda_module.update_provider_status("prov2", "READY") - - item = _get_item(dynamodb_client, "prov2") - assert "updatedAt" in item - assert item["updatedAt"]["S"].endswith("Z") - - -# ================================================================== -# update_provider_error -# ================================================================== - -def test_update_provider_error_sets_status(lambda_module, dynamodb_client): - make_provider_record(dynamodb_client, "err1") - lambda_module.update_provider_error("err1", "boom") - - item = _get_item(dynamodb_client, "err1") - assert item["agentcoreRuntimeStatus"]["S"] == "UPDATE_FAILED" - - -def test_update_provider_error_stores_message(lambda_module, dynamodb_client): - make_provider_record(dynamodb_client, "err2") - lambda_module.update_provider_error("err2", "something went wrong") - - item = _get_item(dynamodb_client, "err2") - assert item["agentcoreRuntimeError"]["S"] == "something went wrong" - - -def test_update_provider_error_truncates_long_message(lambda_module, dynamodb_client): - make_provider_record(dynamodb_client, "err3") - long_msg = "x" * 2000 - lambda_module.update_provider_error("err3", long_msg) - - item = _get_item(dynamodb_client, "err3") - assert len(item["agentcoreRuntimeError"]["S"]) == 1000 - - -# ================================================================== -# DynamoDB key format -# ================================================================== - -def test_dynamodb_key_format(lambda_module, dynamodb_client): - make_provider_record(dynamodb_client, "key-test") - lambda_module.update_provider_status("key-test", "UPDATING") - - # Verify the key format by doing a direct get with the expected key - item = _get_item(dynamodb_client, "key-test") - assert item["PK"]["S"] == "AUTH_PROVIDER#key-test" - assert item["SK"]["S"] == "AUTH_PROVIDER#key-test" diff --git a/backend/lambda-functions/runtime-updater/tests/test_notifications.py b/backend/lambda-functions/runtime-updater/tests/test_notifications.py deleted file mode 100644 index f5cbc011..00000000 --- a/backend/lambda-functions/runtime-updater/tests/test_notifications.py +++ /dev/null @@ -1,148 +0,0 @@ -"""Tests for SNS notification functions — send_update_summary & send_critical_failure_alert.""" - -import sys -import os -from unittest.mock import MagicMock - -from botocore.exceptions import ClientError - -_tests_dir = os.path.dirname(__file__) -if _tests_dir not in sys.path: - sys.path.insert(0, _tests_dir) -from conftest import SNS_TOPIC_ARN - - -# ------------------------------------------------------------------ -# Helpers -# ------------------------------------------------------------------ - -def _result(provider_id, success, display_name=None, error=None, attempts=1): - r = { - "provider_id": provider_id, - "success": success, - "display_name": display_name or f"Provider {provider_id}", - "attempts": attempts, - } - if error: - r["error"] = error - return r - - -def _mock_sns(lambda_module): - mock = MagicMock() - lambda_module.sns = mock - return mock - - -# ------------------------------------------------------------------ -# send_update_summary -# ------------------------------------------------------------------ - -def test_update_summary_all_success(lambda_module): - mock = _mock_sns(lambda_module) - results = [_result(f"p{i}", True) for i in range(3)] - - lambda_module.send_update_summary(results, "v2.0.0") - - mock.publish.assert_called_once() - kwargs = mock.publish.call_args[1] - assert "3 succeeded, 0 failed" in kwargs["Subject"] - - -def test_update_summary_mixed(lambda_module): - mock = _mock_sns(lambda_module) - results = [ - _result("p1", True), - _result("p2", True), - _result("p3", False, error="timeout"), - ] - - lambda_module.send_update_summary(results, "v2.0.0") - - kwargs = mock.publish.call_args[1] - assert "2 succeeded, 1 failed" in kwargs["Subject"] - assert "timeout" in kwargs["Message"] - - -def test_update_summary_all_failures(lambda_module): - mock = _mock_sns(lambda_module) - results = [ - _result("p1", False, error="err-a"), - _result("p2", False, error="err-b"), - _result("p3", False, error="err-c"), - ] - - lambda_module.send_update_summary(results, "v2.0.0") - - kwargs = mock.publish.call_args[1] - assert "0 succeeded, 3 failed" in kwargs["Subject"] - for err in ("err-a", "err-b", "err-c"): - assert err in kwargs["Message"] - - -def test_update_summary_includes_image_tag(lambda_module): - mock = _mock_sns(lambda_module) - results = [_result("p1", True)] - - lambda_module.send_update_summary(results, "v3.5.1") - - kwargs = mock.publish.call_args[1] - assert "v3.5.1" in kwargs["Message"] - - -def test_update_summary_failure_details(lambda_module): - mock = _mock_sns(lambda_module) - results = [ - _result("p1", False, display_name="Acme Corp", error="connection refused", attempts=3), - ] - - lambda_module.send_update_summary(results, "v1.0.0") - - msg = mock.publish.call_args[1]["Message"] - assert "Acme Corp" in msg - assert "connection refused" in msg - assert "3" in msg - - -# ------------------------------------------------------------------ -# send_critical_failure_alert -# ------------------------------------------------------------------ - -def test_critical_failure_alert_subject(lambda_module): - mock = _mock_sns(lambda_module) - lambda_module.send_critical_failure_alert("something broke") - - kwargs = mock.publish.call_args[1] - assert kwargs["Subject"] == "CRITICAL: AgentCore Runtime Updater Failed" - - -def test_critical_failure_alert_includes_error(lambda_module): - mock = _mock_sns(lambda_module) - lambda_module.send_critical_failure_alert("disk full") - - kwargs = mock.publish.call_args[1] - assert "disk full" in kwargs["Message"] - - -def test_critical_failure_alert_includes_timestamp(lambda_module): - mock = _mock_sns(lambda_module) - lambda_module.send_critical_failure_alert("oops") - - msg = mock.publish.call_args[1]["Message"] - # Timestamp format: YYYY-MM-DDTHH:MM:SS - import re - assert re.search(r"\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}", msg) - - -# ------------------------------------------------------------------ -# SNS publish failure handled gracefully -# ------------------------------------------------------------------ - -def test_sns_publish_failure_handled(lambda_module): - mock = _mock_sns(lambda_module) - mock.publish.side_effect = ClientError( - {"Error": {"Code": "InternalError", "Message": "SNS error"}}, "Publish" - ) - - # Should not raise - lambda_module.send_update_summary([_result("p1", True)], "v1.0.0") diff --git a/backend/lambda-functions/runtime-updater/tests/test_parallel.py b/backend/lambda-functions/runtime-updater/tests/test_parallel.py deleted file mode 100644 index 8474792d..00000000 --- a/backend/lambda-functions/runtime-updater/tests/test_parallel.py +++ /dev/null @@ -1,97 +0,0 @@ -"""Tests for parallel runtime update execution (update_runtimes_parallel).""" - -import sys -import os -from unittest.mock import patch, MagicMock - -_tests_dir = os.path.dirname(__file__) -if _tests_dir not in sys.path: - sys.path.insert(0, _tests_dir) - -from conftest import make_provider_record, AUTH_PROVIDERS_TABLE - - -def _make_providers(n): - """Return a list of n provider dicts.""" - return [ - {"provider_id": f"p{i}", "runtime_id": f"rt-{i}", "display_name": f"Provider {i}"} - for i in range(1, n + 1) - ] - - -def _seed_providers(lambda_module, providers): - """Insert provider records into moto DynamoDB.""" - for p in providers: - make_provider_record( - lambda_module.dynamodb, p["provider_id"], runtime_id=p["runtime_id"] - ) - - -class TestUpdateRuntimesParallel: - - def test_single_provider_updated(self, lambda_module): - providers = _make_providers(1) - _seed_providers(lambda_module, providers) - - with patch("lambda_function.time.sleep"): - results = lambda_module.update_runtimes_parallel(providers, "repo:v2.0.0") - - assert len(results) == 1 - assert results[0]["success"] is True - assert results[0]["provider_id"] == "p1" - - def test_multiple_providers_all_succeed(self, lambda_module): - providers = _make_providers(3) - _seed_providers(lambda_module, providers) - - with patch("lambda_function.time.sleep"): - results = lambda_module.update_runtimes_parallel(providers, "repo:v2.0.0") - - assert len(results) == 3 - assert all(r["success"] is True for r in results) - returned_ids = {r["provider_id"] for r in results} - assert returned_ids == {"p1", "p2", "p3"} - - def test_results_contain_all_providers(self, lambda_module): - providers = _make_providers(5) - _seed_providers(lambda_module, providers) - - with patch("lambda_function.time.sleep"): - results = lambda_module.update_runtimes_parallel(providers, "repo:v2.0.0") - - assert len(results) == 5 - returned_ids = {r["provider_id"] for r in results} - assert returned_ids == {f"p{i}" for i in range(1, 6)} - - def test_unexpected_exception_captured(self, lambda_module): - """A non-ClientError raised inside the thread is captured with attempts=0.""" - providers = _make_providers(1) - _seed_providers(lambda_module, providers) - - # Make update_runtime_with_retry raise a raw Exception that escapes the - # retry loop entirely, so it is caught by the future.result() handler. - with patch("lambda_function.time.sleep"), \ - patch.object( - lambda_module, "update_runtime_with_retry", - side_effect=RuntimeError("boom"), - ): - results = lambda_module.update_runtimes_parallel(providers, "repo:v2.0.0") - - assert len(results) == 1 - assert results[0]["success"] is False - assert results[0]["attempts"] == 0 - assert "boom" in results[0]["error"] - - def test_max_workers_is_five(self, lambda_module): - assert lambda_module.MAX_CONCURRENT_UPDATES == 5 - - def test_many_providers_batched(self, lambda_module): - providers = _make_providers(10) - _seed_providers(lambda_module, providers) - - with patch("lambda_function.time.sleep"): - results = lambda_module.update_runtimes_parallel(providers, "repo:v2.0.0") - - assert len(results) == 10 - returned_ids = {r["provider_id"] for r in results} - assert returned_ids == {f"p{i}" for i in range(1, 11)} diff --git a/backend/lambda-functions/runtime-updater/tests/test_providers.py b/backend/lambda-functions/runtime-updater/tests/test_providers.py deleted file mode 100644 index 443de38c..00000000 --- a/backend/lambda-functions/runtime-updater/tests/test_providers.py +++ /dev/null @@ -1,116 +0,0 @@ -"""Tests for get_providers_with_runtimes — DynamoDB provider discovery.""" - -import sys -import os - -_tests_dir = os.path.dirname(__file__) -if _tests_dir not in sys.path: - sys.path.insert(0, _tests_dir) -from conftest import make_provider_record, AUTH_PROVIDERS_TABLE - - -# ------------------------------------------------------------------ -# 1. Two providers with runtimes → both returned -# ------------------------------------------------------------------ - -def test_returns_providers_with_runtimes(lambda_module, dynamodb_client): - make_provider_record(dynamodb_client, "prov-a") - make_provider_record(dynamodb_client, "prov-b") - - providers = lambda_module.get_providers_with_runtimes() - assert len(providers) == 2 - ids = {p["provider_id"] for p in providers} - assert ids == {"prov-a", "prov-b"} - - -# ------------------------------------------------------------------ -# 2. FAILED status → excluded -# ------------------------------------------------------------------ - -def test_excludes_failed_providers(lambda_module, dynamodb_client): - make_provider_record(dynamodb_client, "good", status="READY") - make_provider_record(dynamodb_client, "bad", status="FAILED") - - providers = lambda_module.get_providers_with_runtimes() - assert len(providers) == 1 - assert providers[0]["provider_id"] == "good" - - -# ------------------------------------------------------------------ -# 3. Provider without agentcoreRuntimeId → excluded -# ------------------------------------------------------------------ - -def test_excludes_providers_without_runtime_id(lambda_module, dynamodb_client): - # Insert manually without runtime id - dynamodb_client.put_item( - TableName=AUTH_PROVIDERS_TABLE, - Item={ - "PK": {"S": "AUTH_PROVIDER#no-runtime"}, - "SK": {"S": "AUTH_PROVIDER#no-runtime"}, - "providerId": {"S": "no-runtime"}, - "agentcoreRuntimeStatus": {"S": "READY"}, - "displayName": {"S": "No Runtime Provider"}, - }, - ) - make_provider_record(dynamodb_client, "with-runtime") - - providers = lambda_module.get_providers_with_runtimes() - assert len(providers) == 1 - assert providers[0]["provider_id"] == "with-runtime" - - -# ------------------------------------------------------------------ -# 4. Empty table → empty list -# ------------------------------------------------------------------ - -def test_empty_table_returns_empty_list(lambda_module): - providers = lambda_module.get_providers_with_runtimes() - assert providers == [] - - -# ------------------------------------------------------------------ -# 5. Fields deserialized correctly -# ------------------------------------------------------------------ - -def test_provider_fields_deserialized(lambda_module, dynamodb_client): - make_provider_record( - dynamodb_client, - "prov-1", - runtime_id="rt-abc", - runtime_arn="arn:aws:bedrock-agentcore:us-east-1:111:runtime/rt-abc", - display_name="My Provider", - ) - - providers = lambda_module.get_providers_with_runtimes() - assert len(providers) == 1 - p = providers[0] - assert p["provider_id"] == "prov-1" - assert p["runtime_id"] == "rt-abc" - assert p["runtime_arn"] == "arn:aws:bedrock-agentcore:us-east-1:111:runtime/rt-abc" - assert p["display_name"] == "My Provider" - - -# ------------------------------------------------------------------ -# 6. Non-FAILED statuses are all included -# ------------------------------------------------------------------ - -def test_includes_non_failed_statuses(lambda_module, dynamodb_client): - make_provider_record(dynamodb_client, "ready", status="READY") - make_provider_record(dynamodb_client, "updating", status="UPDATING") - make_provider_record(dynamodb_client, "update-failed", status="UPDATE_FAILED") - - providers = lambda_module.get_providers_with_runtimes() - ids = {p["provider_id"] for p in providers} - assert ids == {"ready", "updating", "update-failed"} - - -# ------------------------------------------------------------------ -# 7. Pagination — at least >25 items returned when 30 inserted -# ------------------------------------------------------------------ - -def test_pagination_collects_all(lambda_module, dynamodb_client): - for i in range(30): - make_provider_record(dynamodb_client, f"prov-{i:03d}") - - providers = lambda_module.get_providers_with_runtimes() - assert len(providers) == 30 diff --git a/backend/lambda-functions/runtime-updater/tests/test_retry.py b/backend/lambda-functions/runtime-updater/tests/test_retry.py deleted file mode 100644 index 5d0742b0..00000000 --- a/backend/lambda-functions/runtime-updater/tests/test_retry.py +++ /dev/null @@ -1,293 +0,0 @@ -"""Tests for retry logic, backoff, and error classification (update_runtime_with_retry).""" - -import sys -import os -from unittest.mock import patch, MagicMock, call - -from botocore.exceptions import ClientError - -_tests_dir = os.path.dirname(__file__) -if _tests_dir not in sys.path: - sys.path.insert(0, _tests_dir) - -from conftest import make_provider_record, AUTH_PROVIDERS_TABLE - - -def _make_client_error(code, message="test error"): - return ClientError( - {"Error": {"Code": code, "Message": message}}, "UpdateAgentRuntime" - ) - - -def _success_runtime_response(): - return { - "roleArn": "arn:aws:iam::123456789012:role/test-runtime-role", - "networkConfiguration": {"networkMode": "PUBLIC"}, - "agentRuntimeArtifact": { - "containerConfiguration": {"containerUri": "old-repo:v1"} - }, - "authorizerConfiguration": { - "customJWTAuthorizer": { - "discoveryUrl": "https://example.com/.well-known/openid-configuration", - "allowedAudience": ["aud"], - "allowedClients": ["client"], - } - }, - "environmentVariables": {"KEY": "value"}, - } - - -_PROVIDER = {"provider_id": "p1", "runtime_id": "rt-1", "display_name": "Provider 1"} - - -def _seed(lambda_module): - make_provider_record( - lambda_module.dynamodb, "p1", runtime_id="rt-1" - ) - - -def _get_db_status(lambda_module, provider_id="p1"): - resp = lambda_module.dynamodb.get_item( - TableName=AUTH_PROVIDERS_TABLE, - Key={ - "PK": {"S": f"AUTH_PROVIDER#{provider_id}"}, - "SK": {"S": f"AUTH_PROVIDER#{provider_id}"}, - }, - ) - return resp["Item"] - - -class TestRetryLogic: - - def test_success_on_first_attempt(self, lambda_module): - _seed(lambda_module) - lambda_module.bedrock_agentcore.get_agent_runtime.return_value = ( - _success_runtime_response() - ) - lambda_module.bedrock_agentcore.update_agent_runtime.return_value = {} - - with patch("lambda_function.time.sleep"): - result = lambda_module.update_runtime_with_retry(_PROVIDER, "repo:v2.0.0") - - assert result["success"] is True - assert result["attempts"] == 1 - - def test_throttling_retries(self, lambda_module): - _seed(lambda_module) - lambda_module.bedrock_agentcore.get_agent_runtime.side_effect = [ - _make_client_error("ThrottlingException"), - _make_client_error("ThrottlingException"), - _success_runtime_response(), - ] - lambda_module.bedrock_agentcore.update_agent_runtime.return_value = {} - - with patch("lambda_function.time.sleep") as mock_sleep: - result = lambda_module.update_runtime_with_retry(_PROVIDER, "repo:v2.0.0") - - assert result["success"] is True - assert result["attempts"] == 3 - mock_sleep.assert_any_call(2) # 2^1 - mock_sleep.assert_any_call(4) # 2^2 - - def test_service_unavailable_retries(self, lambda_module): - _seed(lambda_module) - lambda_module.bedrock_agentcore.get_agent_runtime.side_effect = [ - _make_client_error("ServiceUnavailableException"), - _success_runtime_response(), - ] - lambda_module.bedrock_agentcore.update_agent_runtime.return_value = {} - - with patch("lambda_function.time.sleep") as mock_sleep: - result = lambda_module.update_runtime_with_retry(_PROVIDER, "repo:v2.0.0") - - assert result["success"] is True - assert result["attempts"] == 2 - mock_sleep.assert_called_once_with(2) # 2^1 - - def test_resource_not_found_fails_immediately(self, lambda_module): - _seed(lambda_module) - lambda_module.bedrock_agentcore.get_agent_runtime.side_effect = _make_client_error( - "ResourceNotFoundException" - ) - - with patch("lambda_function.time.sleep") as mock_sleep: - result = lambda_module.update_runtime_with_retry(_PROVIDER, "repo:v2.0.0") - - assert result["success"] is False - assert result["attempts"] == 1 - mock_sleep.assert_not_called() - - def test_validation_exception_fails_immediately(self, lambda_module): - _seed(lambda_module) - lambda_module.bedrock_agentcore.get_agent_runtime.side_effect = _make_client_error( - "ValidationException" - ) - - with patch("lambda_function.time.sleep") as mock_sleep: - result = lambda_module.update_runtime_with_retry(_PROVIDER, "repo:v2.0.0") - - assert result["success"] is False - assert result["attempts"] == 1 - mock_sleep.assert_not_called() - - def test_exponential_backoff_timing(self, lambda_module): - _seed(lambda_module) - lambda_module.bedrock_agentcore.get_agent_runtime.side_effect = [ - _make_client_error("ThrottlingException"), - _make_client_error("ThrottlingException"), - _success_runtime_response(), - ] - lambda_module.bedrock_agentcore.update_agent_runtime.return_value = {} - - with patch("lambda_function.time.sleep") as mock_sleep: - lambda_module.update_runtime_with_retry(_PROVIDER, "repo:v2.0.0") - - assert mock_sleep.call_args_list == [call(2), call(4)] - - def test_max_retries_exhausted(self, lambda_module): - _seed(lambda_module) - lambda_module.bedrock_agentcore.get_agent_runtime.side_effect = [ - _make_client_error("ThrottlingException"), - _make_client_error("ThrottlingException"), - _make_client_error("ThrottlingException"), - ] - - with patch("lambda_function.time.sleep"): - result = lambda_module.update_runtime_with_retry(_PROVIDER, "repo:v2.0.0") - - assert result["success"] is False - assert result["attempts"] == 3 - - def test_status_transitions_updating_then_ready(self, lambda_module): - _seed(lambda_module) - lambda_module.bedrock_agentcore.get_agent_runtime.return_value = ( - _success_runtime_response() - ) - lambda_module.bedrock_agentcore.update_agent_runtime.return_value = {} - - with patch("lambda_function.time.sleep"): - lambda_module.update_runtime_with_retry(_PROVIDER, "repo:v2.0.0") - - item = _get_db_status(lambda_module) - assert item["agentcoreRuntimeStatus"]["S"] == "READY" - - def test_status_transitions_updating_then_failed(self, lambda_module): - _seed(lambda_module) - lambda_module.bedrock_agentcore.get_agent_runtime.side_effect = _make_client_error( - "ResourceNotFoundException", "not found" - ) - - with patch("lambda_function.time.sleep"): - lambda_module.update_runtime_with_retry(_PROVIDER, "repo:v2.0.0") - - item = _get_db_status(lambda_module) - assert item["agentcoreRuntimeStatus"]["S"] == "UPDATE_FAILED" - - def test_non_client_error_retries(self, lambda_module): - _seed(lambda_module) - lambda_module.bedrock_agentcore.get_agent_runtime.side_effect = [ - RuntimeError("transient"), - _success_runtime_response(), - ] - lambda_module.bedrock_agentcore.update_agent_runtime.return_value = {} - - with patch("lambda_function.time.sleep") as mock_sleep: - result = lambda_module.update_runtime_with_retry(_PROVIDER, "repo:v2.0.0") - - assert result["success"] is True - assert result["attempts"] == 2 - mock_sleep.assert_called_once_with(2) - - def test_error_message_in_dynamodb(self, lambda_module): - _seed(lambda_module) - lambda_module.bedrock_agentcore.get_agent_runtime.side_effect = _make_client_error( - "ResourceNotFoundException", "Runtime rt-1 does not exist" - ) - - with patch("lambda_function.time.sleep"): - lambda_module.update_runtime_with_retry(_PROVIDER, "repo:v2.0.0") - - item = _get_db_status(lambda_module) - assert item["agentcoreRuntimeStatus"]["S"] == "UPDATE_FAILED" - assert "rt-1 does not exist" in item["agentcoreRuntimeError"]["S"] - - def test_update_preserves_runtime_config(self, lambda_module): - _seed(lambda_module) - runtime_resp = _success_runtime_response() - lambda_module.bedrock_agentcore.get_agent_runtime.return_value = runtime_resp - lambda_module.bedrock_agentcore.update_agent_runtime.return_value = {} - - with patch("lambda_function.time.sleep"): - lambda_module.update_runtime_with_retry(_PROVIDER, "repo:v2.0.0") - - lambda_module.bedrock_agentcore.update_agent_runtime.assert_called_once() - call_kwargs = lambda_module.bedrock_agentcore.update_agent_runtime.call_args[1] - - assert call_kwargs["agentRuntimeId"] == "rt-1" - assert call_kwargs["agentRuntimeArtifact"] == { - "containerConfiguration": {"containerUri": "repo:v2.0.0"} - } - assert call_kwargs["roleArn"] == runtime_resp["roleArn"] - assert call_kwargs["networkConfiguration"] == runtime_resp["networkConfiguration"] - assert call_kwargs["authorizerConfiguration"] == runtime_resp["authorizerConfiguration"] - # Env vars are refreshed from SSM (not blindly preserved from runtime). - # The refreshed set should include static config vars at minimum. - env_vars = call_kwargs["environmentVariables"] - assert "PROJECT_NAME" in env_vars - assert "PROVIDER_ID" in env_vars - assert env_vars["PROVIDER_ID"] == "p1" - - def test_update_always_includes_authorization_header(self, lambda_module): - """Authorization header MUST be in requestHeaderAllowlist even when - the current runtime has NO requestHeaderConfiguration at all.""" - _seed(lambda_module) - runtime_resp = _success_runtime_response() - # Simulate the field being absent from GetAgentRuntime response - runtime_resp.pop("requestHeaderConfiguration", None) - lambda_module.bedrock_agentcore.get_agent_runtime.return_value = runtime_resp - lambda_module.bedrock_agentcore.update_agent_runtime.return_value = {} - - with patch("lambda_function.time.sleep"): - lambda_module.update_runtime_with_retry(_PROVIDER, "repo:v2.0.0") - - call_kwargs = lambda_module.bedrock_agentcore.update_agent_runtime.call_args[1] - header_cfg = call_kwargs["requestHeaderConfiguration"] - assert "Authorization" in header_cfg["requestHeaderAllowlist"] - - def test_update_preserves_custom_headers_alongside_authorization(self, lambda_module): - """Existing custom headers must be preserved, and Authorization must - still be present even if it wasn't in the original allowlist.""" - _seed(lambda_module) - runtime_resp = _success_runtime_response() - runtime_resp["requestHeaderConfiguration"] = { - "requestHeaderAllowlist": [ - "X-Amzn-Bedrock-AgentCore-Runtime-Custom-Trace-Id" - ] - } - lambda_module.bedrock_agentcore.get_agent_runtime.return_value = runtime_resp - lambda_module.bedrock_agentcore.update_agent_runtime.return_value = {} - - with patch("lambda_function.time.sleep"): - lambda_module.update_runtime_with_retry(_PROVIDER, "repo:v2.0.0") - - call_kwargs = lambda_module.bedrock_agentcore.update_agent_runtime.call_args[1] - allowlist = call_kwargs["requestHeaderConfiguration"]["requestHeaderAllowlist"] - assert "Authorization" in allowlist - assert "X-Amzn-Bedrock-AgentCore-Runtime-Custom-Trace-Id" in allowlist - - def test_update_does_not_duplicate_authorization_header(self, lambda_module): - """If Authorization is already in the allowlist, it should not appear twice.""" - _seed(lambda_module) - runtime_resp = _success_runtime_response() - runtime_resp["requestHeaderConfiguration"] = { - "requestHeaderAllowlist": ["Authorization"] - } - lambda_module.bedrock_agentcore.get_agent_runtime.return_value = runtime_resp - lambda_module.bedrock_agentcore.update_agent_runtime.return_value = {} - - with patch("lambda_function.time.sleep"): - lambda_module.update_runtime_with_retry(_PROVIDER, "repo:v2.0.0") - - call_kwargs = lambda_module.bedrock_agentcore.update_agent_runtime.call_args[1] - allowlist = call_kwargs["requestHeaderConfiguration"]["requestHeaderAllowlist"] - assert allowlist.count("Authorization") == 1 diff --git a/backend/lambda-functions/runtime-updater/tests/test_smoke.py b/backend/lambda-functions/runtime-updater/tests/test_smoke.py deleted file mode 100644 index ebbdeb5b..00000000 --- a/backend/lambda-functions/runtime-updater/tests/test_smoke.py +++ /dev/null @@ -1,70 +0,0 @@ -"""Smoke tests to verify conftest fixtures wire up correctly.""" - -import sys -import os - -# Make the tests directory importable so we can use the conftest helpers -_tests_dir = os.path.dirname(__file__) -if _tests_dir not in sys.path: - sys.path.insert(0, _tests_dir) - -from conftest import make_provider_record, make_ssm_change_event - - -def test_lambda_module_loads(lambda_module): - """The lambda_function module loads with mocked clients.""" - assert hasattr(lambda_module, "lambda_handler") - assert hasattr(lambda_module, "dynamodb") - assert hasattr(lambda_module, "bedrock_agentcore") - - -def test_dynamodb_table_exists(dynamodb_client): - """The moto DynamoDB table was created.""" - resp = dynamodb_client.describe_table(TableName="test-auth-providers") - assert resp["Table"]["TableName"] == "test-auth-providers" - - -def test_ssm_params_populated(ssm_client): - """SSM parameters are pre-populated.""" - resp = ssm_client.get_parameter(Name="/test-project/inference-api/image-tag") - assert resp["Parameter"]["Value"] == "v1.0.0" - - -def test_sns_topic_exists(sns_client): - """The SNS topic was created in moto.""" - resp = sns_client.list_topics() - arns = [t["TopicArn"] for t in resp["Topics"]] - assert any("test-runtime-update-alerts" in a for a in arns) - - -def test_bedrock_client_is_mock(bedrock_client): - """The bedrock-agentcore-control client is a MagicMock.""" - resp = bedrock_client.get_agent_runtime(agentRuntimeId="rt-123") - assert resp["roleArn"] == "arn:aws:iam::123456789012:role/test-runtime-role" - - -def test_make_provider_record(dynamodb_client): - """make_provider_record inserts into the DynamoDB table.""" - make_provider_record(dynamodb_client, "prov-1") - resp = dynamodb_client.get_item( - TableName="test-auth-providers", - Key={ - "PK": {"S": "AUTH_PROVIDER#prov-1"}, - "SK": {"S": "AUTH_PROVIDER#prov-1"}, - }, - ) - assert resp["Item"]["providerId"]["S"] == "prov-1" - - -def test_make_ssm_change_event(): - """make_ssm_change_event returns a well-formed event.""" - event = make_ssm_change_event() - assert event["source"] == "aws.ssm" - assert event["detail"]["name"] == "/test-project/inference-api/image-tag" - - -def test_lambda_handler_no_providers(lambda_module): - """lambda_handler returns 200 with no providers to update.""" - event = make_ssm_change_event() - result = lambda_module.lambda_handler(event, {}) - assert result["statusCode"] == 200 diff --git a/backend/pyproject.toml b/backend/pyproject.toml index 646eff15..a663670c 100644 --- a/backend/pyproject.toml +++ b/backend/pyproject.toml @@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta" [project] name = "agentcore-stack" -version = "1.0.0-beta.20" +version = "1.0.0-beta.22" requires-python = ">=3.10" description = "Multi-agent conversational AI system with AWS Bedrock AgentCore" readme = "README.md" @@ -13,11 +13,11 @@ license = {text = "MIT"} # Core dependencies shared across both APIs dependencies = [ # FastAPI and web framework - "fastapi==0.135.2", - "uvicorn[standard]==0.42.0", + "fastapi==0.135.3", + "uvicorn[standard]==0.44.0", # AWS and cloud services - "boto3==1.42.78", + "boto3==1.42.83", # Utilities "python-dotenv==1.2.2", @@ -38,14 +38,14 @@ dependencies = [ [project.optional-dependencies] # AgentCore-specific dependencies (for inference_api) agentcore = [ - "strands-agents==1.33.0", + "strands-agents==1.34.1", "strands-agents-tools==0.3.0", "aws-opentelemetry-distro==0.16.0", - "bedrock-agentcore==1.4.8", + "bedrock-agentcore==1.6.0", # Multi-provider LLM support "openai==2.30.0", # For OpenAI models - "google-genai==1.69.0", # For Google Gemini models + "google-genai==1.70.0", # For Google Gemini models ] # Document ingestion pipeline dependencies (for Lambda deployment) @@ -59,11 +59,11 @@ dev = [ "pytest==9.0.2", "pytest-asyncio==1.3.0", "pytest-cov==7.1.0", - "hypothesis==6.151.10", - "moto[dynamodb]==5.1.22", + "hypothesis==6.151.11", + "moto[dynamodb,cognitoidp]==5.1.22", "black==26.3.1", - "ruff==0.15.8", - "mypy==1.19.1", + "ruff==0.15.9", + "mypy==1.20.0", "types-aiofiles==25.1.0.20251011", "tiktoken==0.12.0", "numpy==2.2.6", diff --git a/backend/scripts/seed_bootstrap_data.py b/backend/scripts/seed_bootstrap_data.py index d93d7818..78875523 100644 --- a/backend/scripts/seed_bootstrap_data.py +++ b/backend/scripts/seed_bootstrap_data.py @@ -2,34 +2,25 @@ """ Bootstrap data seeding script for first-time platform deployment. -Seeds auth providers, quota tiers, quota assignments, Bedrock models, -and system admin JWT role mappings into DynamoDB and Secrets Manager. -Designed to be invoked by scripts/stack-bootstrap/seed.sh after -infrastructure deployment. +Seeds quota tiers, quota assignments, Bedrock models, system admin role, +and default tools into DynamoDB. Designed to be invoked by +scripts/stack-bootstrap/seed.sh after infrastructure deployment. + +Auth provider seeding has been removed — admin authentication is now +handled via the Cognito first-boot flow. All operations are idempotent: re-running with identical inputs produces the same database state. Environment variables: - DDB_AUTH_PROVIDERS_TABLE - Auth providers DynamoDB table name DDB_USER_QUOTAS_TABLE - User quotas DynamoDB table name DDB_MANAGED_MODELS_TABLE - Managed models DynamoDB table name DDB_APP_ROLES_TABLE - App roles DynamoDB table name - SECRETS_AUTH_ARN - Secrets Manager ARN for auth secrets AWS_REGION - AWS region - - SEED_AUTH_PROVIDER_ID - Provider slug (e.g., entra-id) - SEED_AUTH_DISPLAY_NAME - Login page display name - SEED_AUTH_ISSUER_URL - OIDC issuer URL - SEED_AUTH_CLIENT_ID - OAuth client ID - SEED_AUTH_CLIENT_SECRET - OAuth client secret - SEED_AUTH_BUTTON_COLOR - Hex color for login button (optional) - SEED_ADMIN_JWT_ROLE - JWT role that grants system admin access (e.g., Admin) """ from __future__ import annotations -import json import logging import os import sys @@ -40,7 +31,6 @@ from typing import Any import boto3 -import httpx from botocore.exceptions import ClientError logger = logging.getLogger("seed_bootstrap_data") @@ -65,148 +55,6 @@ class SeedResult: details: list[str] = field(default_factory=list) -def seed_auth_provider( - table_name: str, - secrets_arn: str, - region: str, - provider_id: str, - display_name: str, - issuer_url: str, - client_id: str, - client_secret: str, - button_color: str | None = None, - discover: bool = True, -) -> SeedResult: - """Seed a single OIDC auth provider into DynamoDB and Secrets Manager.""" - result = SeedResult(category="auth_provider") - session = boto3.Session(region_name=region) - dynamodb = session.resource("dynamodb") - table = dynamodb.Table(table_name) - secrets_client = session.client("secretsmanager") - - pk = f"AUTH_PROVIDER#{provider_id}" - - # Check for existing item - try: - existing = table.get_item(Key={"PK": pk, "SK": pk}) - if "Item" in existing: - msg = f"Auth provider '{provider_id}' already exists — skipped" - logger.info(msg) - result.skipped = 1 - result.details.append(msg) - return result - except ClientError as e: - error_code = e.response["Error"]["Code"] - msg = f"Failed to check existing auth provider '{provider_id}': {error_code}" - logger.error(msg) - result.failed = 1 - result.details.append(msg) - return result - - # OIDC discovery - discovered: dict[str, Any] = {} - if discover: - discovery_url = issuer_url.rstrip("/") + "/.well-known/openid-configuration" - logger.info("Discovering OIDC endpoints from %s", discovery_url) - try: - resp = httpx.get(discovery_url, timeout=10.0, follow_redirects=True) - resp.raise_for_status() - discovered = resp.json() - logger.info("OIDC discovery successful") - except Exception as e: - logger.warning("OIDC discovery failed: %s — continuing without discovered endpoints", e) - - now = datetime.now(timezone.utc).isoformat().replace("+00:00", "Z") - - item: dict[str, Any] = { - "PK": pk, - "SK": pk, - "GSI1PK": "ENABLED#true", - "GSI1SK": pk, - "providerId": provider_id, - "displayName": display_name, - "providerType": "oidc", - "enabled": True, - "issuerUrl": issuer_url, - "clientId": client_id, - "scopes": "openid profile email", - "responseType": "code", - "pkceEnabled": True, - "userIdClaim": "sub", - "emailClaim": "email", - "nameClaim": "name", - "rolesClaim": "roles", - "pictureClaim": "picture", - "firstNameClaim": "given_name", - "lastNameClaim": "family_name", - "createdAt": now, - "updatedAt": now, - "createdBy": "bootstrap-seed", - } - - # Map discovered endpoints - endpoint_mapping = { - "authorizationEndpoint": "authorization_endpoint", - "tokenEndpoint": "token_endpoint", - "jwksUri": "jwks_uri", - "userinfoEndpoint": "userinfo_endpoint", - "endSessionEndpoint": "end_session_endpoint", - } - for dynamo_key, oidc_key in endpoint_mapping.items(): - value = discovered.get(oidc_key) - if value: - item[dynamo_key] = value - - if button_color: - item["buttonColor"] = button_color - - # Write to DynamoDB - try: - table.put_item(Item=item) - logger.info("Auth provider '%s' written to DynamoDB", provider_id) - except ClientError as e: - error_code = e.response["Error"]["Code"] - msg = f"Failed to write auth provider '{provider_id}' to DynamoDB: {error_code}" - logger.error(msg) - result.failed = 1 - result.details.append(msg) - return result - - # Write client secret to Secrets Manager - try: - try: - response = secrets_client.get_secret_value(SecretId=secrets_arn) - secrets = json.loads(response["SecretString"]) - except ClientError as e: - if e.response["Error"]["Code"] == "ResourceNotFoundException": - secrets = {} - else: - raise - except (json.JSONDecodeError, KeyError): - secrets = {} - - if provider_id not in secrets: - secrets[provider_id] = client_secret - secrets_client.put_secret_value( - SecretId=secrets_arn, - SecretString=json.dumps(secrets), - ) - logger.info("Client secret for '%s' stored in Secrets Manager", provider_id) - else: - logger.info("Client secret for '%s' already in Secrets Manager — kept existing", provider_id) - except ClientError as e: - error_code = e.response["Error"]["Code"] - msg = f"Failed to write secret for '{provider_id}': {error_code}" - logger.error(msg) - result.failed = 1 - result.details.append(msg) - return result - - result.created = 1 - result.details.append(f"Auth provider '{provider_id}' created") - return result - - def seed_default_quota_tier( table_name: str, region: str, @@ -476,8 +324,8 @@ def seed_system_admin_role( ) -> SeedResult: """Seed the system_admin role with DEFINITION, MODEL_GRANT#*, and TOOL_GRANT#*. - This runs unconditionally (no JWT role required). The JWT mapping - is handled separately by seed_system_admin_jwt_roles. + This runs unconditionally (no JWT role required). Admin access is now + granted via the Cognito first-boot flow. """ result = SeedResult(category="system_admin_role") session = boto3.Session(region_name=region) @@ -490,10 +338,50 @@ def seed_system_admin_role( try: existing = table.get_item(Key={"PK": pk, "SK": "DEFINITION"}) if "Item" in existing: - msg = "system_admin role already exists — skipped" - logger.info(msg) - result.skipped = 1 - result.details.append(msg) + # Role exists — ensure JWT mapping is present (additive, non-destructive) + try: + jwt_check = table.get_item(Key={"PK": pk, "SK": "JWT_MAPPING#system_admin"}) + if "Item" in jwt_check: + msg = "system_admin role already exists with JWT mapping — skipped" + logger.info(msg) + result.skipped = 1 + result.details.append(msg) + return result + except ClientError: + pass # If check fails, try to add the mapping anyway + + # JWT mapping is missing — add it without touching anything else + logger.info("system_admin role exists but JWT_MAPPING#system_admin is missing — adding it") + try: + jwt_mapping_item = { + "PK": pk, + "SK": "JWT_MAPPING#system_admin", + "GSI1PK": "JWT_ROLE#system_admin", + "GSI1SK": pk, + "roleId": role_id, + "enabled": True, + } + table.put_item(Item=jwt_mapping_item) + + # Also update the DEFINITION to include the mapping in jwtRoleMappings + existing_mappings = existing["Item"].get("jwtRoleMappings", []) + if "system_admin" not in existing_mappings: + existing_mappings.append("system_admin") + table.update_item( + Key={"PK": pk, "SK": "DEFINITION"}, + UpdateExpression="SET jwtRoleMappings = :m", + ExpressionAttributeValues={":m": existing_mappings}, + ) + + msg = "Added missing JWT_MAPPING#system_admin to existing system_admin role" + logger.info(msg) + result.created = 1 + result.details.append(msg) + except ClientError as e: + msg = f"Failed to add JWT mapping to existing system_admin role: {e}" + logger.error(msg) + result.failed = 1 + result.details.append(msg) return result except ClientError as e: msg = f"Failed to check existing system_admin role: {e}" @@ -510,7 +398,7 @@ def seed_system_admin_role( "roleId": role_id, "displayName": "System Administrator", "description": "Full access to all system features. This role cannot be deleted.", - "jwtRoleMappings": [], + "jwtRoleMappings": ["system_admin"], "inheritsFrom": [], "grantedTools": ["*"], "grantedModels": ["*"], @@ -547,6 +435,15 @@ def seed_system_admin_role( "enabled": True, } + jwt_mapping_item = { + "PK": pk, + "SK": "JWT_MAPPING#system_admin", + "GSI1PK": "JWT_ROLE#system_admin", + "GSI1SK": pk, + "roleId": role_id, + "enabled": True, + } + try: client = session.client("dynamodb") client.transact_write_items( @@ -554,10 +451,11 @@ def seed_system_admin_role( {"Put": {"TableName": table_name, "Item": _serialize(definition_item)}}, {"Put": {"TableName": table_name, "Item": _serialize(tool_grant_item)}}, {"Put": {"TableName": table_name, "Item": _serialize(model_grant_item)}}, + {"Put": {"TableName": table_name, "Item": _serialize(jwt_mapping_item)}}, ] ) result.created = 1 - result.details.append("system_admin role created with TOOL_GRANT#* and MODEL_GRANT#*") + result.details.append("system_admin role created with TOOL_GRANT#*, MODEL_GRANT#*, and JWT_MAPPING#system_admin") except ClientError as e: msg = f"Failed to create system_admin role: {e}" logger.error(msg) @@ -633,193 +531,6 @@ def seed_default_tools( return result -def seed_system_admin_jwt_roles( - table_name: str, - region: str, - jwt_role: str, -) -> SeedResult: - """Seed JWT role mapping for the system_admin AppRole. - - Writes a JWT_MAPPING item to the app-roles table so that - AppRoleService.resolve_user_permissions() can resolve users with the - given JWT role to the system_admin AppRole via the JwtRoleMappingIndex GSI. - - If the system_admin role definition does not yet exist, the full role - (DEFINITION + JWT_MAPPING + TOOL_GRANT + MODEL_GRANT items) is created. - If the role exists and already has the correct mapping, the operation is - skipped. If it exists with a different mapping, the old mapping items - are replaced. - """ - result = SeedResult(category="system_admin_jwt") - session = boto3.Session(region_name=region) - dynamodb = session.resource("dynamodb") - table = dynamodb.Table(table_name) - - role_id = "system_admin" - pk = f"ROLE#{role_id}" - now = datetime.now(timezone.utc).isoformat().replace("+00:00", "Z") - - # Check for existing role definition - try: - existing = table.get_item(Key={"PK": pk, "SK": "DEFINITION"}) - except ClientError as e: - msg = f"Failed to check existing system_admin role: {e}" - logger.error(msg) - result.failed = 1 - result.details.append(msg) - return result - - if "Item" in existing: - current_mappings = existing["Item"].get("jwtRoleMappings", []) - if jwt_role in current_mappings: - msg = f"system_admin already has JWT mapping '{jwt_role}' — skipped" - logger.info(msg) - result.skipped = 1 - result.details.append(msg) - return result - - # Update: replace old JWT mappings with new one - logger.info( - "Updating system_admin JWT mappings: %s -> ['%s']", - current_mappings, - jwt_role, - ) - - # Delete old JWT_MAPPING items - try: - query_resp = table.query( - KeyConditionExpression=( - boto3.dynamodb.conditions.Key("PK").eq(pk) - & boto3.dynamodb.conditions.Key("SK").begins_with("JWT_MAPPING#") - ), - ) - with table.batch_writer() as batch: - for item in query_resp.get("Items", []): - batch.delete_item(Key={"PK": item["PK"], "SK": item["SK"]}) - except ClientError as e: - msg = f"Failed to delete old JWT_MAPPING items: {e}" - logger.error(msg) - result.failed = 1 - result.details.append(msg) - return result - - # Update DEFINITION item's jwtRoleMappings - try: - table.update_item( - Key={"PK": pk, "SK": "DEFINITION"}, - UpdateExpression="SET jwtRoleMappings = :m, updatedAt = :u", - ExpressionAttributeValues={ - ":m": [jwt_role], - ":u": now, - }, - ) - except ClientError as e: - msg = f"Failed to update system_admin jwtRoleMappings: {e}" - logger.error(msg) - result.failed = 1 - result.details.append(msg) - return result - - # Write new JWT_MAPPING item - try: - table.put_item(Item={ - "PK": pk, - "SK": f"JWT_MAPPING#{jwt_role}", - "GSI1PK": f"JWT_ROLE#{jwt_role}", - "GSI1SK": pk, - "roleId": role_id, - "enabled": True, - }) - except ClientError as e: - msg = f"Failed to write JWT_MAPPING item for '{jwt_role}': {e}" - logger.error(msg) - result.failed = 1 - result.details.append(msg) - return result - - result.created = 1 - result.details.append( - f"system_admin JWT mapping updated to '{jwt_role}'" - ) - return result - - # Role does not exist — create full system_admin role - logger.info("system_admin role not found — creating with JWT mapping '%s'", jwt_role) - - definition_item: dict[str, Any] = { - "PK": pk, - "SK": "DEFINITION", - "roleId": role_id, - "displayName": "System Administrator", - "description": "Full access to all system features. This role cannot be deleted.", - "jwtRoleMappings": [jwt_role], - "inheritsFrom": [], - "grantedTools": ["*"], - "grantedModels": ["*"], - "effectivePermissions": { - "tools": ["*"], - "models": ["*"], - "quotaTier": None, - }, - "priority": 1000, - "isSystemRole": True, - "enabled": True, - "createdAt": now, - "updatedAt": now, - "createdBy": "bootstrap-seed", - } - - jwt_mapping_item = { - "PK": pk, - "SK": f"JWT_MAPPING#{jwt_role}", - "GSI1PK": f"JWT_ROLE#{jwt_role}", - "GSI1SK": pk, - "roleId": role_id, - "enabled": True, - } - - tool_grant_item = { - "PK": pk, - "SK": "TOOL_GRANT#*", - "GSI2PK": "TOOL#*", - "GSI2SK": pk, - "roleId": role_id, - "displayName": "System Administrator", - "enabled": True, - } - - model_grant_item = { - "PK": pk, - "SK": "MODEL_GRANT#*", - "GSI3PK": "MODEL#*", - "GSI3SK": pk, - "roleId": role_id, - "displayName": "System Administrator", - "enabled": True, - } - - try: - client = session.client("dynamodb") - client.transact_write_items( - TransactItems=[ - {"Put": {"TableName": table_name, "Item": _serialize(definition_item)}}, - {"Put": {"TableName": table_name, "Item": _serialize(jwt_mapping_item)}}, - {"Put": {"TableName": table_name, "Item": _serialize(tool_grant_item)}}, - {"Put": {"TableName": table_name, "Item": _serialize(model_grant_item)}}, - ] - ) - result.created = 1 - result.details.append( - f"system_admin role created with JWT mapping '{jwt_role}'" - ) - except ClientError as e: - msg = f"Failed to create system_admin role: {e}" - logger.error(msg) - result.failed = 1 - result.details.append(msg) - - return result - def _serialize(item: dict[str, Any]) -> dict[str, Any]: """Convert a high-level DynamoDB item dict to low-level client format.""" @@ -854,57 +565,13 @@ def print_summary(results: list[SeedResult]) -> None: def main() -> None: """Entry point: read env vars, dispatch seeders, print summary.""" # Required env vars for DynamoDB tables and region - auth_table = os.environ.get("DDB_AUTH_PROVIDERS_TABLE", "") quotas_table = os.environ.get("DDB_USER_QUOTAS_TABLE", "") models_table = os.environ.get("DDB_MANAGED_MODELS_TABLE", "") app_roles_table = os.environ.get("DDB_APP_ROLES_TABLE", "") - secrets_arn = os.environ.get("SECRETS_AUTH_ARN", "") region = os.environ.get("AWS_REGION", "us-east-1") - # Auth provider env vars (all optional — skip seeding if any missing) - auth_provider_id = os.environ.get("SEED_AUTH_PROVIDER_ID", "") - auth_display_name = os.environ.get("SEED_AUTH_DISPLAY_NAME", "") - auth_issuer_url = os.environ.get("SEED_AUTH_ISSUER_URL", "") - auth_client_id = os.environ.get("SEED_AUTH_CLIENT_ID", "") - auth_client_secret = os.environ.get("SEED_AUTH_CLIENT_SECRET", "") - auth_button_color = os.environ.get("SEED_AUTH_BUTTON_COLOR", "") or None - results: list[SeedResult] = [] - # --- Auth provider seeding --- - required_auth_var_names = [ - "SEED_AUTH_ISSUER_URL", - "SEED_AUTH_CLIENT_ID", - "SEED_AUTH_CLIENT_SECRET", - ] - missing_auth = [ - name for name in required_auth_var_names if not os.environ.get(name, "") - ] - - if missing_auth: - logger.warning( - "Skipping auth provider seeding — missing env vars: %s", - ", ".join(missing_auth), - ) - result = SeedResult(category="auth_provider", skipped=1) - result.details.append(f"Skipped — missing: {', '.join(missing_auth)}") - results.append(result) - else: - results.append( - seed_auth_provider( - table_name=auth_table, - secrets_arn=secrets_arn, - region=region, - provider_id=auth_provider_id or "default", - display_name=auth_display_name or "Default Provider", - issuer_url=auth_issuer_url, - client_id=auth_client_id, - client_secret=auth_client_secret, - button_color=auth_button_color, - discover=True, - ) - ) - # --- Quota tier seeding --- results.append(seed_default_quota_tier(table_name=quotas_table, region=region)) @@ -922,24 +589,6 @@ def main() -> None: # --- Tool seeding --- results.append(seed_default_tools(table_name=app_roles_table, region=region)) - # --- System admin JWT role seeding --- - admin_jwt_role = os.environ.get("SEED_ADMIN_JWT_ROLE", "") - if admin_jwt_role: - results.append( - seed_system_admin_jwt_roles( - table_name=app_roles_table, - region=region, - jwt_role=admin_jwt_role, - ) - ) - else: - logger.warning( - "Skipping system admin JWT role seeding — SEED_ADMIN_JWT_ROLE not set" - ) - r = SeedResult(category="system_admin_jwt", skipped=1) - r.details.append("Skipped — SEED_ADMIN_JWT_ROLE not set") - results.append(r) - # --- Summary --- print_summary(results) diff --git a/backend/src/agents/main_agent/quota/event_recorder.py b/backend/src/agents/main_agent/quota/event_recorder.py index 3e0a6f82..3ebb46c3 100644 --- a/backend/src/agents/main_agent/quota/event_recorder.py +++ b/backend/src/agents/main_agent/quota/event_recorder.py @@ -41,7 +41,7 @@ async def record_block( "tier_name": tier.tier_name, "session_id": session_id, "assignment_id": assignment_id, - "user_email": user.email, + "user_name": user.name, "user_roles": user.roles } ) @@ -95,7 +95,7 @@ async def record_warning_if_needed( "tier_name": tier.tier_name, "session_id": session_id, "assignment_id": assignment_id, - "user_email": user.email, + "user_name": user.name, "user_roles": user.roles } ) @@ -125,7 +125,7 @@ async def record_override_applied( metadata={ "override_id": override_id, "tier_name": tier.tier_name, - "user_email": user.email, + "user_name": user.name, "user_roles": user.roles } ) diff --git a/backend/src/agents/main_agent/session/tests/test_compaction.py b/backend/src/agents/main_agent/session/tests/test_compaction.py index 99e9d679..74036984 100644 --- a/backend/src/agents/main_agent/session/tests/test_compaction.py +++ b/backend/src/agents/main_agent/session/tests/test_compaction.py @@ -62,9 +62,9 @@ class TestCompactionConfig: def test_default_config(self): config = CompactionConfig() - assert config.enabled is False + assert config.enabled is True assert config.token_threshold == 100_000 - assert config.protected_turns == 2 + assert config.protected_turns == 3 assert config.max_tool_content_length == 500 def test_from_env(self, monkeypatch): diff --git a/backend/src/agents/main_agent/session/tests/test_compaction_integration.py b/backend/src/agents/main_agent/session/tests/test_compaction_integration.py index c99dc918..5421667b 100644 --- a/backend/src/agents/main_agent/session/tests/test_compaction_integration.py +++ b/backend/src/agents/main_agent/session/tests/test_compaction_integration.py @@ -18,6 +18,13 @@ """ import os +import pytest + +# Skip all tests in this module unless AWS integration env vars are set +pytestmark = pytest.mark.skipif( + not os.environ.get("AGENTCORE_MEMORY_ID"), + reason="Integration test requires AGENTCORE_MEMORY_ID environment variable" +) import sys import uuid import asyncio diff --git a/backend/src/apis/app_api/admin/README.md b/backend/src/apis/app_api/admin/README.md index 0c81998a..d33d21c2 100644 --- a/backend/src/apis/app_api/admin/README.md +++ b/backend/src/apis/app_api/admin/README.md @@ -10,7 +10,7 @@ The admin module demonstrates how to use the shared authentication RBAC utilitie ### JWT Role Extraction -Roles are automatically extracted from the JWT token by `GenericOIDCJWTValidator` (`apis/shared/auth/generic_jwt_validator.py`) and populated in the `User` model (`apis/shared/auth/models.py`). +Roles are automatically extracted from the JWT token by `CognitoJWTValidator` (`apis/shared/auth/cognito_jwt_validator.py`) and populated in the `User` model (`apis/shared/auth/models.py`). ### RBAC Dependencies @@ -298,7 +298,7 @@ Roles are configured in Entra ID (Azure AD) app registration: 3. Roles appear in the JWT token's `roles` claim 4. Backend validates and extracts roles automatically -See `apis/shared/auth/generic_jwt_validator.py` for role extraction logic. +See `apis/shared/auth/cognito_jwt_validator.py` for role extraction logic. ## Future Enhancements diff --git a/backend/src/apis/app_api/admin/auth_providers/routes.py b/backend/src/apis/app_api/admin/auth_providers/routes.py index c0e4aec6..7b51ac34 100644 --- a/backend/src/apis/app_api/admin/auth_providers/routes.py +++ b/backend/src/apis/app_api/admin/auth_providers/routes.py @@ -221,27 +221,6 @@ async def delete_auth_provider( ) -@router.post( - "/discover", - response_model=OIDCDiscoveryResponse, - summary="Discover OIDC endpoints", -) -async def discover_oidc_endpoints( - request: OIDCDiscoveryRequest, - admin_user: User = Depends(require_system_admin), -) -> OIDCDiscoveryResponse: - """ - Discover OIDC endpoints from an issuer URL. - - Fetches the .well-known/openid-configuration document and returns - the discovered endpoints, supported scopes, and claims. - """ - logger.info("Admin discovering OIDC endpoints") - - service = get_auth_provider_service() - return await service.discover_endpoints(request.issuer_url) - - @router.post( "/{provider_id}/test", summary="Test authentication provider connectivity", diff --git a/backend/src/apis/app_api/admin/routes.py b/backend/src/apis/app_api/admin/routes.py index 1fb82cd0..67de87d7 100644 --- a/backend/src/apis/app_api/admin/routes.py +++ b/backend/src/apis/app_api/admin/routes.py @@ -26,6 +26,8 @@ ManagedModel, ) from apis.shared.auth import User, require_admin +from apis.shared.sessions.metadata import list_user_sessions, get_session_metadata +from apis.shared.sessions.messages import get_messages from apis.shared.models.managed_models import ( create_managed_model, get_managed_model, diff --git a/backend/src/apis/app_api/auth/models.py b/backend/src/apis/app_api/auth/models.py deleted file mode 100644 index 38e5044e..00000000 --- a/backend/src/apis/app_api/auth/models.py +++ /dev/null @@ -1,66 +0,0 @@ -"""Authentication models.""" - -from dataclasses import dataclass -from typing import List, Optional -from pydantic import BaseModel, Field - - -@dataclass -class User: - """Authenticated user model.""" - email: str - empl_id: str - name: str - roles: List[str] - picture: Optional[str] = None - - -class TokenExchangeRequest(BaseModel): - """Request model for token exchange endpoint.""" - code: str = Field(..., description="Authorization code from the OIDC provider") - state: str = Field(..., description="State token for CSRF protection") - redirect_uri: Optional[str] = Field(None, description="Redirect URI (must match authorization request)") - - -class TokenExchangeResponse(BaseModel): - """Response model for token exchange endpoint.""" - access_token: str = Field(..., description="JWT access token") - refresh_token: Optional[str] = Field(None, description="Refresh token for obtaining new access tokens") - id_token: Optional[str] = Field(None, description="ID token containing user information") - token_type: str = Field(default="Bearer", description="Token type") - expires_in: int = Field(..., description="Access token expiration time in seconds") - scope: Optional[str] = Field(None, description="Token scopes") - - -class TokenRefreshRequest(BaseModel): - """Request model for token refresh endpoint.""" - refresh_token: str = Field(..., description="Refresh token from previous authentication") - - -class TokenRefreshResponse(BaseModel): - """Response model for token refresh endpoint.""" - access_token: str = Field(..., description="New JWT access token") - refresh_token: Optional[str] = Field(None, description="New refresh token (may be same as input)") - id_token: Optional[str] = Field(None, description="New ID token containing user information") - token_type: str = Field(default="Bearer", description="Token type") - expires_in: int = Field(..., description="Access token expiration time in seconds") - scope: Optional[str] = Field(None, description="Token scopes") - - -class LoginResponse(BaseModel): - """Response model for login endpoint.""" - authorization_url: str = Field(..., description="URL to redirect user to for authentication") - state: str = Field(..., description="State token for CSRF protection (should be validated on callback)") - - -class LogoutResponse(BaseModel): - """Response model for logout endpoint.""" - logout_url: str = Field(..., description="URL to redirect user to for OIDC provider logout") - - -class RuntimeEndpointResponse(BaseModel): - """Response model for runtime endpoint lookup.""" - runtime_endpoint_url: str = Field(..., description="AgentCore Runtime endpoint URL for the user's provider") - provider_id: str = Field(..., description="Auth provider ID") - runtime_status: str = Field(..., description="Runtime status (PENDING, CREATING, READY, UPDATING, FAILED)") - diff --git a/backend/src/apis/app_api/auth/routes.py b/backend/src/apis/app_api/auth/routes.py index 7fe3641d..e3e16fc1 100644 --- a/backend/src/apis/app_api/auth/routes.py +++ b/backend/src/apis/app_api/auth/routes.py @@ -1,27 +1,17 @@ -"""OIDC authentication routes with multi-provider support.""" +"""Authentication routes. + +Only exposes the public provider listing endpoint. All authentication +flows go through Cognito directly (frontend → Cognito → IdP → Cognito → frontend). +""" import logging -import os -from typing import Optional -from fastapi import APIRouter, Depends, HTTPException, Query, Request, status +from fastapi import APIRouter -from .models import ( - LoginResponse, - LogoutResponse, - RuntimeEndpointResponse, - TokenExchangeRequest, - TokenExchangeResponse, - TokenRefreshRequest, - TokenRefreshResponse, -) -from .service import get_generic_auth_service from apis.shared.auth_providers.models import ( AuthProviderPublicInfo, AuthProviderPublicListResponse, ) -from apis.shared.auth.dependencies import get_current_user -from apis.shared.auth.models import User logger = logging.getLogger(__name__) @@ -62,351 +52,3 @@ async def list_auth_providers() -> AuthProviderPublicListResponse: except Exception as e: logger.debug(f"Error listing auth providers (may not be configured): {e}") return AuthProviderPublicListResponse(providers=[]) - - -@router.get( - "/login", - response_model=LoginResponse, - summary="Initiate OIDC login", -) -async def login( - request: Request, - provider_id: str = Query(..., description="Auth provider ID"), - redirect_uri: str = Query(None, description="Optional redirect URI override"), - prompt: str = Query("select_account", description="Prompt type (select_account, login, consent)") -) -> LoginResponse: - """ - Generate authorization URL for OIDC login. - - Requires a provider_id that references an enabled auth provider - configured via the admin OIDC provider setup. - - When no redirect_uri is configured (neither in the query param nor on the - provider), one is auto-derived from the request's Origin or Referer header - by appending /auth/callback. - """ - try: - auth_service = await get_generic_auth_service(provider_id) - - # Auto-derive redirect_uri from request origin when not configured - effective_redirect_uri = redirect_uri - if not effective_redirect_uri and not auth_service.redirect_uri: - origin = request.headers.get("origin") or request.headers.get("referer") - if origin: - # Strip path from referer to get just the origin - from urllib.parse import urlparse - parsed = urlparse(origin) - base = f"{parsed.scheme}://{parsed.netloc}" - effective_redirect_uri = f"{base}/auth/callback" - logger.info(f"Auto-derived redirect_uri from request origin: {effective_redirect_uri}") - - state, code_challenge, nonce = auth_service.generate_state(redirect_uri=effective_redirect_uri) - - authorization_url = auth_service.build_authorization_url( - state=state, - code_challenge=code_challenge, - nonce=nonce, - redirect_uri=effective_redirect_uri, - prompt=prompt - ) - - logger.info("Generated authorization URL for OIDC login") - - return LoginResponse( - authorization_url=authorization_url, - state=state - ) - - except ValueError as e: - logger.error(f"Authentication not configured: {e}") - raise HTTPException( - status_code=status.HTTP_503_SERVICE_UNAVAILABLE, - detail=str(e) - ) - except HTTPException: - raise - except Exception as e: - logger.error(f"Error generating authorization URL: {e}", exc_info=True) - raise HTTPException( - status_code=status.HTTP_500_INTERNAL_SERVER_ERROR, - detail="Failed to generate authorization URL" - ) - - -@router.post( - "/token", - response_model=TokenExchangeResponse, - status_code=status.HTTP_200_OK, - summary="Exchange authorization code for tokens", -) -async def exchange_token(request: TokenExchangeRequest) -> TokenExchangeResponse: - """ - Exchange authorization code for access and refresh tokens. - - Resolves the auth provider from the stored state's provider_id. - """ - try: - # Peek at the state to determine provider (without consuming it) - # The actual state validation/consumption happens inside exchange_code_for_tokens - provider_id = _peek_provider_from_state(request.state) - - if not provider_id: - raise HTTPException( - status_code=status.HTTP_400_BAD_REQUEST, - detail="Could not resolve auth provider from state. Please initiate login again." - ) - - auth_service = await get_generic_auth_service(provider_id) - - tokens = await auth_service.exchange_code_for_tokens( - code=request.code, - state=request.state, - redirect_uri=request.redirect_uri - ) - - return TokenExchangeResponse(**tokens) - except ValueError as e: - logger.error(f"Authentication not configured: {e}") - raise HTTPException( - status_code=status.HTTP_503_SERVICE_UNAVAILABLE, - detail=str(e) - ) - except HTTPException: - raise - except Exception as e: - logger.error(f"Error exchanging token: {e}", exc_info=True) - raise HTTPException( - status_code=status.HTTP_400_BAD_REQUEST, - detail="Token exchange failed." - ) - - -@router.post( - "/refresh", - response_model=TokenRefreshResponse, - status_code=status.HTTP_200_OK, - summary="Refresh access token", -) -async def refresh_token( - request: TokenRefreshRequest, - provider_id: str = Query(..., description="Auth provider ID"), -) -> TokenRefreshResponse: - """ - Refresh access token using refresh token. - - Requires a provider_id to route to the correct provider's token endpoint. - """ - try: - auth_service = await get_generic_auth_service(provider_id) - - tokens = await auth_service.refresh_access_token(request.refresh_token) - - return TokenRefreshResponse(**tokens) - except ValueError as e: - logger.error(f"Authentication not configured: {e}") - raise HTTPException( - status_code=status.HTTP_503_SERVICE_UNAVAILABLE, - detail=str(e) - ) - except HTTPException: - raise - except Exception as e: - logger.error(f"Error refreshing token: {e}", exc_info=True) - raise HTTPException( - status_code=status.HTTP_400_BAD_REQUEST, - detail="Token refresh failed." - ) - - -@router.get( - "/logout", - response_model=LogoutResponse, - summary="Get logout URL", -) -async def logout( - provider_id: str = Query(..., description="Auth provider ID"), - post_logout_redirect_uri: str = Query( - None, - description="URL to redirect to after logout" - ) -) -> LogoutResponse: - """ - Get logout URL for ending the user's session. - - Requires a provider_id to return the correct provider's end session URL. - """ - try: - auth_service = await get_generic_auth_service(provider_id) - - logout_url = auth_service.build_logout_url( - post_logout_redirect_uri=post_logout_redirect_uri - ) - - logger.info("Generated logout URL") - - return LogoutResponse(logout_url=logout_url) - - except ValueError as e: - logger.error(f"Authentication not configured: {e}") - raise HTTPException( - status_code=status.HTTP_503_SERVICE_UNAVAILABLE, - detail=str(e) - ) - except HTTPException: - raise - except Exception as e: - logger.error(f"Error generating logout URL: {e}", exc_info=True) - raise HTTPException( - status_code=status.HTTP_500_INTERNAL_SERVER_ERROR, - detail="Failed to generate logout URL" - ) - - -def _peek_provider_from_state(state: str) -> Optional[str]: - """ - Peek at the OIDC state to determine which provider initiated the flow. - - This reads the state from the store WITHOUT consuming it. The actual - consumption happens inside the auth service's exchange_code_for_tokens. - - For the in-memory store we inspect the internal dict directly. - For DynamoDB we do a GetItem without the atomic delete. - """ - try: - from apis.shared.auth.state_store import create_state_store - - store = create_state_store() - - # For InMemoryStateStore, peek at the internal dict - if hasattr(store, '_store'): - entry = store._store.get(state) - if entry: - _, data = entry - return data.provider_id if data else None - return None - - # For DynamoDBStateStore, do a non-destructive read - if hasattr(store, 'table'): - import time - response = store.table.get_item( - Key={ - 'PK': f'STATE#{state}', - 'SK': f'STATE#{state}', - }, - ConsistentRead=True, - ) - item = response.get('Item') - if item: - expires_at = item.get('expiresAt', 0) - if int(time.time()) <= expires_at: - return item.get('provider_id') - return None - - except Exception as e: - logger.debug(f"Could not peek provider from state: {e}") - - return None - - -# Redefine the endpoint with proper dependency injection -@router.get( - "/runtime-endpoint", - response_model=RuntimeEndpointResponse, - summary="Get AgentCore Runtime endpoint URL for user's provider", -) -async def get_runtime_endpoint_impl( - current_user: User = Depends(get_current_user) -) -> RuntimeEndpointResponse: - """ - Get the AgentCore Runtime endpoint URL for the authenticated user's auth provider. - - This endpoint requires authentication. The provider ID is extracted from the - user's JWT token by resolving the issuer to a configured auth provider. - - Returns: - RuntimeEndpointResponse with the runtime endpoint URL and status - - Raises: - HTTPException: - - 401 if not authenticated - - 404 if provider not found or runtime not ready - - 500 if runtime endpoint not configured - """ - from apis.shared.auth.generic_jwt_validator import GenericOIDCJWTValidator - from apis.shared.auth_providers.repository import get_auth_provider_repository - - try: - repo = get_auth_provider_repository() - if not repo.enabled: - raise HTTPException( - status_code=status.HTTP_500_INTERNAL_SERVER_ERROR, - detail="Auth provider repository not configured" - ) - - validator = GenericOIDCJWTValidator(repo) - - # Get the raw token from the user object - token = getattr(current_user, 'raw_token', None) - if not token: - raise HTTPException( - status_code=status.HTTP_401_UNAUTHORIZED, - detail="Token not available" - ) - - # Resolve provider from token - provider = await validator.resolve_provider_from_token(token) - if not provider: - raise HTTPException( - status_code=status.HTTP_404_NOT_FOUND, - detail="Auth provider not found for this token" - ) - - # Check if runtime endpoint is configured - if not provider.agentcore_runtime_endpoint_url: - if provider.agentcore_runtime_status == "PENDING": - raise HTTPException( - status_code=status.HTTP_404_NOT_FOUND, - detail=f"Runtime is being provisioned for provider '{provider.provider_id}'. Please try again in a few minutes." - ) - elif provider.agentcore_runtime_status == "CREATING": - raise HTTPException( - status_code=status.HTTP_404_NOT_FOUND, - detail=f"Runtime is currently being created for provider '{provider.provider_id}'. Please try again in a few minutes." - ) - elif provider.agentcore_runtime_status == "FAILED": - error_msg = provider.agentcore_runtime_error or "Unknown error" - raise HTTPException( - status_code=status.HTTP_500_INTERNAL_SERVER_ERROR, - detail=f"Runtime provisioning failed for provider '{provider.provider_id}': {error_msg}" - ) - else: - raise HTTPException( - status_code=status.HTTP_404_NOT_FOUND, - detail=f"Runtime endpoint not configured for provider '{provider.provider_id}'" - ) - - logger.info( - f"Resolved runtime endpoint for user {current_user.user_id} " - f"(provider: {provider.provider_id}): {provider.agentcore_runtime_endpoint_url}" - ) - - # Allow local override for development (bypass cloud runtime) - runtime_url = os.environ.get( - "LOCAL_RUNTIME_ENDPOINT_URL", - provider.agentcore_runtime_endpoint_url, - ) - - return RuntimeEndpointResponse( - runtime_endpoint_url=runtime_url, - provider_id=provider.provider_id, - runtime_status=provider.agentcore_runtime_status, - ) - - except HTTPException: - raise - except Exception as e: - logger.error(f"Error resolving runtime endpoint: {e}", exc_info=True) - raise HTTPException( - status_code=status.HTTP_500_INTERNAL_SERVER_ERROR, - detail="Failed to resolve runtime endpoint" - ) diff --git a/backend/src/apis/app_api/auth/service.py b/backend/src/apis/app_api/auth/service.py deleted file mode 100644 index 7f811d37..00000000 --- a/backend/src/apis/app_api/auth/service.py +++ /dev/null @@ -1,320 +0,0 @@ -"""OIDC authentication service with multi-provider support.""" - -import base64 -import hashlib -import logging -import secrets -from typing import Any, Dict, Optional, Tuple -from urllib.parse import urlencode - -import httpx -from fastapi import HTTPException, status - -from apis.shared.auth.state_store import OIDCStateData, create_state_store - -logger = logging.getLogger(__name__) - - -def generate_pkce_pair() -> Tuple[str, str]: - """ - Generate PKCE code verifier and challenge (S256). - - Returns: - Tuple of (code_verifier, code_challenge) - """ - # Generate 32 bytes of random data for code_verifier (43-128 chars when base64 encoded) - code_verifier = secrets.token_urlsafe(32) - - # Create code_challenge using S256: BASE64URL(SHA256(code_verifier)) - digest = hashlib.sha256(code_verifier.encode('ascii')).digest() - code_challenge = base64.urlsafe_b64encode(digest).rstrip(b'=').decode('ascii') - - return code_verifier, code_challenge - - -class GenericOIDCAuthService: - """Provider-agnostic OIDC auth service for dynamically configured providers.""" - - def __init__(self, provider, client_secret: str, state_store): - """ - Initialize with a specific auth provider configuration. - - Args: - provider: AuthProvider from the database - client_secret: Client secret from Secrets Manager - state_store: StateStore instance for OIDC state management - """ - self.provider = provider - self.client_secret = client_secret - self.client_id = provider.client_id - self.authorization_endpoint = provider.authorization_endpoint - self.token_endpoint = provider.token_endpoint - self.logout_endpoint = provider.end_session_endpoint - self.scope = provider.scopes - self.redirect_uri = provider.redirect_uri - self.pkce_enabled = provider.pkce_enabled - self.state_store = state_store - self._state_ttl = 600 - - def generate_state( - self, - redirect_uri: Optional[str] = None - ) -> Tuple[str, str, str]: - """Generate secure state token, PKCE challenge, and nonce. - - Stores the state in the state store with the provider_id, - code_verifier (if PKCE enabled), nonce, and optional redirect_uri. - - Returns: - Tuple of (state, code_challenge, nonce) - """ - state = secrets.token_urlsafe(32) - code_verifier, code_challenge = generate_pkce_pair() - nonce = secrets.token_urlsafe(32) - - self.state_store.store_state( - state=state, - data=OIDCStateData( - redirect_uri=redirect_uri, - code_verifier=code_verifier if self.pkce_enabled else None, - nonce=nonce, - provider_id=self.provider.provider_id, - ), - ttl_seconds=self._state_ttl - ) - return state, code_challenge, nonce - - def validate_state(self, state: str) -> Tuple[bool, Optional[OIDCStateData]]: - """Validate state token and return associated OIDC data.""" - return self.state_store.get_and_delete_state(state) - - def build_authorization_url( - self, - state: str, - code_challenge: str, - nonce: str, - redirect_uri: Optional[str] = None, - prompt: str = "select_account" - ) -> str: - """Build authorization URL with PKCE and nonce.""" - redirect = redirect_uri or self.redirect_uri - - params = { - "client_id": self.client_id, - "response_type": "code", - "redirect_uri": redirect, - "response_mode": "query", - "scope": self.scope, - "state": state, - "nonce": nonce, - "prompt": prompt, - } - - if self.pkce_enabled: - params["code_challenge"] = code_challenge - params["code_challenge_method"] = "S256" - - return f"{self.authorization_endpoint}?{urlencode(params)}" - - async def exchange_code_for_tokens( - self, - code: str, - state: str, - redirect_uri: Optional[str] = None - ) -> Dict[str, Any]: - """Exchange authorization code for tokens. - - Validates the state parameter, sends the code to the token endpoint, - verifies the nonce in the ID token if present, and returns the token dict. - - Raises: - HTTPException(400): If state is invalid/expired or nonce mismatch. - HTTPException(503): If the token endpoint is unreachable. - """ - is_valid, state_data = self.validate_state(state) - if not is_valid or state_data is None: - raise HTTPException( - status_code=status.HTTP_400_BAD_REQUEST, - detail="Invalid or expired state parameter. Please initiate login again." - ) - - redirect = state_data.redirect_uri or redirect_uri or self.redirect_uri - - token_data = { - "client_id": self.client_id, - "client_secret": self.client_secret, - "code": code, - "grant_type": "authorization_code", - "redirect_uri": redirect, - "scope": self.scope, - } - - if self.pkce_enabled and state_data.code_verifier: - token_data["code_verifier"] = state_data.code_verifier - - try: - async with httpx.AsyncClient() as client: - response = await client.post( - self.token_endpoint, - data=token_data, - headers={"Content-Type": "application/x-www-form-urlencoded"}, - timeout=10.0 - ) - response.raise_for_status() - token_response = response.json() - - # Validate nonce in ID token if present - id_token = token_response.get("id_token") - if id_token and state_data.nonce: - import jwt - try: - id_claims = jwt.decode(id_token, options={"verify_signature": False}) - token_nonce = id_claims.get("nonce") - if token_nonce != state_data.nonce: - raise HTTPException( - status_code=status.HTTP_400_BAD_REQUEST, - detail="ID token nonce validation failed." - ) - except jwt.DecodeError: - raise HTTPException( - status_code=status.HTTP_400_BAD_REQUEST, - detail="Invalid ID token received." - ) - - return { - "access_token": token_response.get("access_token"), - "refresh_token": token_response.get("refresh_token"), - "id_token": token_response.get("id_token"), - "token_type": token_response.get("token_type", "Bearer"), - "expires_in": token_response.get("expires_in", 3600), - "scope": token_response.get("scope", ""), - "provider_id": self.provider.provider_id, - } - - except httpx.HTTPStatusError as e: - logger.error(f"Token exchange failed for provider {self.provider.provider_id}: {e.response.status_code}") - raise HTTPException( - status_code=status.HTTP_400_BAD_REQUEST, - detail="Failed to exchange authorization code for tokens." - ) - except httpx.RequestError as e: - logger.error(f"Token exchange request failed for provider {self.provider.provider_id}: {e}") - raise HTTPException( - status_code=status.HTTP_503_SERVICE_UNAVAILABLE, - detail="Authentication service unavailable." - ) - - async def refresh_access_token(self, refresh_token: str) -> Dict[str, Any]: - """Refresh access token using a refresh token. - - Raises: - HTTPException(401): If the token endpoint returns 400 (expired/invalid refresh token). - HTTPException(503): If the token endpoint is unreachable. - """ - token_data = { - "client_id": self.client_id, - "client_secret": self.client_secret, - "refresh_token": refresh_token, - "grant_type": "refresh_token", - "scope": self.scope, - } - - try: - async with httpx.AsyncClient() as client: - response = await client.post( - self.token_endpoint, - data=token_data, - headers={"Content-Type": "application/x-www-form-urlencoded"}, - timeout=10.0 - ) - response.raise_for_status() - token_response = response.json() - - return { - "access_token": token_response.get("access_token"), - "refresh_token": token_response.get("refresh_token") or refresh_token, - "id_token": token_response.get("id_token"), - "token_type": token_response.get("token_type", "Bearer"), - "expires_in": token_response.get("expires_in", 3600), - "scope": token_response.get("scope", ""), - "provider_id": self.provider.provider_id, - } - - except httpx.HTTPStatusError as e: - if e.response.status_code == 400: - raise HTTPException( - status_code=status.HTTP_401_UNAUTHORIZED, - detail="Invalid or expired refresh token. Please login again." - ) - raise HTTPException( - status_code=status.HTTP_400_BAD_REQUEST, - detail="Failed to refresh access token." - ) - except httpx.RequestError: - raise HTTPException( - status_code=status.HTTP_503_SERVICE_UNAVAILABLE, - detail="Authentication service unavailable." - ) - - def build_logout_url(self, post_logout_redirect_uri: Optional[str] = None) -> str: - """Build logout URL for the provider. - - Returns an empty string if no end_session_endpoint is configured. - """ - if not self.logout_endpoint: - return "" - - params = {} - if post_logout_redirect_uri: - params["post_logout_redirect_uri"] = post_logout_redirect_uri - - if params: - return f"{self.logout_endpoint}?{urlencode(params)}" - return self.logout_endpoint - - -async def get_generic_auth_service(provider_id: str) -> GenericOIDCAuthService: - """ - Create a GenericOIDCAuthService for a specific auth provider. - - Args: - provider_id: The auth provider ID to create the service for - - Returns: - GenericOIDCAuthService configured for the provider - - Raises: - HTTPException: If provider not found or not enabled - """ - from apis.shared.auth_providers.service import get_auth_provider_service - - service = get_auth_provider_service() - provider = await service.get_provider(provider_id) - - if not provider: - raise HTTPException( - status_code=status.HTTP_400_BAD_REQUEST, - detail=f"Authentication provider '{provider_id}' not found." - ) - - if not provider.enabled: - raise HTTPException( - status_code=status.HTTP_400_BAD_REQUEST, - detail=f"Authentication provider '{provider_id}' is not enabled." - ) - - client_secret = await service.get_client_secret(provider_id) - if not client_secret: - raise HTTPException( - status_code=status.HTTP_500_INTERNAL_SERVER_ERROR, - detail=f"Client secret not configured for provider '{provider_id}'." - ) - - state_store = create_state_store() - - return GenericOIDCAuthService( - provider=provider, - client_secret=client_secret, - state_store=state_store, - ) - diff --git a/backend/src/apis/app_api/files/routes.py b/backend/src/apis/app_api/files/routes.py index f7e9fa54..3a3b9aab 100644 --- a/backend/src/apis/app_api/files/routes.py +++ b/backend/src/apis/app_api/files/routes.py @@ -63,7 +63,7 @@ async def request_presigned_url( - User storage quota: 1GB """ logger.info( - f"User {user.email} requesting presigned URL for {request.filename} " + f"User {user.name} requesting presigned URL for {request.filename} " f"({request.size_bytes} bytes)" ) @@ -72,7 +72,7 @@ async def request_presigned_url( return response except InvalidFileTypeError as e: - logger.warning(f"Invalid file type from user {user.email}: {e.mime_type}") + logger.warning(f"Invalid file type from user {user.name}: {e.mime_type}") allowed = ", ".join(ALLOWED_MIME_TYPES.values()) raise HTTPException( status_code=status.HTTP_400_BAD_REQUEST, @@ -81,7 +81,7 @@ async def request_presigned_url( except FileTooLargeError as e: logger.warning( - f"File too large from user {user.email}: " + f"File too large from user {user.name}: " f"{e.size_bytes} > {e.max_size}" ) raise HTTPException( @@ -91,7 +91,7 @@ async def request_presigned_url( except QuotaExceededError as e: logger.warning( - f"Quota exceeded for user {user.email}: " + f"Quota exceeded for user {user.name}: " f"{e.current_usage}/{e.max_allowed}" ) raise HTTPException( diff --git a/backend/src/apis/app_api/main.py b/backend/src/apis/app_api/main.py index a533c6cd..0c16aef8 100644 --- a/backend/src/apis/app_api/main.py +++ b/backend/src/apis/app_api/main.py @@ -45,15 +45,6 @@ async def lifespan(app: FastAPI): os.makedirs(generated_images_dir, exist_ok=True) logger.info("Output directories ready") - # Seed system roles for RBAC - try: - from apis.shared.rbac import ensure_system_roles - await ensure_system_roles() - logger.info("RBAC system roles initialized") - except Exception as e: - logger.warning(f"Failed to seed RBAC system roles: {e}") - # Don't fail startup - roles can be seeded later - yield # Application is running # Shutdown @@ -68,29 +59,15 @@ async def lifespan(app: FastAPI): lifespan=lifespan ) -# Add CORS middleware -# CORS origins are automatically configured based on FRONTEND_URL environment variable -allowed_origins = [] - -# Read frontend URL from environment variable (set by CDK based on frontend.domainName) -frontend_url = os.getenv('FRONTEND_URL', '') -if frontend_url: - allowed_origins.append(frontend_url) - logger.info(f"CORS: Added frontend origin: {frontend_url}") - -# Fallback: Add localhost for local development if no frontend URL configured -if not allowed_origins: - allowed_origins.append("http://localhost:4200") - logger.info("CORS: Added local development origin (fallback)") - -if allowed_origins: - app.add_middleware( - CORSMiddleware, - allow_origins=allowed_origins, - allow_credentials=True, - allow_methods=["*"], - allow_headers=["*"], - ) +# Add CORS middleware - origins from CDK-provided CORS_ORIGINS env var +_cors_origins = os.environ.get("CORS_ORIGINS", "").split(",") +app.add_middleware( + CORSMiddleware, + allow_origins=[o.strip() for o in _cors_origins if o.strip()], + allow_credentials=False, + allow_methods=["*"], + allow_headers=["*"], +) # Import routers @@ -111,6 +88,7 @@ async def lifespan(app: FastAPI): from apis.app_api.users.routes import router as users_router from apis.app_api.user_settings.routes import router as user_settings_router from apis.shared.oauth.routes import router as oauth_router +from apis.app_api.system.routes import router as system_router from apis.app_api.shares.routes import conversations_share_router, shares_router, shared_view_router # Include routers @@ -131,6 +109,7 @@ async def lifespan(app: FastAPI): app.include_router(tools_router) # Tool discovery and permissions app.include_router(files_router) # File upload via pre-signed URLs app.include_router(oauth_router) # OAuth provider connections +app.include_router(system_router) # System status and first-boot endpoints app.include_router(conversations_share_router) # Share conversations endpoints app.include_router(shares_router) # Share management (update, revoke, export) app.include_router(shared_view_router) # Shared conversation read-only view diff --git a/backend/src/apis/app_api/models/routes.py b/backend/src/apis/app_api/models/routes.py index e62fb595..b0685c51 100644 --- a/backend/src/apis/app_api/models/routes.py +++ b/backend/src/apis/app_api/models/routes.py @@ -54,7 +54,7 @@ async def list_models_for_user( - 500 if server error """ logger.info( - f"User {current_user.email} requesting available models " + f"User {current_user.name} requesting available models " f"(roles: {current_user.roles})" ) @@ -69,7 +69,7 @@ async def list_models_for_user( logger.info( f"✅ Found {len(accessible_models)} models available to user " - f"{current_user.email} (out of {len(all_models)} total)" + f"{current_user.name} (out of {len(all_models)} total)" ) # Convert ManagedModel instances to dicts for Pydantic v2 validation diff --git a/backend/src/apis/app_api/sessions/tests/test_cache_savings.py b/backend/src/apis/app_api/sessions/tests/test_cache_savings.py index 519084db..dcb8b16d 100644 --- a/backend/src/apis/app_api/sessions/tests/test_cache_savings.py +++ b/backend/src/apis/app_api/sessions/tests/test_cache_savings.py @@ -73,7 +73,7 @@ def sample_message_metadata(self, sample_token_usage_with_cache, sample_model_in async def test_cache_savings_calculation(self, mock_storage, sample_message_metadata): """Test that cache savings are calculated correctly""" with patch( - 'apis.app_api.storage.metadata_storage.get_metadata_storage', + 'apis.app_api.storage.get_metadata_storage', return_value=mock_storage ): from apis.app_api.sessions.services.metadata import _update_cost_summary_async @@ -138,7 +138,7 @@ async def test_cache_savings_zero_when_no_cache_reads(self, mock_storage): ) with patch( - 'apis.app_api.storage.metadata_storage.get_metadata_storage', + 'apis.app_api.storage.get_metadata_storage', return_value=mock_storage ): from apis.app_api.sessions.services.metadata import _update_cost_summary_async @@ -180,7 +180,7 @@ async def test_cache_savings_zero_when_no_pricing_snapshot(self, mock_storage): ) with patch( - 'apis.app_api.storage.metadata_storage.get_metadata_storage', + 'apis.app_api.storage.get_metadata_storage', return_value=mock_storage ): from apis.app_api.sessions.services.metadata import _update_cost_summary_async @@ -230,7 +230,7 @@ async def test_cache_savings_large_cache_hit(self, mock_storage): ) with patch( - 'apis.app_api.storage.metadata_storage.get_metadata_storage', + 'apis.app_api.storage.get_metadata_storage', return_value=mock_storage ): from apis.app_api.sessions.services.metadata import _update_cost_summary_async @@ -287,7 +287,7 @@ async def test_cache_savings_with_haiku_pricing(self, mock_storage): ) with patch( - 'apis.app_api.storage.metadata_storage.get_metadata_storage', + 'apis.app_api.storage.get_metadata_storage', return_value=mock_storage ): from apis.app_api.sessions.services.metadata import _update_cost_summary_async diff --git a/backend/src/apis/app_api/system/__init__.py b/backend/src/apis/app_api/system/__init__.py new file mode 100644 index 00000000..c0e95a02 --- /dev/null +++ b/backend/src/apis/app_api/system/__init__.py @@ -0,0 +1,17 @@ +"""System settings module for first-boot and system status.""" + +from .cognito_service import CognitoService, get_cognito_service +from .models import FirstBootRequest, FirstBootResponse, SystemStatusResponse +from .repository import SystemSettingsRepository, get_system_settings_repository +from .routes import router + +__all__ = [ + "CognitoService", + "FirstBootRequest", + "FirstBootResponse", + "SystemStatusResponse", + "SystemSettingsRepository", + "get_cognito_service", + "get_system_settings_repository", + "router", +] diff --git a/backend/src/apis/app_api/system/cognito_service.py b/backend/src/apis/app_api/system/cognito_service.py new file mode 100644 index 00000000..bacb5841 --- /dev/null +++ b/backend/src/apis/app_api/system/cognito_service.py @@ -0,0 +1,193 @@ +"""Cognito service for first-boot user creation and pool management.""" + +import logging +import os +from typing import Optional + +import boto3 +from botocore.exceptions import ClientError + +logger = logging.getLogger(__name__) + + +class CognitoService: + """Encapsulates Cognito Admin API operations for first-boot flow.""" + + def __init__( + self, + user_pool_id: Optional[str] = None, + region: Optional[str] = None, + ): + self._user_pool_id = user_pool_id or os.getenv("COGNITO_USER_POOL_ID") + self._region = region or os.getenv("AWS_REGION", "us-west-2") + self._enabled = bool(self._user_pool_id) + + if not self._enabled: + logger.warning( + "COGNITO_USER_POOL_ID not set. Cognito service is disabled." + ) + return + + profile = os.getenv("AWS_PROFILE") + if profile: + session = boto3.Session(profile_name=profile) + self._client = session.client( + "cognito-idp", region_name=self._region + ) + else: + self._client = boto3.client( + "cognito-idp", region_name=self._region + ) + + logger.info( + f"Initialized Cognito service: pool={self._user_pool_id}" + ) + + @property + def enabled(self) -> bool: + return self._enabled + + @property + def user_pool_id(self) -> Optional[str]: + return self._user_pool_id + + def create_admin_user( + self, username: str, email: str, password: str + ) -> str: + """ + Create a user in Cognito and set a permanent password. + + Uses AdminCreateUser with MessageAction=SUPPRESS to skip the + welcome email, then AdminSetUserPassword with Permanent=True + to bypass the forced password change on first login. + + Args: + username: The desired username. + email: The user's email address. + password: The permanent password. + + Returns: + The Cognito user ``sub`` (unique user ID). + + Raises: + ClientError: On Cognito API failures (e.g. + ``InvalidPasswordException``, ``UsernameExistsException``). + """ + if not self._enabled: + raise RuntimeError("Cognito service is not enabled") + + # Step 1: Create user with a temporary password (suppressed invite) + response = self._client.admin_create_user( + UserPoolId=self._user_pool_id, + Username=username, + UserAttributes=[ + {"Name": "email", "Value": email}, + {"Name": "email_verified", "Value": "true"}, + ], + MessageAction="SUPPRESS", + ) + + # Extract the sub from the created user attributes + user_sub = "" + for attr in response["User"]["Attributes"]: + if attr["Name"] == "sub": + user_sub = attr["Value"] + break + + # Step 2: Set permanent password (skips FORCE_CHANGE_PASSWORD) + self._client.admin_set_user_password( + UserPoolId=self._user_pool_id, + Username=username, + Password=password, + Permanent=True, + ) + + logger.info("Created Cognito admin user successfully") + return user_sub + + def delete_user(self, username: str) -> None: + """ + Delete a user from Cognito. Used for rollback on failure. + + Args: + username: The Cognito username to delete. + """ + if not self._enabled: + return + + try: + self._client.admin_delete_user( + UserPoolId=self._user_pool_id, + Username=username, + ) + logger.info(f"Deleted Cognito user (rollback): {username}") + except ClientError: + logger.exception( + f"Failed to delete Cognito user during rollback: {username}" + ) + + def add_user_to_group(self, username: str, group_name: str) -> None: + """ + Add a user to a Cognito User Pool group, creating the group if needed. + + The group membership causes Cognito to include the group name in the + ``cognito:groups`` claim of the JWT token, which the RBAC system uses + to resolve AppRole permissions. + + Args: + username: The Cognito username. + group_name: The group to add the user to. + """ + if not self._enabled: + return + + # Ensure the group exists (idempotent) + try: + self._client.create_group( + GroupName=group_name, + UserPoolId=self._user_pool_id, + Description=f"Auto-created group for {group_name} role", + ) + logger.info(f"Created Cognito group: {group_name}") + except ClientError as e: + if e.response["Error"]["Code"] != "GroupExistsException": + raise + # Group already exists — fine + + self._client.admin_add_user_to_group( + UserPoolId=self._user_pool_id, + Username=username, + GroupName=group_name, + ) + logger.info(f"Added user {username} to Cognito group: {group_name}") + + def disable_self_signup(self) -> None: + """ + Disable self-signup on the User Pool by setting + AllowAdminCreateUserOnly=true. + + Only updates AdminCreateUserConfig; the existing password policy + (configured by CDK) is preserved. + """ + if not self._enabled: + raise RuntimeError("Cognito service is not enabled") + + self._client.update_user_pool( + UserPoolId=self._user_pool_id, + AdminCreateUserConfig={ + "AllowAdminCreateUserOnly": True, + }, + ) + logger.info("Disabled self-signup on Cognito User Pool") + + +# Singleton instance +_cognito_service: Optional[CognitoService] = None + + +def get_cognito_service() -> CognitoService: + """Get the Cognito service singleton.""" + global _cognito_service + if _cognito_service is None: + _cognito_service = CognitoService() + return _cognito_service diff --git a/backend/src/apis/app_api/system/models.py b/backend/src/apis/app_api/system/models.py new file mode 100644 index 00000000..801a2b95 --- /dev/null +++ b/backend/src/apis/app_api/system/models.py @@ -0,0 +1,25 @@ +"""Pydantic models for system settings and first-boot flow.""" + +from pydantic import BaseModel, Field + + +class FirstBootRequest(BaseModel): + """Request body for the first-boot admin registration endpoint.""" + + username: str = Field(..., min_length=3, max_length=128) + email: str = Field(..., pattern=r"^[^@]+@[^@]+\.[^@]+$") + password: str = Field(..., min_length=8) + + +class FirstBootResponse(BaseModel): + """Response body for a successful first-boot registration.""" + + success: bool + user_id: str + message: str + + +class SystemStatusResponse(BaseModel): + """Response body for the system status endpoint.""" + + first_boot_completed: bool diff --git a/backend/src/apis/app_api/system/repository.py b/backend/src/apis/app_api/system/repository.py new file mode 100644 index 00000000..629d61a7 --- /dev/null +++ b/backend/src/apis/app_api/system/repository.py @@ -0,0 +1,130 @@ +"""DynamoDB repository for system settings (first-boot state).""" + +import logging +import os +from datetime import datetime, timezone +from typing import Any, Dict, Optional + +import boto3 +from botocore.exceptions import ClientError + +logger = logging.getLogger(__name__) + +# DynamoDB key constants +FIRST_BOOT_PK = "SYSTEM_SETTINGS#first-boot" +FIRST_BOOT_SK = "SYSTEM_SETTINGS#first-boot" + + +class SystemSettingsRepository: + """ + Repository for system settings CRUD operations in DynamoDB. + + Stores the first-boot completion state using a single-item pattern + in the auth providers table. Uses conditional writes for race + condition protection on first-boot completion. + """ + + def __init__( + self, + table_name: Optional[str] = None, + region: Optional[str] = None, + ): + self._table_name = table_name or os.getenv("DYNAMODB_AUTH_PROVIDERS_TABLE_NAME") + self._region = region or os.getenv("AWS_REGION", "us-west-2") + self._enabled = bool(self._table_name) + + if not self._enabled: + logger.warning( + "DYNAMODB_AUTH_PROVIDERS_TABLE_NAME not set. " + "System settings repository is disabled." + ) + return + + profile = os.getenv("AWS_PROFILE") + if profile: + session = boto3.Session(profile_name=profile) + self._dynamodb = session.resource("dynamodb", region_name=self._region) + else: + self._dynamodb = boto3.resource("dynamodb", region_name=self._region) + + self._table = self._dynamodb.Table(self._table_name) + logger.info(f"Initialized system settings repository: table={self._table_name}") + + @property + def enabled(self) -> bool: + return self._enabled + + async def get_first_boot_status(self) -> Optional[Dict[str, Any]]: + """ + Get the first-boot completion status. + + Returns: + Dict with first-boot item attributes if completed, None if + the item does not exist (system not yet bootstrapped). + """ + if not self._enabled: + return None + + try: + response = self._table.get_item( + Key={"PK": FIRST_BOOT_PK, "SK": FIRST_BOOT_SK} + ) + return response.get("Item") + except ClientError as e: + logger.error(f"Error reading first-boot status: {e}") + raise + + async def mark_first_boot_completed( + self, + user_id: str, + username: str, + email: str, + ) -> None: + """ + Mark first-boot as completed with an atomic conditional write. + + Uses ``attribute_not_exists(PK)`` so that exactly one concurrent + caller succeeds. All others receive a + ``ConditionalCheckFailedException`` which the caller should + translate to HTTP 409 Conflict. + + Args: + user_id: The Cognito user ID of the admin user. + username: The admin username. + email: The admin email address. + + Raises: + ClientError: With code ``ConditionalCheckFailedException`` + when first-boot has already been completed. + """ + if not self._enabled: + raise RuntimeError("System settings repository is not enabled") + + now = datetime.now(timezone.utc).isoformat() + + self._table.put_item( + Item={ + "PK": FIRST_BOOT_PK, + "SK": FIRST_BOOT_SK, + "completed": True, + "completedAt": now, + "completedBy": user_id, + "adminUsername": username, + "adminEmail": email, + }, + ConditionExpression="attribute_not_exists(PK)", + ) + + logger.info(f"First-boot completed by user_id={user_id}") + + +# Singleton instance +_repository: Optional[SystemSettingsRepository] = None + + +def get_system_settings_repository() -> SystemSettingsRepository: + """Get the system settings repository singleton.""" + global _repository + if _repository is None: + _repository = SystemSettingsRepository() + return _repository diff --git a/backend/src/apis/app_api/system/routes.py b/backend/src/apis/app_api/system/routes.py new file mode 100644 index 00000000..e071632f --- /dev/null +++ b/backend/src/apis/app_api/system/routes.py @@ -0,0 +1,168 @@ +"""System status and first-boot API routes.""" + +import logging +from datetime import datetime, timezone + +from botocore.exceptions import ClientError +from fastapi import APIRouter, HTTPException + +from apis.shared.users.models import UserProfile, UserStatus +from apis.shared.users.repository import UserRepository + +from .cognito_service import get_cognito_service +from .models import FirstBootRequest, FirstBootResponse, SystemStatusResponse +from .repository import get_system_settings_repository + +logger = logging.getLogger(__name__) + +router = APIRouter(prefix="/system", tags=["system"]) + + +@router.get("/status") +async def get_system_status() -> SystemStatusResponse: + """Check if first-boot has been completed. Public endpoint — no auth required.""" + try: + repo = get_system_settings_repository() + settings = await repo.get_first_boot_status() + return SystemStatusResponse( + first_boot_completed=settings is not None and settings.get("completed") is True, + ) + except Exception: + logger.exception("Failed to read first-boot status from DynamoDB") + return SystemStatusResponse(first_boot_completed=False) + + +@router.post("/first-boot", status_code=200) +async def first_boot(request: FirstBootRequest) -> FirstBootResponse: + """ + Create the initial admin user. One-time only — rejects if already completed. + + Public endpoint (no auth required). The flow: + 1. Atomic check via conditional DynamoDB write (rejects duplicates with 409) + 2. Create user in Cognito via AdminCreateUser + AdminSetUserPassword + 3. Create user record in Users DynamoDB table with system_admin role + 4. Mark first-boot completed in DynamoDB + 5. Disable self-signup on the Cognito User Pool + """ + settings_repo = get_system_settings_repository() + cognito = get_cognito_service() + user_repo = UserRepository() + + # 1. Atomic check: if first-boot already completed, return 409 + try: + existing = await settings_repo.get_first_boot_status() + if existing is not None and existing.get("completed") is True: + raise HTTPException( + status_code=409, + detail="First-boot has already been completed.", + ) + except HTTPException: + raise + except Exception: + logger.exception("Failed to check first-boot status") + raise HTTPException( + status_code=500, + detail="Failed to check first-boot status.", + ) + + # 2. Create user in Cognito + user_sub = "" + try: + user_sub = cognito.create_admin_user( + username=request.username, + email=request.email, + password=request.password, + ) + except ClientError as e: + error_code = e.response["Error"]["Code"] + if error_code == "InvalidPasswordException": + raise HTTPException( + status_code=400, + detail=f"Password does not meet Cognito policy: {e.response['Error']['Message']}", + ) + if error_code == "UsernameExistsException": + raise HTTPException( + status_code=409, + detail="A user with that username already exists.", + ) + logger.exception("Cognito AdminCreateUser failed") + raise HTTPException( + status_code=500, + detail="Failed to create user in Cognito.", + ) + + # 3. Create user record in Users DynamoDB table with system_admin role + now_iso = datetime.now(timezone.utc).isoformat() + email_domain = request.email.split("@")[1] if "@" in request.email else "" + + # Add user to system_admin Cognito group so JWT includes the role + try: + cognito.add_user_to_group(request.username, "system_admin") + except Exception: + logger.exception("Failed to add user to system_admin Cognito group — rolling back") + cognito.delete_user(request.username) + raise HTTPException( + status_code=500, + detail="Failed to assign admin group. Cognito user has been rolled back.", + ) + + try: + if user_repo.enabled: + profile = UserProfile( + userId=user_sub, + email=request.email, + name=request.username, + roles=["system_admin"], + emailDomain=email_domain, + createdAt=now_iso, + lastLoginAt=now_iso, + status=UserStatus.ACTIVE, + ) + await user_repo.create_user(profile) + except Exception: + logger.exception("Failed to create user record in DynamoDB — rolling back Cognito user") + cognito.delete_user(request.username) + raise HTTPException( + status_code=500, + detail="Failed to create user record. Cognito user has been rolled back.", + ) + + # 4. Mark first-boot completed in DynamoDB (conditional write) + try: + await settings_repo.mark_first_boot_completed( + user_id=user_sub, + username=request.username, + email=request.email, + ) + except ClientError as e: + if e.response["Error"]["Code"] == "ConditionalCheckFailedException": + # Race condition: another request completed first-boot between our + # check and this write. Roll back the Cognito user. + logger.warning("First-boot race condition detected — rolling back") + cognito.delete_user(request.username) + raise HTTPException( + status_code=409, + detail="First-boot was completed by another request.", + ) + logger.exception("Failed to mark first-boot completed — rolling back") + cognito.delete_user(request.username) + raise HTTPException( + status_code=500, + detail="Failed to mark first-boot completed.", + ) + + # 5. Disable self-signup on the Cognito User Pool + try: + cognito.disable_self_signup() + except Exception: + # Non-fatal: first-boot succeeded, admin can disable manually + logger.exception( + "Failed to disable self-signup after first-boot. " + "Admin should disable it manually via AWS console." + ) + + return FirstBootResponse( + success=True, + user_id=user_sub, + message="First-boot completed. Admin user created successfully.", + ) diff --git a/backend/src/apis/app_api/tools/routes.py b/backend/src/apis/app_api/tools/routes.py index d879bcd6..619c2cdb 100644 --- a/backend/src/apis/app_api/tools/routes.py +++ b/backend/src/apis/app_api/tools/routes.py @@ -87,7 +87,7 @@ async def get_user_tools( Returns: UserToolsResponse with user's accessible tools """ - logger.info(f"User {user.email} getting tools with preferences") + logger.info(f"User {user.name} getting tools with preferences") service = get_tool_catalog_service() tools = await service.get_user_accessible_tools(user) @@ -121,7 +121,7 @@ async def update_tool_preferences( Returns: Success message """ - logger.info(f"User {user.email} updating tool preferences") + logger.info(f"User {user.name} updating tool preferences") service = get_tool_catalog_service() @@ -157,7 +157,7 @@ async def list_all_tools( Returns: LegacyToolListResponse with list of all tools """ - logger.info(f"User {user.email} listing tool catalog (legacy)") + logger.info(f"User {user.name} listing tool catalog (legacy)") catalog_service = get_legacy_catalog_service() @@ -202,7 +202,7 @@ async def get_my_tool_permissions( Returns: UserToolPermissionsResponse with user's allowed tools """ - logger.info(f"User {user.email} checking tool permissions") + logger.info(f"User {user.name} checking tool permissions") role_service = get_app_role_service() permissions = await role_service.resolve_user_permissions(user) @@ -235,7 +235,7 @@ async def list_available_tools( Returns: LegacyToolListResponse with user's available tools """ - logger.info(f"User {user.email} listing available tools (legacy)") + logger.info(f"User {user.name} listing available tools (legacy)") catalog_service = get_legacy_catalog_service() role_service = get_app_role_service() diff --git a/backend/src/apis/app_api/users/models.py b/backend/src/apis/app_api/users/models.py index 15fe8904..ab7e45bc 100644 --- a/backend/src/apis/app_api/users/models.py +++ b/backend/src/apis/app_api/users/models.py @@ -29,3 +29,14 @@ class UserPermissionsResponse(BaseModel): models: List[str] = Field(..., description="Accessible model IDs") quota_tier: Optional[str] = Field(None, alias="quotaTier", description="Assigned quota tier") resolved_at: str = Field(..., alias="resolvedAt", description="ISO timestamp of resolution") + + +class UserProfileSyncRequest(BaseModel): + """Request to sync user profile from the frontend ID token.""" + model_config = ConfigDict(populate_by_name=True) + + email: str = Field(..., description="User email from ID token") + name: str = Field("", description="User display name from ID token") + picture: Optional[str] = Field(None, description="Profile picture URL from ID token") + roles: List[str] = Field(default_factory=list, description="User roles from ID token") + provider_sub: Optional[str] = Field(None, alias="provider_sub", description="IdP user identifier from ID token") diff --git a/backend/src/apis/app_api/users/routes.py b/backend/src/apis/app_api/users/routes.py index 35e8ad54..cf50e16e 100644 --- a/backend/src/apis/app_api/users/routes.py +++ b/backend/src/apis/app_api/users/routes.py @@ -7,8 +7,8 @@ from apis.shared.auth.models import User from apis.shared.rbac.service import get_app_role_service from apis.shared.users.repository import UserRepository -from apis.shared.users.models import UserStatus -from .models import UserSearchResult, UserSearchResponse, UserPermissionsResponse +from apis.shared.users.models import UserProfile, UserListItem, UserStatus +from .models import UserSearchResult, UserSearchResponse, UserPermissionsResponse, UserProfileSyncRequest logger = logging.getLogger(__name__) @@ -49,6 +49,55 @@ async def get_my_permissions( ) +@router.post("/me/sync", status_code=204) +async def sync_my_profile( + body: UserProfileSyncRequest, + current_user: User = Depends(get_current_user), + user_repo: UserRepository = Depends(get_user_repository), +): + """ + Sync user profile from the frontend ID token to the Users table. + + Called by the frontend after each login or token refresh. The ID token + contains identity claims (email, name, picture) that the access token + lacks. This keeps the Users table current so the backend can resolve + email for features like assistant sharing and fine-tuning access. + """ + if not user_repo.enabled: + return + + email = body.email.strip().lower() + if not email: + raise HTTPException(status_code=422, detail="Email is required") + + email_domain = email.split("@")[1] if "@" in email else "" + from datetime import datetime, timezone + now = datetime.now(timezone.utc).isoformat() + "Z" + + profile = UserProfile( + user_id=current_user.user_id, + email=email, + name=body.name or current_user.name, + roles=body.roles if body.roles else current_user.roles or [], + picture=body.picture, + email_domain=email_domain, + created_at=now, + last_login_at=now, + status=UserStatus.ACTIVE, + ) + + try: + await user_repo.upsert_user(profile) + # Invalidate the in-memory profile cache so the enrichment function + # picks up the fresh roles on the very next request. + from apis.shared.auth.dependencies import invalidate_user_profile_cache + invalidate_user_profile_cache(current_user.user_id) + logger.info("Synced profile for user %s", current_user.user_id) + except Exception as e: + logger.error(f"Failed to sync profile for {current_user.user_id}: {e}", exc_info=True) + raise HTTPException(status_code=500, detail="Failed to sync profile") + + @router.get("/search", response_model=UserSearchResponse) async def search_users( q: str = Query(..., description="Search query (email or name, partial match)"), diff --git a/backend/src/apis/inference_api/main.py b/backend/src/apis/inference_api/main.py index 0e3f5018..5c095daf 100644 --- a/backend/src/apis/inference_api/main.py +++ b/backend/src/apis/inference_api/main.py @@ -117,19 +117,15 @@ async def lifespan(app: FastAPI): ) logger.info("Added GZip middleware for response compression") -# Add CORS middleware for local development -# In production (AWS), CloudFront handles routing so CORS is not needed -if os.getenv('ENVIRONMENT', 'development') == 'development': - logger.info("Adding CORS middleware for local development") - app.add_middleware( - CORSMiddleware, - allow_origins=[ - "http://localhost:4200", # Frontend dev server - ], - allow_credentials=True, - allow_methods=["*"], - allow_headers=["*"], - ) +# Add CORS middleware - origins from CDK-provided CORS_ORIGINS env var +_cors_origins = os.environ.get("CORS_ORIGINS", "").split(",") +app.add_middleware( + CORSMiddleware, + allow_origins=[o.strip() for o in _cors_origins if o.strip()], + allow_credentials=False, + allow_methods=["*"], + allow_headers=["*"], +) # Import routers #from health.health import router as health_router diff --git a/backend/src/apis/shared/auth/__init__.py b/backend/src/apis/shared/auth/__init__.py index 1ca785c1..522f92e0 100644 --- a/backend/src/apis/shared/auth/__init__.py +++ b/backend/src/apis/shared/auth/__init__.py @@ -3,17 +3,7 @@ from .dependencies import get_current_user, security from .models import User from .state_store import StateStore, InMemoryStateStore, DynamoDBStateStore, create_state_store -from .rbac import ( - require_roles, - require_all_roles, - has_any_role, - has_all_roles, - require_admin, - require_faculty, - require_staff, - require_developer, - require_aws_ai_access, -) +from .rbac import require_app_roles, require_admin __all__ = [ "get_current_user", @@ -23,20 +13,6 @@ "InMemoryStateStore", "DynamoDBStateStore", "create_state_store", - "require_roles", - "require_all_roles", - "has_any_role", - "has_all_roles", + "require_app_roles", "require_admin", - "require_faculty", - "require_staff", - "require_developer", - "require_aws_ai_access", ] - - - - - - - diff --git a/backend/src/apis/shared/auth/cognito_jwt_validator.py b/backend/src/apis/shared/auth/cognito_jwt_validator.py new file mode 100644 index 00000000..57601af6 --- /dev/null +++ b/backend/src/apis/shared/auth/cognito_jwt_validator.py @@ -0,0 +1,133 @@ +"""Cognito JWT validator for single-issuer Cognito User Pool authentication.""" + +import logging +from typing import List + +import jwt +from jwt import PyJWKClient +from fastapi import HTTPException, status + +from .models import User + +logger = logging.getLogger(__name__) + + +class CognitoJWTValidator: + """Validates JWT tokens against a single Cognito User Pool. + + Supports both Cognito access tokens (which use `client_id` claim) + and Cognito ID tokens (which use `aud` claim) for App Client verification. + """ + + def __init__(self, user_pool_id: str, app_client_id: str, region: str): + self._issuer = f"https://cognito-idp.{region}.amazonaws.com/{user_pool_id}" + self._app_client_id = app_client_id + jwks_url = f"{self._issuer}/.well-known/jwks.json" + self._jwks_client = PyJWKClient(jwks_url, cache_keys=True) + + def validate_token(self, token: str) -> User: + """Validate a Cognito JWT token and extract user identity. + + Args: + token: JWT token string (access or ID token). + + Returns: + User object with extracted claims. + + Raises: + HTTPException: If token validation fails. + """ + try: + signing_key = self._jwks_client.get_signing_key_from_jwt(token) + # Cognito access tokens place the App Client ID in `client_id`, + # not `aud`. We disable PyJWT's built-in aud check and verify manually. + payload = jwt.decode( + token, + signing_key.key, + algorithms=["RS256"], + issuer=self._issuer, + options={"verify_exp": True, "verify_aud": False}, + ) + + # Validate client_id (access tokens) or aud (ID tokens) + token_client_id = payload.get("client_id") or payload.get("aud") + if token_client_id != self._app_client_id: + raise jwt.InvalidTokenError( + f"Token client_id/aud '{token_client_id}' does not match " + f"expected '{self._app_client_id}'" + ) + + # Extract roles from cognito:groups (list) or custom:roles (comma-separated string) + roles = self._extract_roles(payload) + + return User( + user_id=payload["sub"], + email=payload.get("email") or "", + name=payload.get("name") or payload.get("cognito:username") or payload.get("username") or "", + roles=roles, + picture=payload.get("picture"), + ) + + except jwt.InvalidSignatureError as e: + logger.error(f"Invalid Cognito token signature: {e}") + raise HTTPException( + status_code=status.HTTP_401_UNAUTHORIZED, + detail="Invalid token signature.", + ) + except jwt.InvalidIssuerError as e: + logger.error(f"Invalid Cognito token issuer: {e}") + raise HTTPException( + status_code=status.HTTP_401_UNAUTHORIZED, + detail="Invalid token issuer.", + ) + except jwt.ExpiredSignatureError: + raise HTTPException( + status_code=status.HTTP_401_UNAUTHORIZED, + detail="Token expired. Please refresh your session.", + ) + except jwt.InvalidTokenError as e: + logger.error(f"Invalid Cognito token: {e}") + raise HTTPException( + status_code=status.HTTP_401_UNAUTHORIZED, + detail="Invalid token.", + ) + except HTTPException: + raise + except Exception as e: + logger.error(f"Cognito token validation failed: {e}", exc_info=True) + raise HTTPException( + status_code=status.HTTP_401_UNAUTHORIZED, + detail="Token validation failed.", + ) + + def _extract_roles(self, payload: dict) -> List[str]: + """Extract roles from Cognito token claims. + + Priority order: + 1. ``custom:roles`` – IdP roles mapped via Cognito attribute mapping. + The value is a string that may be a JSON array (e.g. Entra ID sends + ``'["Admin","Staff"]'``) or a comma-separated list. + 2. ``cognito:groups`` – Cognito User Pool Groups. For federated users + this typically contains the Cognito provider group name (e.g. + ``us-west-2_Pool_provider-name``), not the IdP roles, so it is only + used as a fallback when ``custom:roles`` is absent. + """ + import json + + custom_roles = payload.get("custom:roles", "") + if custom_roles: + # Try JSON array first (e.g. '["Admin","Editor"]') + try: + parsed = json.loads(custom_roles) + if isinstance(parsed, list): + return [str(r).strip() for r in parsed if str(r).strip()] + except (json.JSONDecodeError, TypeError): + pass + # Fall back to comma-separated + return [r.strip() for r in custom_roles.split(",") if r.strip()] + + groups = payload.get("cognito:groups") + if isinstance(groups, list): + return groups + + return [] diff --git a/backend/src/apis/shared/auth/dependencies.py b/backend/src/apis/shared/auth/dependencies.py index 5288b3e7..5bf31501 100644 --- a/backend/src/apis/shared/auth/dependencies.py +++ b/backend/src/apis/shared/auth/dependencies.py @@ -3,6 +3,7 @@ import asyncio import jwt import logging +import os from typing import Optional from fastapi import Depends, HTTPException, status from fastapi.security import HTTPBearer, HTTPAuthorizationCredentials @@ -37,6 +38,93 @@ def _get_user_sync_service(): security = HTTPBearer(auto_error=False) +# ─── User Profile Cache ──────────────────────────────────────────────── +# Cognito access tokens don't contain identity claims (email, name, picture). +# We cache the user profile from DynamoDB so we only hit the table once per +# user, not on every request. TTL keeps it fresh if the profile changes. + +_user_profile_cache: dict[str, tuple[float, dict]] = {} +_USER_PROFILE_CACHE_TTL = 300 # 5 minutes + + +def invalidate_user_profile_cache(user_id: str) -> None: + """Remove a user's cached profile so the next request re-reads from DynamoDB. + + Call this after updating the Users table (e.g. from /users/me/sync) so + that subsequent requests pick up the fresh roles immediately. + """ + _user_profile_cache.pop(user_id, None) + +_user_repository = None + + +def _get_user_repository(): + """Get UserRepository instance, creating it lazily on first use.""" + global _user_repository + if _user_repository is not None: + return _user_repository + try: + from apis.shared.users.repository import UserRepository + repo = UserRepository() + if repo.enabled: + _user_repository = repo + except Exception as e: + logger.warning(f"Failed to initialize UserRepository for profile cache: {e}") + return _user_repository + + +async def _enrich_user_from_store(user: User) -> None: + """Fill in missing identity claims from the Users DynamoDB table. + + Cognito access tokens only carry sub, cognito:groups, and username. + The Users table (populated by the frontend's /users/me/sync call + which decodes the ID token) stores the full profile including the + IdP roles mapped via custom:roles. + + This enrichment is critical for RBAC: the access token's + cognito:groups contains the Cognito provider group name (e.g. + ``us-west-2_Pool_provider-name``), not the actual IdP roles. + The stored profile has the real roles parsed from the ID token. + + Results are cached in-memory to avoid per-request DynamoDB lookups. + """ + import time + + # Check cache first + now = time.monotonic() + cached = _user_profile_cache.get(user.user_id) + if cached: + ts, profile = cached + if now - ts < _USER_PROFILE_CACHE_TTL: + user.email = profile.get("email") or user.email + user.name = profile.get("name") or user.name + stored_roles = profile.get("roles") + if stored_roles: + user.roles = stored_roles + return + + # Cache miss — query DynamoDB + repo = _get_user_repository() + if not repo: + return + + try: + stored = await repo.get_user_by_user_id(user.user_id) + if stored: + profile = { + "email": stored.email, + "name": stored.name, + "roles": stored.roles, + } + _user_profile_cache[user.user_id] = (now, profile) + user.email = stored.email or user.email + user.name = stored.name or user.name + if stored.roles: + user.roles = stored.roles + except Exception as e: + logger.debug(f"Profile enrichment failed for {user.user_id}: {e}") + + async def _sync_user_background(sync_service, user: User) -> None: """Sync user to DynamoDB in the background (fire-and-forget).""" try: @@ -46,36 +134,50 @@ async def _sync_user_background(sync_service, user: User) -> None: # Log but don't fail - sync should never break authentication logger.warning(f"Failed to sync user {user.user_id}: {e}") -# Lazy-initialized generic validator for multi-provider support -_generic_validator = None -_generic_validator_initialized = False +# Lazy-initialized Cognito validator singleton +_cognito_validator = None -def _get_generic_validator(): +def _get_cognito_validator(): """ - Get the GenericOIDCJWTValidator instance. + Get the CognitoJWTValidator singleton instance. - Returns None if the auth providers table is not configured. + Reads Cognito configuration from environment variables: + - COGNITO_USER_POOL_ID: The Cognito User Pool ID + - COGNITO_APP_CLIENT_ID: The Cognito App Client ID + - COGNITO_REGION or AWS_REGION: The AWS region + + Returns None if required environment variables are not set. """ - global _generic_validator, _generic_validator_initialized - if _generic_validator_initialized: - return _generic_validator + global _cognito_validator + if _cognito_validator is not None: + return _cognito_validator - _generic_validator_initialized = True try: - from apis.shared.auth_providers.repository import get_auth_provider_repository - from .generic_jwt_validator import GenericOIDCJWTValidator + from .cognito_jwt_validator import CognitoJWTValidator - repo = get_auth_provider_repository() - if repo.enabled: - _generic_validator = GenericOIDCJWTValidator(repo) - logger.info("GenericOIDCJWTValidator initialized for multi-provider auth") - else: - logger.debug("Auth providers table not configured, generic validator disabled") + user_pool_id = os.environ.get("COGNITO_USER_POOL_ID") + app_client_id = os.environ.get("COGNITO_APP_CLIENT_ID") + region = os.environ.get("COGNITO_REGION") or os.environ.get("AWS_REGION") + + if not user_pool_id or not app_client_id or not region: + logger.warning( + "Cognito environment variables not fully configured. " + "Required: COGNITO_USER_POOL_ID, COGNITO_APP_CLIENT_ID, " + "COGNITO_REGION (or AWS_REGION)" + ) + return None + + _cognito_validator = CognitoJWTValidator( + user_pool_id=user_pool_id, + app_client_id=app_client_id, + region=region, + ) + logger.info("CognitoJWTValidator initialized for Cognito auth") except Exception as e: - logger.debug(f"Generic validator not available: {e}") + logger.error(f"Failed to initialize CognitoJWTValidator: {e}", exc_info=True) - return _generic_validator + return _cognito_validator async def get_current_user( @@ -84,8 +186,8 @@ async def get_current_user( """ FastAPI dependency to get the current authenticated user. - Validates the JWT token using the GenericOIDCJWTValidator, which - matches the token issuer to configured auth providers. + Validates the JWT token using the CognitoJWTValidator against + the configured Cognito User Pool. Args: credentials: HTTP Bearer token credentials (None if missing) @@ -108,21 +210,21 @@ async def get_current_user( token = credentials.credentials - # Use generic multi-provider validation - generic_validator = _get_generic_validator() - if generic_validator: + validator = _get_cognito_validator() + if validator: try: - provider = await generic_validator.resolve_provider_from_token(token) - if provider: - user = generic_validator.validate_token(token, provider) - user.raw_token = token + user = validator.validate_token(token) + user.raw_token = token - # Fire-and-forget sync to Users table - sync_service = _get_user_sync_service() - if sync_service and sync_service.enabled: - asyncio.create_task(_sync_user_background(sync_service, user)) + # Enrich with stored profile (email, name) when using access tokens + await _enrich_user_from_store(user) - return user + # Fire-and-forget sync to Users table + sync_service = _get_user_sync_service() + if sync_service and sync_service.enabled: + asyncio.create_task(_sync_user_background(sync_service, user)) + + return user except HTTPException: raise except Exception as e: @@ -132,11 +234,11 @@ async def get_current_user( detail="Authentication failed." ) - # No validator available - no auth providers configured - logger.error("No JWT validator available. Ensure at least one OIDC auth provider is configured.") + # No validator available - Cognito not configured + logger.error("No JWT validator available. Ensure Cognito environment variables are configured.") raise HTTPException( status_code=status.HTTP_500_INTERNAL_SERVER_ERROR, - detail="Authentication service not configured. No OIDC auth providers have been set up." + detail="Authentication service not configured. Cognito environment variables are missing." ) @@ -167,8 +269,8 @@ async def get_current_user_trusted( Use this when JWT validation is already performed at the network level (e.g., by AWS Bedrock AgentCore Runtime's JWT authorizer). This method - skips expensive signature verification and simply extracts claims from - the token using the matching auth provider's claim mappings. + skips expensive signature verification and simply extracts standard + Cognito/OIDC claims from the token. Security: Only use this in services where the JWT validation is guaranteed. IE AgentCore Runtime with Inbound Auth. For services without pre-validation, use @@ -202,82 +304,17 @@ async def get_current_user_trusted( payload = jwt.decode(token, options={"verify_signature": False}) logger.debug("[get_current_user_trusted] JWT decoded successfully") - # Resolve provider for claim mappings - generic_validator = _get_generic_validator() - if generic_validator: - try: - provider = await generic_validator.resolve_provider_from_token(token) - logger.debug(f"[get_current_user_trusted] Provider resolved: {provider.provider_id if provider else 'None'}") - if provider: - # Use provider-specific claim extraction - # Fall back to common OIDC claims if primary claim is absent - email = ( - payload.get(provider.email_claim) - or payload.get("preferred_username") - or payload.get("upn") - ) - name = payload.get(provider.name_claim) - user_id = payload.get(provider.user_id_claim) - roles = payload.get(provider.roles_claim, []) - picture = payload.get(provider.picture_claim) if provider.picture_claim else None - - logger.debug("[get_current_user_trusted] Claims extracted from token") - - if not name and provider.first_name_claim and provider.last_name_claim: - first = payload.get(provider.first_name_claim, "") - last = payload.get(provider.last_name_claim, "") - name = f"{first} {last}".strip() - - if isinstance(roles, str): - roles = [roles] - - if not user_id: - logger.error("[get_current_user_trusted] Required user_id claim is missing/empty in token - returning 401") - raise HTTPException( - status_code=status.HTTP_401_UNAUTHORIZED, - detail="Invalid user." - ) - - user = User( - email=str(email).lower() if email else "", - name=str(name) if name else "", - user_id=str(user_id), - roles=roles if isinstance(roles, list) else [], - picture=picture, - raw_token=token, - ) - - logger.debug("[get_current_user_trusted] User authenticated successfully via provider path") - - sync_service = _get_user_sync_service() - if sync_service and sync_service.enabled: - asyncio.create_task(_sync_user_background(sync_service, user)) - - return user - else: - logger.warning("[get_current_user_trusted] Provider resolved to None - falling through to generic extraction") - except HTTPException: - raise - except Exception as e: - logger.error(f"[get_current_user_trusted] Provider-based trusted extraction failed: {e}", exc_info=True) - raise HTTPException( - status_code=status.HTTP_401_UNAUTHORIZED, - detail="Authentication failed." - ) - else: - logger.warning("[get_current_user_trusted] No generic validator available (auth providers table not configured?)") - - # No auth providers configured - use standard OIDC claim extraction - logger.warning("[get_current_user_trusted] Using standard OIDC claim fallback (no provider matched)") + # Extract standard Cognito/OIDC claims email = payload.get('email') or payload.get('preferred_username') name = payload.get('name') or ( f"{payload.get('given_name', '')} {payload.get('family_name', '')}" - ).strip() + ).strip() or payload.get('cognito:username') or payload.get('username') or "" user_id = payload.get('sub') - roles = payload.get('roles', []) + # Support cognito:groups (list) or roles claim + roles = payload.get('cognito:groups') or payload.get('roles', []) picture = payload.get('picture') - logger.debug("[get_current_user_trusted] Using OIDC fallback claim extraction") + logger.debug("[get_current_user_trusted] Claims extracted from token") if not user_id: logger.error("[get_current_user_trusted] Missing 'sub' claim in token - returning 401") @@ -286,6 +323,9 @@ async def get_current_user_trusted( detail="Invalid user." ) + if isinstance(roles, str): + roles = [roles] + user = User( email=email.lower() if email else "", name=name, @@ -295,7 +335,10 @@ async def get_current_user_trusted( raw_token=token, ) - logger.debug("[get_current_user_trusted] User authenticated successfully via OIDC fallback") + logger.debug("[get_current_user_trusted] User authenticated successfully") + + # Enrich with stored profile (email, name) when using access tokens + await _enrich_user_from_store(user) # Fire-and-forget sync to Users table sync_service = _get_user_sync_service() diff --git a/backend/src/apis/shared/auth/generic_jwt_validator.py b/backend/src/apis/shared/auth/generic_jwt_validator.py deleted file mode 100644 index 9c5cf428..00000000 --- a/backend/src/apis/shared/auth/generic_jwt_validator.py +++ /dev/null @@ -1,338 +0,0 @@ -"""Generic OIDC JWT validator that works with any configured auth provider.""" - -import logging -import re -from typing import Dict, Optional - -import jwt -from jwt import PyJWKClient -from fastapi import HTTPException, status - -from .models import User -from apis.shared.auth_providers.models import AuthProvider -from apis.shared.auth_providers.repository import AuthProviderRepository - -logger = logging.getLogger(__name__) - - -class GenericOIDCJWTValidator: - """ - Validates JWT tokens against dynamically configured OIDC providers. - - Resolves the provider from the token's issuer claim, then validates - the token using that provider's JWKS and claim mappings. - """ - - def __init__(self, provider_repo: AuthProviderRepository): - self._provider_repo = provider_repo - # Cache PyJWKClient instances per provider (keyed by jwks_uri) - self._jwks_clients: Dict[str, PyJWKClient] = {} - # Cache issuer -> provider mapping for fast lookups - self._issuer_to_provider: Dict[str, AuthProvider] = {} - - def _get_jwks_client(self, provider: AuthProvider) -> PyJWKClient: - """Get or create a cached PyJWKClient for the provider's JWKS URI.""" - jwks_uri = provider.jwks_uri - if not jwks_uri: - raise HTTPException( - status_code=status.HTTP_500_INTERNAL_SERVER_ERROR, - detail=f"Auth provider '{provider.provider_id}' has no JWKS URI configured", - ) - - if jwks_uri not in self._jwks_clients: - self._jwks_clients[jwks_uri] = PyJWKClient( - jwks_uri, - cache_keys=True, - max_cached_keys=5, - ) - - return self._jwks_clients[jwks_uri] - - async def resolve_provider_from_token(self, token: str) -> Optional[AuthProvider]: - """ - Resolve which auth provider issued a token by matching the issuer claim. - - Args: - token: JWT token string - - Returns: - AuthProvider if a matching enabled provider is found, None otherwise - """ - try: - unverified = jwt.decode(token, options={"verify_signature": False}) - issuer = unverified.get("iss") - if not issuer: - return None - - # Check cache first - if issuer in self._issuer_to_provider: - cached = self._issuer_to_provider[issuer] - if cached.enabled: - return cached - - # Query enabled providers and match by issuer - providers = await self._provider_repo.list_providers(enabled_only=True) - for provider in providers: - if self._issuer_matches(issuer, provider): - self._issuer_to_provider[issuer] = provider - return provider - - return None - - except jwt.DecodeError: - return None - except Exception as e: - logger.debug(f"Error resolving provider from token: {e}") - return None - - def invalidate_cache(self) -> None: - """Clear all cached data. Call when providers are updated.""" - self._issuer_to_provider.clear() - self._jwks_clients.clear() - - def validate_token(self, token: str, provider: AuthProvider) -> User: - """ - Validate a JWT token using the provider's configuration and extract user info. - - Args: - token: JWT token string - provider: The AuthProvider configuration to validate against - - Returns: - User object with extracted claims - - Raises: - HTTPException: If validation fails - """ - try: - # Log token details for debugging (only when DEBUG is enabled) - if logger.isEnabledFor(logging.DEBUG): - try: - token_header = jwt.get_unverified_header(token) - logger.debug( - f"Validating token for provider {provider.provider_id}: " - f"alg={token_header.get('alg')}" - ) - except Exception: - logger.debug("Could not decode token header for inspection") - - # Get signing key from provider's JWKS - jwks_client = self._get_jwks_client(provider) - signing_key = jwks_client.get_signing_key_from_jwt(token) - - # Decode and validate token - # Allow issuer mismatch for providers like Entra ID where - # the token issuer (v1: sts.windows.net) differs from the - # OIDC discovery issuer (v2: login.microsoftonline.com) - payload = jwt.decode( - token, - signing_key.key, - algorithms=["RS256", "RS384", "RS512", "ES256", "ES384", "ES512"], - options={ - "verify_signature": True, - "verify_aud": False, # Manual audience verification below - "verify_iss": False, # Manual issuer verification below - "verify_exp": True, - }, - leeway=60, - ) - - # Manual issuer verification: accept both the configured issuer - # and known variant issuers (e.g., Entra ID v1 vs v2) - token_issuer = payload.get("iss", "") - if not self._issuer_matches(token_issuer, provider): - logger.warning( - f"Token issuer '{token_issuer}' does not match provider " - f"'{provider.provider_id}' issuer '{provider.issuer_url}'" - ) - raise HTTPException( - status_code=status.HTTP_401_UNAUTHORIZED, - detail=f"Invalid token issuer.", - ) - - # Verify audience if configured - if provider.allowed_audiences: - token_aud = payload.get("aud") - if isinstance(token_aud, str): - token_audiences = [token_aud] - elif isinstance(token_aud, list): - token_audiences = token_aud - else: - token_audiences = [] - - if not any(aud in provider.allowed_audiences for aud in token_audiences): - logger.warning( - f"Token audience {token_aud} not in allowed audiences " - f"for provider {provider.provider_id}" - ) - raise HTTPException( - status_code=status.HTTP_401_UNAUTHORIZED, - detail="Invalid token audience.", - ) - - # Verify required scopes if configured - if provider.required_scopes: - scp_claim = payload.get("scp", "") - token_scopes = scp_claim.split() if scp_claim else [] - for required_scope in provider.required_scopes: - if required_scope not in token_scopes: - logger.warning( - f"Token missing required scope '{required_scope}' " - f"for provider {provider.provider_id}" - ) - raise HTTPException( - status_code=status.HTTP_401_UNAUTHORIZED, - detail=f"Token missing required scope: {required_scope}", - ) - - # Extract user info using provider's claim mappings - user_id = self._extract_claim(payload, provider.user_id_claim) - email = ( - self._extract_claim(payload, provider.email_claim) - or payload.get("preferred_username") - or payload.get("upn") - ) - name = self._extract_claim(payload, provider.name_claim) - roles = payload.get(provider.roles_claim, []) - picture = payload.get(provider.picture_claim) if provider.picture_claim else None - - # Build full name from first/last if name claim is empty - if not name and provider.first_name_claim and provider.last_name_claim: - first = payload.get(provider.first_name_claim, "") - last = payload.get(provider.last_name_claim, "") - name = f"{first} {last}".strip() - - # Ensure roles is a list - if isinstance(roles, str): - roles = [roles] - elif not isinstance(roles, list): - roles = [] - - # Validate user_id format if pattern is configured - if provider.user_id_pattern and user_id: - user_id_str = str(user_id) - if not re.match(provider.user_id_pattern, user_id_str): - logger.warning( - f"User ID '{user_id_str}' does not match pattern " - f"'{provider.user_id_pattern}' for provider {provider.provider_id}" - ) - raise HTTPException( - status_code=status.HTTP_401_UNAUTHORIZED, - detail="Invalid user.", - ) - - if not user_id: - logger.warning( - f"Missing user_id claim '{provider.user_id_claim}' " - f"for provider {provider.provider_id}" - ) - raise HTTPException( - status_code=status.HTTP_401_UNAUTHORIZED, - detail="Invalid user.", - ) - - return User( - email=str(email).lower() if email else "", - user_id=str(user_id), - name=str(name) if name else str(email) or "", - roles=roles, - picture=picture, - ) - - except jwt.InvalidSignatureError as e: - logger.error(f"Invalid token signature for provider {provider.provider_id}: {e}") - raise HTTPException( - status_code=status.HTTP_401_UNAUTHORIZED, - detail="Invalid token signature.", - ) - except jwt.InvalidIssuerError as e: - logger.error(f"Invalid issuer for provider {provider.provider_id}: {e}") - raise HTTPException( - status_code=status.HTTP_401_UNAUTHORIZED, - detail=f"Invalid token issuer. Expected: {provider.issuer_url}", - ) - except jwt.ExpiredSignatureError: - raise HTTPException( - status_code=status.HTTP_401_UNAUTHORIZED, - detail="Token expired. Please refresh your session.", - ) - except jwt.InvalidTokenError as e: - logger.error(f"Invalid token for provider {provider.provider_id}: {e}") - raise HTTPException( - status_code=status.HTTP_401_UNAUTHORIZED, - detail="Invalid token.", - ) - except HTTPException: - raise - except Exception as e: - logger.error( - f"Error validating token for provider {provider.provider_id}: {e}", - exc_info=True, - ) - raise HTTPException( - status_code=status.HTTP_401_UNAUTHORIZED, - detail="Token validation failed.", - ) - - def _issuer_matches(self, token_issuer: str, provider: AuthProvider) -> bool: - """ - Check if a token's issuer matches a provider, accounting for known - issuer variants (e.g., Entra ID v1 vs v2 endpoints). - - Entra ID v2 issuer: https://login.microsoftonline.com/{tenant}/v2.0 - Entra ID v1 issuer: https://sts.windows.net/{tenant}/ - Both are valid for the same tenant. - """ - provider_issuer = provider.issuer_url.rstrip("/") - token_iss = token_issuer.rstrip("/") - - # Direct match - if provider_issuer == token_iss: - return True - - # Entra ID v1/v2 cross-match - # Extract tenant ID from either format and compare - v2_pattern = r"https://login\.microsoftonline\.com/([^/]+)/v2\.0" - v1_pattern = r"https://sts\.windows\.net/([^/]+)" - - v2_match_provider = re.match(v2_pattern, provider_issuer) - v1_match_token = re.match(v1_pattern, token_iss) - if v2_match_provider and v1_match_token: - if v2_match_provider.group(1) == v1_match_token.group(1): - return True - - v1_match_provider = re.match(v1_pattern, provider_issuer) - v2_match_token = re.match(v2_pattern, token_iss) - if v1_match_provider and v2_match_token: - if v1_match_provider.group(1) == v2_match_token.group(1): - return True - - return False - - def _extract_claim(self, payload: dict, claim_path: str) -> Optional[str]: - """ - Extract a claim value from the JWT payload. - - Supports nested claims using dot notation or URI-based claims - like 'http://schemas.example.com/claims/id'. - """ - if not claim_path: - return None - - # Direct lookup first (handles URI-style claims) - value = payload.get(claim_path) - if value is not None: - return value - - # Try dot-notation for nested claims (e.g., "address.country") - if "." in claim_path and not claim_path.startswith("http"): - parts = claim_path.split(".") - current = payload - for part in parts: - if isinstance(current, dict): - current = current.get(part) - else: - return None - return current - - return None diff --git a/backend/src/apis/shared/auth/rbac.py b/backend/src/apis/shared/auth/rbac.py index bcdcba27..f07df319 100644 --- a/backend/src/apis/shared/auth/rbac.py +++ b/backend/src/apis/shared/auth/rbac.py @@ -1,4 +1,9 @@ -"""Role-based access control utilities.""" +"""Role-based access control via the AppRole system. + +All authorization checks resolve through the AppRoleService, which maps +JWT ``cognito:groups`` claims to DynamoDB-backed AppRoles. This gives a +single source of truth for permissions — no hardcoded group names. +""" from typing import Callable from fastapi import Depends, HTTPException, status @@ -10,161 +15,61 @@ logger = logging.getLogger(__name__) -def require_roles(*required_roles: str) -> Callable: +def require_app_roles(*required_app_roles: str) -> Callable: """ - Create a dependency that requires the user to have at least one of the specified roles. + Create a dependency that checks the AppRole system for authorization. - This creates a FastAPI dependency that checks if the authenticated user has any of the - specified roles. If the user doesn't have any of the required roles, a 403 Forbidden - response is returned. + Resolves the user's effective AppRoles via the AppRoleService + (JWT role → DynamoDB AppRole mapping) and checks if any of the + required AppRoles are present. Fails closed: if the permission + lookup raises, access is denied. Usage: - @router.post("/admin/users") - async def admin_only_endpoint(user: User = Depends(require_roles("Admin", "SuperAdmin"))): - return {"message": "Admin access granted"} + @router.get("/admin/users") + async def list_users(user: User = Depends(require_app_roles("system_admin"))): + ... Args: - *required_roles: One or more role names that grant access (OR logic) + *required_app_roles: One or more AppRole IDs that grant access (OR logic) Returns: - A FastAPI dependency function that validates roles and returns the User object + A FastAPI dependency function that validates AppRoles and returns the User Raises: - HTTPException: 403 Forbidden if user doesn't have any of the required roles + HTTPException: 403 if user lacks all required AppRoles """ - async def role_checker(user: User = Depends(get_current_user)) -> User: - if not user.roles: - logger.warning(f"User {user.email} has no assigned roles, denying access") - raise HTTPException( - status_code=status.HTTP_403_FORBIDDEN, - detail="User has no assigned roles." - ) - - has_required_role = any(role in user.roles for role in required_roles) - if not has_required_role: - logger.warning( - f"User {user.email} (roles: {user.roles}) lacks required roles: {required_roles}" - ) - raise HTTPException( - status_code=status.HTTP_403_FORBIDDEN, - detail=f"Access denied. Required roles: {', '.join(required_roles)}" + async def checker(user: User = Depends(get_current_user)) -> User: + from apis.shared.rbac.service import get_app_role_service + + try: + service = get_app_role_service() + permissions = await service.resolve_user_permissions(user) + if any(role in permissions.app_roles for role in required_app_roles): + logger.debug( + f"User {user.name} authorized via AppRoles: " + f"{set(permissions.app_roles) & set(required_app_roles)}" + ) + return user + except Exception: + logger.exception( + f"Failed to resolve AppRole permissions for {user.name}, denying access" ) - logger.debug(f"User {user.email} authorized with roles: {user.roles}") - return user - - return role_checker - - -def require_all_roles(*required_roles: str) -> Callable: - """ - Create a dependency that requires the user to have ALL of the specified roles. - - This creates a FastAPI dependency that checks if the authenticated user has all of the - specified roles. If the user is missing any required role, a 403 Forbidden response - is returned. - - Usage: - @router.post("/admin/critical") - async def critical_endpoint(user: User = Depends(require_all_roles("Admin", "Security"))): - return {"message": "Full access granted"} - - Args: - *required_roles: All role names that must be present (AND logic) - - Returns: - A FastAPI dependency function that validates roles and returns the User object - - Raises: - HTTPException: 403 Forbidden if user doesn't have all required roles - """ - async def role_checker(user: User = Depends(get_current_user)) -> User: - if not user.roles: - logger.warning(f"User {user.email} has no assigned roles, denying access") - raise HTTPException( - status_code=status.HTTP_403_FORBIDDEN, - detail="User has no assigned roles." - ) - - has_all_roles = all(role in user.roles for role in required_roles) - if not has_all_roles: - missing_roles = [role for role in required_roles if role not in user.roles] - logger.warning( - f"User {user.email} (roles: {user.roles}) missing required roles: {missing_roles}" - ) - raise HTTPException( - status_code=status.HTTP_403_FORBIDDEN, - detail=f"Access denied. Missing required roles: {', '.join(missing_roles)}" - ) - - logger.debug(f"User {user.email} authorized with all required roles: {required_roles}") - return user - - return role_checker - - -def has_any_role(user: User, *roles: str) -> bool: - """ - Helper function to check if a user has any of the specified roles. - - Useful for conditional logic within route handlers without raising exceptions. - - Usage: - async def my_endpoint(user: User = Depends(get_current_user)): - if has_any_role(user, "Admin", "SuperAdmin"): - # Show additional admin data - pass - - Args: - user: User object to check - *roles: Role names to check for - - Returns: - True if user has any of the specified roles, False otherwise - """ - if not user.roles: - return False - return any(role in user.roles for role in roles) - - -def has_all_roles(user: User, *roles: str) -> bool: - """ - Helper function to check if a user has all of the specified roles. - - Useful for conditional logic within route handlers without raising exceptions. - - Usage: - async def my_endpoint(user: User = Depends(get_current_user)): - if has_all_roles(user, "Admin", "Security"): - # Perform security-sensitive operation - pass - - Args: - user: User object to check - *roles: Role names to check for - - Returns: - True if user has all of the specified roles, False otherwise - """ - if not user.roles: - return False - return all(role in user.roles for role in roles) - - -# Predefined role checkers for common use cases -# These can be used directly as dependencies: async def endpoint(user: User = Depends(require_admin)) - -# Admin access - requires either Admin or SuperAdmin role -require_admin = require_roles("Admin", "SuperAdmin", "DotNetDevelopers") + logger.warning( + f"User {user.name} (jwt_roles: {user.roles}) denied access — " + f"required AppRoles: {required_app_roles}" + ) + raise HTTPException( + status_code=status.HTTP_403_FORBIDDEN, + detail=f"Access denied. Required AppRoles: {', '.join(required_app_roles)}", + ) -# Faculty access -require_faculty = require_roles("Faculty") + return checker -# Staff access -require_staff = require_roles("Staff") -# Developer access -require_developer = require_roles("DotNetDevelopers") +# --------------------------------------------------------------------------- +# Predefined checkers +# --------------------------------------------------------------------------- -# AWS AI access -require_aws_ai_access = require_roles("AWS-BoiseStateAI") +# Admin access — any JWT group mapped to the "system_admin" AppRole. +require_admin = require_app_roles("system_admin") diff --git a/backend/src/apis/shared/auth_providers/cognito_idp_service.py b/backend/src/apis/shared/auth_providers/cognito_idp_service.py new file mode 100644 index 00000000..bed95058 --- /dev/null +++ b/backend/src/apis/shared/auth_providers/cognito_idp_service.py @@ -0,0 +1,310 @@ +"""Cognito Identity Provider management for federated OIDC providers. + +Handles registering, updating, and deleting federated identity providers +in a Cognito User Pool, and updating the App Client's supported providers list. +""" + +import logging +import os +from typing import Dict, List, Optional + +import boto3 +from botocore.exceptions import ClientError + +logger = logging.getLogger(__name__) + +# Default attribute mappings from Cognito attributes to OIDC claims +DEFAULT_ATTRIBUTE_MAPPING: Dict[str, str] = { + "email": "email", + "name": "name", + "given_name": "given_name", + "family_name": "family_name", + "picture": "picture", + "custom:provider_sub": "sub", +} + + +class CognitoIdentityProviderService: + """Manages federated OIDC identity providers in a Cognito User Pool.""" + + def __init__( + self, + user_pool_id: Optional[str] = None, + app_client_id: Optional[str] = None, + region: Optional[str] = None, + ): + self._user_pool_id = user_pool_id or os.getenv("COGNITO_USER_POOL_ID") + self._app_client_id = app_client_id or os.getenv("COGNITO_APP_CLIENT_ID") + self._region = region or os.getenv("AWS_REGION", "us-west-2") + self._enabled = bool(self._user_pool_id and self._app_client_id) + + if not self._enabled: + logger.warning( + "COGNITO_USER_POOL_ID or COGNITO_APP_CLIENT_ID not set. " + "Cognito identity provider service is disabled." + ) + return + + profile = os.getenv("AWS_PROFILE") + if profile: + session = boto3.Session(profile_name=profile) + self._client = session.client("cognito-idp", region_name=self._region) + else: + self._client = boto3.client("cognito-idp", region_name=self._region) + + logger.info( + f"Initialized Cognito IdP service: pool={self._user_pool_id}, " + f"client={self._app_client_id}" + ) + + @property + def enabled(self) -> bool: + return self._enabled + + def create_identity_provider( + self, + provider_name: str, + issuer_url: str, + client_id: str, + client_secret: str, + scopes: str = "openid profile email", + attribute_mapping: Optional[Dict[str, str]] = None, + ) -> None: + """Register an OIDC identity provider in the Cognito User Pool. + + Args: + provider_name: Unique name for the provider within the pool. + issuer_url: The OIDC issuer URL. + client_id: The OIDC client ID. + client_secret: The OIDC client secret. + scopes: Space-separated scopes string. + attribute_mapping: Custom attribute mapping (Cognito attr -> provider claim). + Falls back to DEFAULT_ATTRIBUTE_MAPPING if not provided. + + Raises: + ClientError: On Cognito API failure. + """ + if not self._enabled: + raise RuntimeError("Cognito identity provider service is not enabled") + + mapping = attribute_mapping or DEFAULT_ATTRIBUTE_MAPPING + + self._client.create_identity_provider( + UserPoolId=self._user_pool_id, + ProviderName=provider_name, + ProviderType="OIDC", + ProviderDetails={ + "client_id": client_id, + "client_secret": client_secret, + "authorize_scopes": scopes, + "oidc_issuer": issuer_url, + "attributes_request_method": "GET", + }, + AttributeMapping=mapping, + ) + logger.info(f"Created Cognito identity provider: {provider_name}") + + def update_identity_provider( + self, + provider_name: str, + issuer_url: Optional[str] = None, + client_id: Optional[str] = None, + client_secret: Optional[str] = None, + scopes: Optional[str] = None, + attribute_mapping: Optional[Dict[str, str]] = None, + ) -> None: + """Update an OIDC identity provider in the Cognito User Pool. + + Only provided (non-None) fields are updated. Builds updated + ProviderDetails and/or AttributeMapping from the supplied values + merged with the existing provider configuration. + + Args: + provider_name: The provider name to update. + issuer_url: Updated OIDC issuer URL. + client_id: Updated OIDC client ID. + client_secret: Updated OIDC client secret. + scopes: Updated space-separated scopes string. + attribute_mapping: Updated attribute mapping (replaces existing). + + Raises: + ClientError: On Cognito API failure. + """ + if not self._enabled: + raise RuntimeError("Cognito identity provider service is not enabled") + + # Fetch current provider config to merge with updates + resp = self._client.describe_identity_provider( + UserPoolId=self._user_pool_id, + ProviderName=provider_name, + ) + current = resp["IdentityProvider"] + current_details = current.get("ProviderDetails", {}) + + # Build updated ProviderDetails by merging + updated_details: Dict[str, str] = {} + updated_details["oidc_issuer"] = issuer_url if issuer_url is not None else current_details.get("oidc_issuer", "") + updated_details["client_id"] = client_id if client_id is not None else current_details.get("client_id", "") + updated_details["client_secret"] = client_secret if client_secret is not None else current_details.get("client_secret", "") + updated_details["authorize_scopes"] = scopes if scopes is not None else current_details.get("authorize_scopes", "openid profile email") + updated_details["attributes_request_method"] = current_details.get("attributes_request_method", "GET") + + update_kwargs: dict = { + "UserPoolId": self._user_pool_id, + "ProviderName": provider_name, + "ProviderDetails": updated_details, + } + + if attribute_mapping is not None: + update_kwargs["AttributeMapping"] = attribute_mapping + + self._client.update_identity_provider(**update_kwargs) + logger.info(f"Updated Cognito identity provider: {provider_name}") + + def delete_identity_provider(self, provider_name: str) -> None: + """Delete an identity provider from the Cognito User Pool. + + Handles 'not found' gracefully for idempotent deletes. + + Args: + provider_name: The provider name to delete. + """ + if not self._enabled: + return + + try: + self._client.delete_identity_provider( + UserPoolId=self._user_pool_id, + ProviderName=provider_name, + ) + logger.info(f"Deleted Cognito identity provider: {provider_name}") + except ClientError as e: + code = e.response["Error"]["Code"] + if code in ("ResourceNotFoundException", "UnsupportedIdentityProviderException"): + logger.warning( + f"Cognito identity provider '{provider_name}' not found during delete (idempotent)." + ) + else: + raise + + def get_supported_identity_providers(self) -> List[str]: + """Get the current list of supported identity providers on the App Client. + + Returns: + List of provider names (e.g. ['COGNITO', 'okta-prod']). + """ + if not self._enabled: + return [] + + response = self._client.describe_user_pool_client( + UserPoolId=self._user_pool_id, + ClientId=self._app_client_id, + ) + return response["UserPoolClient"].get("SupportedIdentityProviders", []) + + def add_provider_to_app_client(self, provider_name: str) -> None: + """Add a provider to the App Client's SupportedIdentityProviders. + + Fetches the current client config, appends the new provider, + and updates the client. Preserves all existing client settings. + + Args: + provider_name: The provider name to add. + + Raises: + ClientError: On Cognito API failure. + """ + if not self._enabled: + raise RuntimeError("Cognito identity provider service is not enabled") + + # Get current client configuration + response = self._client.describe_user_pool_client( + UserPoolId=self._user_pool_id, + ClientId=self._app_client_id, + ) + client_config = response["UserPoolClient"] + + current_providers = client_config.get("SupportedIdentityProviders", []) + if provider_name in current_providers: + logger.info(f"Provider '{provider_name}' already in App Client supported providers.") + return + + updated_providers = current_providers + [provider_name] + + # Build update params preserving existing settings + update_params = self._build_client_update_params(client_config, updated_providers) + self._client.update_user_pool_client(**update_params) + logger.info( + f"Updated App Client supported providers: {updated_providers}" + ) + + def remove_provider_from_app_client(self, provider_name: str) -> None: + """Remove a provider from the App Client's SupportedIdentityProviders. + + Args: + provider_name: The provider name to remove. + """ + if not self._enabled: + return + + response = self._client.describe_user_pool_client( + UserPoolId=self._user_pool_id, + ClientId=self._app_client_id, + ) + client_config = response["UserPoolClient"] + + current_providers = client_config.get("SupportedIdentityProviders", []) + if provider_name not in current_providers: + logger.info(f"Provider '{provider_name}' not in App Client supported providers.") + return + + updated_providers = [p for p in current_providers if p != provider_name] + + update_params = self._build_client_update_params(client_config, updated_providers) + self._client.update_user_pool_client(**update_params) + logger.info( + f"Removed '{provider_name}' from App Client supported providers: {updated_providers}" + ) + + def _build_client_update_params( + self, client_config: dict, supported_providers: List[str] + ) -> dict: + """Build UpdateUserPoolClient params preserving existing settings.""" + params: dict = { + "UserPoolId": self._user_pool_id, + "ClientId": self._app_client_id, + "SupportedIdentityProviders": supported_providers, + } + + # Preserve key existing settings + preserve_keys = [ + "ClientName", + "RefreshTokenValidity", + "AccessTokenValidity", + "IdTokenValidity", + "TokenValidityUnits", + "ExplicitAuthFlows", + "CallbackURLs", + "LogoutURLs", + "AllowedOAuthFlows", + "AllowedOAuthScopes", + "AllowedOAuthFlowsUserPoolClient", + "PreventUserExistenceErrors", + ] + for key in preserve_keys: + if key in client_config: + params[key] = client_config[key] + + return params + + +# Singleton +_cognito_idp_service: Optional[CognitoIdentityProviderService] = None + + +def get_cognito_idp_service() -> CognitoIdentityProviderService: + """Get the Cognito identity provider service singleton.""" + global _cognito_idp_service + if _cognito_idp_service is None: + _cognito_idp_service = CognitoIdentityProviderService() + return _cognito_idp_service diff --git a/backend/src/apis/shared/auth_providers/models.py b/backend/src/apis/shared/auth_providers/models.py index 9654bacf..70404462 100644 --- a/backend/src/apis/shared/auth_providers/models.py +++ b/backend/src/apis/shared/auth_providers/models.py @@ -50,6 +50,8 @@ class AuthProvider: created_at: str = field(default_factory=lambda: datetime.now(timezone.utc).isoformat() + "Z") updated_at: str = field(default_factory=lambda: datetime.now(timezone.utc).isoformat() + "Z") created_by: Optional[str] = None + # Cognito federated identity provider name + cognito_provider_name: Optional[str] = None # AgentCore Runtime tracking agentcore_runtime_arn: Optional[str] = None agentcore_runtime_id: Optional[str] = None @@ -123,6 +125,10 @@ def to_dynamo_item(self) -> Dict[str, Any]: if self.created_by: item["createdBy"] = self.created_by + # Cognito federated identity provider name + if self.cognito_provider_name: + item["cognitoProviderName"] = self.cognito_provider_name + # AgentCore Runtime tracking fields if self.agentcore_runtime_arn: item["agentcoreRuntimeArn"] = self.agentcore_runtime_arn @@ -170,6 +176,7 @@ def from_dynamo_item(cls, item: Dict[str, Any]) -> "AuthProvider": created_at=item.get("createdAt", datetime.now(timezone.utc).isoformat() + "Z"), updated_at=item.get("updatedAt", datetime.now(timezone.utc).isoformat() + "Z"), created_by=item.get("createdBy"), + cognito_provider_name=item.get("cognitoProviderName"), agentcore_runtime_arn=item.get("agentcoreRuntimeArn"), agentcore_runtime_id=item.get("agentcoreRuntimeId"), agentcore_runtime_endpoint_url=item.get("agentcoreRuntimeEndpointUrl"), @@ -224,6 +231,11 @@ class AuthProviderCreate(BaseModel): ) required_scopes: Optional[List[str]] = None allowed_audiences: Optional[List[str]] = None + # Discovery + auto_discover: bool = Field( + default=False, + description="When True, fetch .well-known/openid-configuration from issuer URL to auto-populate missing endpoints", + ) # Appearance logo_url: Optional[str] = None button_color: Optional[str] = Field( @@ -295,6 +307,7 @@ class AuthProviderResponse(BaseModel): created_at: str updated_at: str created_by: Optional[str] = None + cognito_provider_name: Optional[str] = None agentcore_runtime_arn: Optional[str] = None agentcore_runtime_id: Optional[str] = None agentcore_runtime_endpoint_url: Optional[str] = None @@ -335,6 +348,7 @@ def from_provider(cls, provider: AuthProvider) -> "AuthProviderResponse": created_at=provider.created_at, updated_at=provider.updated_at, created_by=provider.created_by, + cognito_provider_name=provider.cognito_provider_name, agentcore_runtime_arn=provider.agentcore_runtime_arn, agentcore_runtime_id=provider.agentcore_runtime_id, agentcore_runtime_endpoint_url=provider.agentcore_runtime_endpoint_url, diff --git a/backend/src/apis/shared/auth_providers/repository.py b/backend/src/apis/shared/auth_providers/repository.py index 6ae3d740..04868dd0 100644 --- a/backend/src/apis/shared/auth_providers/repository.py +++ b/backend/src/apis/shared/auth_providers/repository.py @@ -125,7 +125,7 @@ async def list_providers(self, enabled_only: bool = False) -> List[AuthProvider] logger.error(f"Error listing auth providers: {e}") raise - async def create_provider(self, data: AuthProviderCreate, created_by: Optional[str] = None) -> AuthProvider: + async def create_provider(self, data: AuthProviderCreate, created_by: Optional[str] = None, cognito_provider_name: Optional[str] = None) -> AuthProvider: """Create a new auth provider. Stores client secret in Secrets Manager.""" if not self._enabled: raise RuntimeError("Auth provider repository is not enabled") @@ -168,6 +168,7 @@ async def create_provider(self, data: AuthProviderCreate, created_by: Optional[s created_at=now, updated_at=now, created_by=created_by, + cognito_provider_name=cognito_provider_name, ) # Store client secret in Secrets Manager @@ -264,7 +265,10 @@ async def get_client_secret(self, provider_id: str) -> Optional[str]: response = self._secrets_client.get_secret_value( SecretId=self._secrets_arn ) - secrets = json.loads(response["SecretString"]) + try: + secrets = json.loads(response["SecretString"]) + except (json.JSONDecodeError, KeyError): + secrets = {} return secrets.get(provider_id) except ClientError as e: if e.response["Error"]["Code"] == "ResourceNotFoundException": @@ -287,7 +291,10 @@ async def _store_client_secret(self, provider_id: str, client_secret: str) -> No response = self._secrets_client.get_secret_value( SecretId=self._secrets_arn ) - secrets = json.loads(response["SecretString"]) + try: + secrets = json.loads(response["SecretString"]) + except (json.JSONDecodeError, KeyError): + secrets = {} except ClientError as e: if e.response["Error"]["Code"] == "ResourceNotFoundException": secrets = {} @@ -314,7 +321,10 @@ async def _delete_client_secret(self, provider_id: str) -> None: response = self._secrets_client.get_secret_value( SecretId=self._secrets_arn ) - secrets = json.loads(response["SecretString"]) + try: + secrets = json.loads(response["SecretString"]) + except (json.JSONDecodeError, KeyError): + secrets = {} if provider_id in secrets: del secrets[provider_id] diff --git a/backend/src/apis/shared/auth_providers/service.py b/backend/src/apis/shared/auth_providers/service.py index 16995bdc..1a69e123 100644 --- a/backend/src/apis/shared/auth_providers/service.py +++ b/backend/src/apis/shared/auth_providers/service.py @@ -2,11 +2,16 @@ import logging import re -from typing import List, Optional +from typing import Any, Dict, List, Optional import httpx +from botocore.exceptions import ClientError from fastapi import HTTPException, status +from .cognito_idp_service import ( + CognitoIdentityProviderService, + get_cognito_idp_service, +) from .models import ( AuthProvider, AuthProviderCreate, @@ -21,8 +26,13 @@ class AuthProviderService: """Business logic for OIDC authentication provider management.""" - def __init__(self, repository: AuthProviderRepository): + def __init__( + self, + repository: AuthProviderRepository, + cognito_idp_service: Optional[CognitoIdentityProviderService] = None, + ): self._repo = repository + self._cognito_idp = cognito_idp_service @property def enabled(self) -> bool: @@ -96,6 +106,14 @@ async def create_provider( If endpoints are not explicitly provided and an issuer_url is set, endpoints are auto-discovered from .well-known/openid-configuration. + + When Cognito IdP service is enabled, the provider is also registered + as a federated identity provider in the Cognito User Pool and added + to the App Client's supported providers list. + + Rollback strategy: + - If UpdateUserPoolClient fails → delete the identity provider from Cognito + - If DynamoDB write fails → delete the identity provider from Cognito """ # Validate provider_id format if not re.match(r"^[a-z0-9][a-z0-9-]*$", data.provider_id): @@ -104,14 +122,14 @@ async def create_provider( detail="provider_id must be lowercase alphanumeric with hyphens", ) - # Auto-discover endpoints if not all provided + # Auto-discover endpoints if not all provided and auto_discover is enabled needs_discovery = not all([ data.authorization_endpoint, data.token_endpoint, data.jwks_uri, ]) - if needs_discovery and data.issuer_url: + if needs_discovery and data.issuer_url and data.auto_discover: try: discovered = await self.discover_endpoints(data.issuer_url) # Fill in missing endpoints from discovery @@ -141,12 +159,112 @@ async def create_provider( detail=f"Invalid user_id_pattern regex: {e}", ) - return await self._repo.create_provider(data, created_by=created_by) + # Build attribute mapping from provider claim config + attribute_mapping = self._build_attribute_mapping(data) + + # Register in Cognito if enabled + cognito_provider_name: Optional[str] = None + if self._cognito_idp and self._cognito_idp.enabled: + cognito_provider_name = data.provider_id + try: + # Step 1: Create identity provider in Cognito + self._cognito_idp.create_identity_provider( + provider_name=cognito_provider_name, + issuer_url=data.issuer_url, + client_id=data.client_id, + client_secret=data.client_secret, + scopes=data.scopes, + attribute_mapping=attribute_mapping, + ) + except ClientError as e: + logger.error(f"Cognito CreateIdentityProvider failed: {e}") + raise HTTPException( + status_code=status.HTTP_502_BAD_GATEWAY, + detail=f"Failed to register provider in Cognito: {e.response['Error']['Message']}", + ) + + try: + # Step 2: Add provider to App Client's supported providers + self._cognito_idp.add_provider_to_app_client(cognito_provider_name) + except ClientError as e: + logger.error( + f"Cognito UpdateUserPoolClient failed, rolling back identity provider: {e}" + ) + # Rollback: delete the identity provider we just created + self._cognito_idp.delete_identity_provider(cognito_provider_name) + raise HTTPException( + status_code=status.HTTP_502_BAD_GATEWAY, + detail=f"Failed to update App Client in Cognito: {e.response['Error']['Message']}", + ) + + # Step 3: Save to DynamoDB + Secrets Manager (existing logic) + try: + provider = await self._repo.create_provider( + data, created_by=created_by, cognito_provider_name=cognito_provider_name + ) + except Exception as e: + # Rollback: delete from Cognito if DynamoDB write fails + if cognito_provider_name and self._cognito_idp and self._cognito_idp.enabled: + logger.error( + f"DynamoDB write failed, rolling back Cognito identity provider: {e}" + ) + try: + self._cognito_idp.remove_provider_from_app_client(cognito_provider_name) + except Exception: + logger.exception("Failed to remove provider from App Client during rollback") + self._cognito_idp.delete_identity_provider(cognito_provider_name) + raise + + return provider + + def _build_attribute_mapping(self, data: AuthProviderCreate) -> Dict[str, str]: + """Build Cognito attribute mapping from provider claim configuration. + + Maps Cognito standard attributes to the provider's claim names. + Uses the configured user_id_claim for custom:provider_sub and + roles_claim for custom:roles. + """ + mapping: Dict[str, str] = { + "email": data.email_claim or "email", + "custom:provider_sub": data.user_id_claim or "sub", + } + if data.roles_claim: + mapping["custom:roles"] = data.roles_claim + if data.name_claim: + mapping["name"] = data.name_claim + if data.first_name_claim: + mapping["given_name"] = data.first_name_claim + if data.last_name_claim: + mapping["family_name"] = data.last_name_claim + if data.picture_claim: + mapping["picture"] = data.picture_claim + return mapping + + # Fields that, when changed, require a Cognito UpdateIdentityProvider call + _OIDC_COGNITO_FIELDS = { + "issuer_url", + "client_id", + "client_secret", + "scopes", + "user_id_claim", + "email_claim", + "name_claim", + "roles_claim", + "first_name_claim", + "last_name_claim", + "picture_claim", + } async def update_provider( self, provider_id: str, updates: AuthProviderUpdate ) -> Optional[AuthProvider]: - """Update an auth provider. Re-discovers endpoints if issuer_url changes.""" + """Update an auth provider. Re-discovers endpoints if issuer_url changes. + + When Cognito IdP service is enabled and the provider has a + cognito_provider_name, OIDC-relevant field changes are synced + to Cognito via UpdateIdentityProvider before updating DynamoDB. + If the Cognito update fails, DynamoDB is not updated. + """ # If issuer_url is being changed, re-discover endpoints if updates.issuer_url: try: @@ -177,6 +295,75 @@ async def update_provider( detail=f"Invalid user_id_pattern regex: {e}", ) + # Sync OIDC changes to Cognito if applicable + if self._cognito_idp and self._cognito_idp.enabled: + existing = await self._repo.get_provider(provider_id) + if existing and existing.cognito_provider_name: + # Determine which OIDC-relevant fields actually changed + update_fields = updates.model_dump(exclude_none=True) + changed_oidc = { + k for k in update_fields if k in self._OIDC_COGNITO_FIELDS + } + + if changed_oidc: + # Build Cognito update kwargs from changed fields + cognito_kwargs: Dict[str, Any] = {} + if "issuer_url" in changed_oidc: + cognito_kwargs["issuer_url"] = updates.issuer_url + if "client_id" in changed_oidc: + cognito_kwargs["client_id"] = updates.client_id + if "client_secret" in changed_oidc: + cognito_kwargs["client_secret"] = updates.client_secret + if "scopes" in changed_oidc: + cognito_kwargs["scopes"] = updates.scopes + + # Rebuild attribute mapping if any claim fields changed + claim_fields = changed_oidc & { + "user_id_claim", + "email_claim", + "name_claim", + "roles_claim", + "first_name_claim", + "last_name_claim", + "picture_claim", + } + if claim_fields: + # Merge existing claims with updates + email_claim = updates.email_claim or existing.email_claim or "email" + user_id_claim = updates.user_id_claim if updates.user_id_claim is not None else existing.user_id_claim + mapping: Dict[str, str] = { + "email": email_claim, + "custom:provider_sub": user_id_claim or "sub", + } + roles_claim = updates.roles_claim if updates.roles_claim is not None else existing.roles_claim + if roles_claim: + mapping["custom:roles"] = roles_claim + name_claim = updates.name_claim if updates.name_claim is not None else existing.name_claim + if name_claim: + mapping["name"] = name_claim + first_name = updates.first_name_claim if updates.first_name_claim is not None else existing.first_name_claim + if first_name: + mapping["given_name"] = first_name + last_name = updates.last_name_claim if updates.last_name_claim is not None else existing.last_name_claim + if last_name: + mapping["family_name"] = last_name + picture = updates.picture_claim if updates.picture_claim is not None else existing.picture_claim + if picture: + mapping["picture"] = picture + cognito_kwargs["attribute_mapping"] = mapping + + try: + self._cognito_idp.update_identity_provider( + provider_name=existing.cognito_provider_name, + **cognito_kwargs, + ) + except ClientError as e: + logger.error(f"Cognito UpdateIdentityProvider failed: {e}") + raise HTTPException( + status_code=status.HTTP_502_BAD_GATEWAY, + detail=f"Failed to update provider in Cognito: {e.response['Error']['Message']}", + ) + return await self._repo.update_provider(provider_id, updates) async def get_provider(self, provider_id: str) -> Optional[AuthProvider]: @@ -188,7 +375,38 @@ async def list_providers(self, enabled_only: bool = False) -> List[AuthProvider] return await self._repo.list_providers(enabled_only=enabled_only) async def delete_provider(self, provider_id: str) -> bool: - """Delete a provider and its client secret.""" + """Delete a provider, removing from Cognito first, then DynamoDB and Secrets Manager. + + If the provider has a cognito_provider_name and the Cognito IdP service + is enabled, the provider is removed from the App Client's supported + providers list and deleted from the Cognito User Pool before the + DynamoDB/Secrets Manager cleanup. Cognito "not found" errors are + handled gracefully (idempotent delete). Cognito failures are logged + but do not prevent the DynamoDB deletion (best-effort cleanup). + """ + # Fetch provider to check for Cognito registration + provider = await self._repo.get_provider(provider_id) + if not provider: + return False + + # Remove from Cognito if applicable + if provider.cognito_provider_name and self._cognito_idp and self._cognito_idp.enabled: + try: + self._cognito_idp.remove_provider_from_app_client(provider.cognito_provider_name) + except Exception: + logger.exception( + f"Failed to remove provider '{provider.cognito_provider_name}' from App Client " + "(proceeding with delete)" + ) + try: + self._cognito_idp.delete_identity_provider(provider.cognito_provider_name) + except Exception: + logger.exception( + f"Failed to delete Cognito identity provider '{provider.cognito_provider_name}' " + "(proceeding with delete)" + ) + + # Delete from DynamoDB and Secrets Manager return await self._repo.delete_provider(provider_id) async def get_client_secret(self, provider_id: str) -> Optional[str]: @@ -261,5 +479,9 @@ def get_auth_provider_service() -> AuthProviderService: """Get the auth provider service singleton.""" global _service if _service is None: - _service = AuthProviderService(get_auth_provider_repository()) + cognito_idp = get_cognito_idp_service() + _service = AuthProviderService( + get_auth_provider_repository(), + cognito_idp_service=cognito_idp, + ) return _service diff --git a/backend/src/apis/shared/oauth/routes.py b/backend/src/apis/shared/oauth/routes.py index d901bd98..93f2edf7 100644 --- a/backend/src/apis/shared/oauth/routes.py +++ b/backend/src/apis/shared/oauth/routes.py @@ -44,7 +44,7 @@ async def list_available_providers( Returns: OAuthProviderListResponse with available providers """ - logger.info(f"User {current_user.email} listing available OAuth providers") + logger.info(f"User {current_user.name} listing available OAuth providers") # Resolve user's application roles permissions = await role_service.resolve_user_permissions(current_user) @@ -86,7 +86,7 @@ async def list_user_connections( Returns: OAuthConnectionListResponse with connection statuses """ - logger.info(f"User {current_user.email} listing OAuth connections") + logger.info(f"User {current_user.name} listing OAuth connections") # Resolve user's application roles permissions = await role_service.resolve_user_permissions(current_user) diff --git a/backend/src/apis/shared/rbac/admin_service.py b/backend/src/apis/shared/rbac/admin_service.py index 6525e09b..5f9daf23 100644 --- a/backend/src/apis/shared/rbac/admin_service.py +++ b/backend/src/apis/shared/rbac/admin_service.py @@ -124,14 +124,19 @@ async def update_role( # System role protection if existing.is_system_role and role_id == "system_admin": - # For system_admin, only allow updating display_name and description - allowed_fields = {"display_name", "description"} + # For system_admin, only allow updating display_name, description, + # and jwt_role_mappings. Silently drop other fields so the frontend + # can send its full form payload without triggering errors. + allowed_fields = {"display_name", "description", "jwt_role_mappings"} update_dict = updates.model_dump(exclude_unset=True) - invalid_fields = set(update_dict.keys()) - allowed_fields - if invalid_fields: - raise ValueError( - f"Cannot modify protected fields on system_admin role: {invalid_fields}" + blocked_fields = set(update_dict.keys()) - allowed_fields + if blocked_fields: + logger.info( + f"Stripping protected fields from system_admin update: {blocked_fields}" ) + # Rebuild updates with only allowed fields + filtered = {k: v for k, v in update_dict.items() if k in allowed_fields} + updates = AppRoleUpdate(**filtered) # Apply updates update_dict = updates.model_dump(exclude_unset=True, by_alias=False) diff --git a/backend/src/apis/shared/rbac/service.py b/backend/src/apis/shared/rbac/service.py index e5ad4d78..523d2875 100644 --- a/backend/src/apis/shared/rbac/service.py +++ b/backend/src/apis/shared/rbac/service.py @@ -83,7 +83,7 @@ async def resolve_user_permissions( if default_role and default_role.enabled: matching_roles = [default_role] logger.debug( - f"No matching roles for user {user.email}, using default role" + f"No matching roles for user {user.name}, using default role" ) # Step 4: Merge permissions @@ -93,7 +93,7 @@ async def resolve_user_permissions( await self.cache.set_user_permissions(user.user_id, permissions) logger.debug( - f"Resolved permissions for {user.email}: " + f"Resolved permissions for {user.name}: " f"roles={permissions.app_roles}, " f"tools={len(permissions.tools)}, " f"models={len(permissions.models)}" diff --git a/backend/src/apis/shared/rbac/system_admin.py b/backend/src/apis/shared/rbac/system_admin.py index 53badbb6..638513cc 100644 --- a/backend/src/apis/shared/rbac/system_admin.py +++ b/backend/src/apis/shared/rbac/system_admin.py @@ -43,15 +43,15 @@ async def create_role( app_role_service = get_app_role_service() permissions = await app_role_service.resolve_user_permissions(user) if "system_admin" in permissions.app_roles: - logger.debug(f"User {user.email} authorized as system admin") + logger.debug(f"User {user.name} authorized as system admin") return user except Exception: logger.exception( - f"Failed to resolve permissions for {user.email}, denying admin access" + f"Failed to resolve permissions for {user.name}, denying admin access" ) logger.warning( - f"User {user.email} (roles: {user.roles}) denied system admin access" + f"User {user.name} (roles: {user.roles}) denied system admin access" ) raise HTTPException( status_code=status.HTTP_403_FORBIDDEN, diff --git a/backend/tests/agents/main_agent/session/conftest.py b/backend/tests/agents/main_agent/session/conftest.py index 25e12614..57aa832e 100644 --- a/backend/tests/agents/main_agent/session/conftest.py +++ b/backend/tests/agents/main_agent/session/conftest.py @@ -223,11 +223,16 @@ def _init(self, agentcore_memory_config=None, region_name=None, **kwargs): def make_session_manager(mock_agentcore_config): """ Factory fixture — returns a callable that creates a TurnBasedSessionManager - with AgentCoreMemorySessionManager.__init__ mocked out so no AWS calls are made. + with AgentCoreMemorySessionManager.__init__ and .initialize() mocked out + so no AWS calls are made. - The resulting manager inherits all TurnBasedSessionManager methods and has - the parent's required attributes set via the mock __init__. + The parent's initialize() is replaced with a shim that simulates the SDK + behavior: read the agent, load messages from list_messages(), and populate + agent.messages. This allows tests to control the loaded messages by setting + mgr.read_agent and mgr.list_messages before calling mgr.initialize(agent). """ + active_patches = [] + def _factory(compaction_config=None, user_id=TEST_USER_ID, **kwargs): from bedrock_agentcore.memory.integrations.strands.session_manager import ( AgentCoreMemorySessionManager, @@ -238,6 +243,29 @@ def _factory(compaction_config=None, user_id=TEST_USER_ID, **kwargs): TurnBasedSessionManager._dynamodb_table = None TurnBasedSessionManager._dynamodb_table_name = None + _initialized_agent_ids = set() + + def _mock_sdk_initialize(self_inner, agent, **kw): + """Simulate what the SDK's initialize() does: load messages into agent.""" + from strands.types.exceptions import SessionException + + # SDK tracks agent_ids and raises on duplicate + if agent.agent_id in _initialized_agent_ids: + raise SessionException(f"Agent ID must be unique: {agent.agent_id}") + _initialized_agent_ids.add(agent.agent_id) + + session_agent = self_inner.read_agent(agent.agent_id) + if session_agent is None: + self_inner.create_agent(agent.agent_id) + else: + session_messages = self_inner.list_messages(agent.agent_id) + loaded = [sm.to_message() for sm in session_messages] + agent.messages = loaded + + # SDK always sets these after initialization + self_inner.has_existing_agent = True + self_inner._is_new_session = False + with patch.object( AgentCoreMemorySessionManager, "__init__", @@ -251,6 +279,16 @@ def _factory(compaction_config=None, user_id=TEST_USER_ID, **kwargs): **kwargs, ) + # Patch the parent's initialize so super().initialize() uses our shim. + # Keep the patch active for the lifetime of the test. + p = patch.object( + AgentCoreMemorySessionManager, + "initialize", + _mock_sdk_initialize, + ) + p.start() + active_patches.append(p) + # Set up mock methods for session repository operations # (These are inherited from AgentCoreMemorySessionManager and called via self) mgr.read_agent = MagicMock(return_value=None) @@ -260,4 +298,9 @@ def _factory(compaction_config=None, user_id=TEST_USER_ID, **kwargs): return mgr - return _factory + yield _factory + + # Cleanup: stop all patches started during this fixture's lifetime + for p in active_patches: + p.stop() + active_patches.clear() diff --git a/backend/tests/auth/test_auth_routes.py b/backend/tests/auth/test_auth_routes.py index f4fb1790..2726a182 100644 --- a/backend/tests/auth/test_auth_routes.py +++ b/backend/tests/auth/test_auth_routes.py @@ -2,30 +2,17 @@ Tests the full HTTP request/response cycle for: - GET /auth/providers -- GET /auth/login -- POST /auth/token -- POST /auth/refresh -- GET /auth/logout -- GET /auth/runtime-endpoint All service dependencies are mocked to isolate route logic. - -Requirements: 11.1–11.10 """ -from unittest.mock import AsyncMock, MagicMock, patch +from unittest.mock import AsyncMock, patch import pytest -from fastapi import FastAPI, HTTPException +from fastapi import FastAPI from fastapi.testclient import TestClient from apis.app_api.auth.routes import router -from apis.shared.auth.models import User - - -# --------------------------------------------------------------------------- -# App fixture — mounts only the auth router -# --------------------------------------------------------------------------- @pytest.fixture @@ -42,11 +29,6 @@ def client(app): return TestClient(app) -# --------------------------------------------------------------------------- -# Requirement 11.2: GET /auth/providers returns provider list -# --------------------------------------------------------------------------- - - class TestListAuthProviders: """GET /auth/providers returns enabled providers.""" @@ -91,289 +73,3 @@ def test_returns_empty_when_repo_disabled(self, client): assert resp.status_code == 200 assert resp.json()["providers"] == [] - - -# --------------------------------------------------------------------------- -# Requirement 11.3: GET /auth/login returns auth URL + state -# --------------------------------------------------------------------------- - - -class TestLogin: - """GET /auth/login initiates OIDC login.""" - - def test_returns_authorization_url_and_state(self, client): - """Should return authorization_url and state for a valid provider.""" - mock_service = MagicMock() - mock_service.redirect_uri = "http://localhost:4200/auth/callback" - mock_service.generate_state.return_value = ( - "state-abc", - "challenge-xyz", - "nonce-123", - ) - mock_service.build_authorization_url.return_value = ( - "https://login.example.com/authorize?state=state-abc" - ) - - with patch( - "apis.app_api.auth.routes.get_generic_auth_service", - new_callable=AsyncMock, - return_value=mock_service, - ): - resp = client.get("/auth/login", params={"provider_id": "test"}) - - assert resp.status_code == 200 - body = resp.json() - assert body["authorization_url"] == "https://login.example.com/authorize?state=state-abc" - assert body["state"] == "state-abc" - - -# --------------------------------------------------------------------------- -# Requirement 11.4: GET /auth/login unknown provider 400 -# --------------------------------------------------------------------------- - - - def test_unknown_provider_returns_error(self, client): - """Should return an error when provider_id is unknown.""" - with patch( - "apis.app_api.auth.routes.get_generic_auth_service", - new_callable=AsyncMock, - side_effect=HTTPException(status_code=400, detail="Provider not found"), - ): - resp = client.get("/auth/login", params={"provider_id": "nonexistent"}) - - assert resp.status_code == 400 - - -# --------------------------------------------------------------------------- -# Requirement 11.5: POST /auth/token valid exchange -# --------------------------------------------------------------------------- - - -class TestExchangeToken: - """POST /auth/token exchanges authorization code for tokens.""" - - def test_valid_exchange_returns_tokens(self, client): - """Should return tokens when state and code are valid.""" - mock_service = MagicMock() - mock_service.exchange_code_for_tokens = AsyncMock( - return_value={ - "access_token": "at-123", - "refresh_token": "rt-456", - "id_token": "id-789", - "token_type": "Bearer", - "expires_in": 3600, - "scope": "openid profile", - "provider_id": "test", - } - ) - - # Mock _peek_provider_from_state to return a provider_id - with patch( - "apis.app_api.auth.routes._peek_provider_from_state", - return_value="test", - ), patch( - "apis.app_api.auth.routes.get_generic_auth_service", - new_callable=AsyncMock, - return_value=mock_service, - ): - resp = client.post( - "/auth/token", - json={"code": "auth-code", "state": "valid-state"}, - ) - - assert resp.status_code == 200 - body = resp.json() - assert body["access_token"] == "at-123" - assert body["refresh_token"] == "rt-456" - assert body["id_token"] == "id-789" - assert body["token_type"] == "Bearer" - assert body["expires_in"] == 3600 - assert body["scope"] == "openid profile" - - -# --------------------------------------------------------------------------- -# Requirement 11.6: POST /auth/token invalid state 400 -# --------------------------------------------------------------------------- - - - def test_invalid_state_returns_400(self, client): - """Should return 400 when state cannot be resolved to a provider.""" - with patch( - "apis.app_api.auth.routes._peek_provider_from_state", - return_value=None, - ): - resp = client.post( - "/auth/token", - json={"code": "auth-code", "state": "bogus-state"}, - ) - - assert resp.status_code == 400 - - def test_exchange_http_exception_propagates(self, client): - """Should propagate HTTPException from exchange_code_for_tokens.""" - mock_service = MagicMock() - mock_service.exchange_code_for_tokens = AsyncMock( - side_effect=HTTPException(status_code=400, detail="Invalid or expired state"), - ) - - with patch( - "apis.app_api.auth.routes._peek_provider_from_state", - return_value="test", - ), patch( - "apis.app_api.auth.routes.get_generic_auth_service", - new_callable=AsyncMock, - return_value=mock_service, - ): - resp = client.post( - "/auth/token", - json={"code": "auth-code", "state": "bad-state"}, - ) - - assert resp.status_code == 400 - - -# --------------------------------------------------------------------------- -# Requirement 11.7: POST /auth/refresh success -# --------------------------------------------------------------------------- - - -class TestRefreshToken: - """POST /auth/refresh refreshes access token.""" - - def test_refresh_success(self, client): - """Should return new tokens on successful refresh.""" - mock_service = MagicMock() - mock_service.refresh_access_token = AsyncMock( - return_value={ - "access_token": "new-at-123", - "refresh_token": "new-rt-456", - "id_token": None, - "token_type": "Bearer", - "expires_in": 3600, - "scope": "openid", - } - ) - - with patch( - "apis.app_api.auth.routes.get_generic_auth_service", - new_callable=AsyncMock, - return_value=mock_service, - ): - resp = client.post( - "/auth/refresh", - params={"provider_id": "test"}, - json={"refresh_token": "old-rt"}, - ) - - assert resp.status_code == 200 - body = resp.json() - assert body["access_token"] == "new-at-123" - assert body["token_type"] == "Bearer" - assert body["expires_in"] == 3600 - - -# --------------------------------------------------------------------------- -# Requirement 11.8: GET /auth/logout returns URL -# --------------------------------------------------------------------------- - - -class TestLogout: - """GET /auth/logout returns logout URL.""" - - def test_logout_returns_url(self, client): - """Should return a logout_url for the given provider.""" - mock_service = MagicMock() - mock_service.build_logout_url.return_value = ( - "https://login.example.com/logout?post_logout_redirect_uri=http://localhost" - ) - - with patch( - "apis.app_api.auth.routes.get_generic_auth_service", - new_callable=AsyncMock, - return_value=mock_service, - ): - resp = client.get( - "/auth/logout", - params={"provider_id": "test"}, - ) - - assert resp.status_code == 200 - body = resp.json() - assert "logout" in body["logout_url"] - - -# --------------------------------------------------------------------------- -# Requirement 11.9: GET /auth/runtime-endpoint authenticated -# --------------------------------------------------------------------------- - - -class TestRuntimeEndpoint: - """GET /auth/runtime-endpoint requires authentication.""" - - def test_authenticated_returns_runtime_endpoint(self, client, app, make_provider): - """Should return runtime endpoint info for an authenticated user.""" - user = User( - email="test@example.com", - user_id="user-001", - name="Test User", - roles=["User"], - raw_token="valid-jwt-token", - ) - - provider = make_provider( - provider_id="test-provider", - agentcore_runtime_endpoint_url="https://runtime.example.com/invoke", - agentcore_runtime_status="READY", - ) - - # Override the get_current_user dependency - from apis.shared.auth.dependencies import get_current_user - - app.dependency_overrides[get_current_user] = lambda: user - - mock_repo = AsyncMock() - mock_repo.enabled = True - - mock_validator = MagicMock() - mock_validator.resolve_provider_from_token = AsyncMock(return_value=provider) - - with patch( - "apis.shared.auth_providers.repository.get_auth_provider_repository", - return_value=mock_repo, - ), patch( - "apis.shared.auth.generic_jwt_validator.GenericOIDCJWTValidator", - return_value=mock_validator, - ): - resp = client.get("/auth/runtime-endpoint") - - assert resp.status_code == 200 - body = resp.json() - assert body["runtime_endpoint_url"] == "https://runtime.example.com/invoke" - assert body["provider_id"] == "test-provider" - assert body["runtime_status"] == "READY" - - # Clean up override - app.dependency_overrides.clear() - - -# --------------------------------------------------------------------------- -# Requirement 11.10: GET /auth/runtime-endpoint unauthenticated 401 -# --------------------------------------------------------------------------- - - - def test_unauthenticated_returns_401(self, client, app): - """Should return 401 when no authentication is provided.""" - # Override get_current_user to raise 401 (simulating no credentials) - from apis.shared.auth.dependencies import get_current_user - - def _raise_401(): - raise HTTPException(status_code=401, detail="Not authenticated") - - app.dependency_overrides[get_current_user] = _raise_401 - - resp = client.get("/auth/runtime-endpoint") - - assert resp.status_code == 401 - - # Clean up override - app.dependency_overrides.clear() diff --git a/backend/tests/auth/test_cognito_jwt_validator.py b/backend/tests/auth/test_cognito_jwt_validator.py new file mode 100644 index 00000000..622203f7 --- /dev/null +++ b/backend/tests/auth/test_cognito_jwt_validator.py @@ -0,0 +1,400 @@ +"""Tests for CognitoJWTValidator. + +Covers: valid token decode, issuer verification, client_id/aud verification, +expiration check, claim extraction (sub, email, name, cognito:username fallback, +cognito:groups, custom:roles, picture), invalid signature, and missing sub claim. + +Requirements: 10.1, 10.2, 10.3, 10.4 +""" + +import time +from typing import Any, Dict, Optional +from unittest.mock import MagicMock + +import jwt as pyjwt +import pytest +from fastapi import HTTPException + +from apis.shared.auth.cognito_jwt_validator import CognitoJWTValidator + + +# --------------------------------------------------------------------------- +# Constants +# --------------------------------------------------------------------------- + +USER_POOL_ID = "us-east-1_TestPool" +APP_CLIENT_ID = "test-app-client-id" +REGION = "us-east-1" +ISSUER = f"https://cognito-idp.{REGION}.amazonaws.com/{USER_POOL_ID}" + + +# --------------------------------------------------------------------------- +# Fixtures +# --------------------------------------------------------------------------- + + +@pytest.fixture +def validator(mock_jwks_client): + """Create a CognitoJWTValidator with a mocked JWKS client.""" + v = CognitoJWTValidator( + user_pool_id=USER_POOL_ID, + app_client_id=APP_CLIENT_ID, + region=REGION, + ) + v._jwks_client = mock_jwks_client + return v + + +@pytest.fixture +def make_cognito_jwt(rsa_key_pair): + """Factory that creates signed Cognito-style JWT tokens.""" + + def _make( + claims: Optional[Dict[str, Any]] = None, + expired: bool = False, + ) -> str: + now = int(time.time()) + default_claims: Dict[str, Any] = { + "sub": "abc-123-def", + "email": "admin@example.com", + "name": "Admin User", + "cognito:username": "adminuser", + "cognito:groups": ["system_admin"], + "client_id": APP_CLIENT_ID, + "iss": ISSUER, + "iat": now, + "exp": now - 3600 if expired else now + 3600, + } + if claims: + default_claims.update(claims) + + return pyjwt.encode( + default_claims, + rsa_key_pair["private_pem"], + algorithm="RS256", + headers={"kid": "test-key-id"}, + ) + + return _make + + +# --------------------------------------------------------------------------- +# Valid token decode +# --------------------------------------------------------------------------- + + +class TestValidTokenDecode: + """Validates: Requirements 10.1, 10.2, 10.3, 10.4""" + + def test_valid_access_token_returns_user(self, validator, make_cognito_jwt): + token = make_cognito_jwt() + user = validator.validate_token(token) + + assert user.user_id == "abc-123-def" + assert user.email == "admin@example.com" + assert user.name == "Admin User" + assert user.roles == ["system_admin"] + + def test_valid_id_token_with_aud_returns_user(self, validator, make_cognito_jwt): + """ID tokens use `aud` instead of `client_id`.""" + token = make_cognito_jwt(claims={ + "aud": APP_CLIENT_ID, + "client_id": None, + }) + user = validator.validate_token(token) + + assert user.user_id == "abc-123-def" + assert user.email == "admin@example.com" + + +# --------------------------------------------------------------------------- +# Issuer verification +# --------------------------------------------------------------------------- + + +class TestIssuerVerification: + """Validates: Requirement 10.2""" + + def test_wrong_issuer_raises_401(self, validator, make_cognito_jwt): + token = make_cognito_jwt(claims={ + "iss": "https://cognito-idp.eu-west-1.amazonaws.com/eu-west-1_Wrong", + }) + with pytest.raises(HTTPException) as exc_info: + validator.validate_token(token) + + assert exc_info.value.status_code == 401 + + +# --------------------------------------------------------------------------- +# Client ID / Audience verification +# --------------------------------------------------------------------------- + + +class TestClientIdVerification: + """Validates: Requirement 10.3""" + + def test_wrong_client_id_raises_401(self, validator, make_cognito_jwt): + token = make_cognito_jwt(claims={"client_id": "wrong-client-id"}) + with pytest.raises(HTTPException) as exc_info: + validator.validate_token(token) + + assert exc_info.value.status_code == 401 + assert "Invalid token" in exc_info.value.detail + + def test_wrong_aud_raises_401(self, validator, make_cognito_jwt): + token = make_cognito_jwt(claims={ + "client_id": None, + "aud": "wrong-audience", + }) + with pytest.raises(HTTPException) as exc_info: + validator.validate_token(token) + + assert exc_info.value.status_code == 401 + + def test_no_client_id_or_aud_raises_401(self, validator, make_cognito_jwt): + token = make_cognito_jwt(claims={ + "client_id": None, + "aud": None, + }) + with pytest.raises(HTTPException) as exc_info: + validator.validate_token(token) + + assert exc_info.value.status_code == 401 + + +# --------------------------------------------------------------------------- +# Expiration verification +# --------------------------------------------------------------------------- + + +class TestExpirationVerification: + """Validates: Requirement 10.1""" + + def test_expired_token_raises_401(self, validator, make_cognito_jwt): + token = make_cognito_jwt(expired=True) + with pytest.raises(HTTPException) as exc_info: + validator.validate_token(token) + + assert exc_info.value.status_code == 401 + assert "Token expired" in exc_info.value.detail + + +# --------------------------------------------------------------------------- +# Claim extraction +# --------------------------------------------------------------------------- + + +class TestClaimExtraction: + """Validates: Requirement 10.4""" + + def test_name_falls_back_to_cognito_username(self, validator, make_cognito_jwt): + token = make_cognito_jwt(claims={"name": None}) + user = validator.validate_token(token) + + assert user.name == "adminuser" + + def test_empty_email_defaults_to_empty_string(self, validator, make_cognito_jwt): + token = make_cognito_jwt(claims={"email": None}) + user = validator.validate_token(token) + + assert user.email == "" + + # ---- custom:roles takes priority over cognito:groups ---- + + def test_custom_roles_preferred_over_cognito_groups(self, validator, make_cognito_jwt): + """custom:roles (IdP roles) should win over cognito:groups (provider group name).""" + token = make_cognito_jwt(claims={ + "cognito:groups": ["us-west-2_Pool_ms-entra-id"], + "custom:roles": "admin,editor", + }) + user = validator.validate_token(token) + + assert user.roles == ["admin", "editor"] + + def test_custom_roles_json_array_preferred_over_cognito_groups(self, validator, make_cognito_jwt): + """JSON array in custom:roles should win over cognito:groups.""" + token = make_cognito_jwt(claims={ + "cognito:groups": ["us-west-2_Pool_ms-entra-id"], + "custom:roles": '["DotNetDevelopers","Staff"]', + }) + user = validator.validate_token(token) + + assert user.roles == ["DotNetDevelopers", "Staff"] + + # ---- custom:roles JSON array parsing ---- + + def test_custom_roles_json_array_string(self, validator, make_cognito_jwt): + """Entra ID sends roles as a JSON array serialized to a string.""" + token = make_cognito_jwt(claims={ + "cognito:groups": None, + "custom:roles": '["DotNetDevelopers","All-Employees Entra Sync","Staff"]', + }) + user = validator.validate_token(token) + + assert user.roles == ["DotNetDevelopers", "All-Employees Entra Sync", "Staff"] + + def test_custom_roles_json_single_element_array(self, validator, make_cognito_jwt): + """Single-element JSON array.""" + token = make_cognito_jwt(claims={ + "cognito:groups": None, + "custom:roles": '["Admin"]', + }) + user = validator.validate_token(token) + + assert user.roles == ["Admin"] + + def test_custom_roles_json_empty_array(self, validator, make_cognito_jwt): + """Empty JSON array should return empty roles.""" + token = make_cognito_jwt(claims={ + "cognito:groups": None, + "custom:roles": '[]', + }) + user = validator.validate_token(token) + + assert user.roles == [] + + def test_custom_roles_json_strips_whitespace(self, validator, make_cognito_jwt): + """JSON array elements with whitespace should be trimmed.""" + token = make_cognito_jwt(claims={ + "cognito:groups": None, + "custom:roles": '[" Admin ", " Staff "]', + }) + user = validator.validate_token(token) + + assert user.roles == ["Admin", "Staff"] + + # ---- custom:roles comma-separated fallback ---- + + def test_custom_roles_comma_separated(self, validator, make_cognito_jwt): + """Plain comma-separated string (non-JSON) still works.""" + token = make_cognito_jwt(claims={ + "cognito:groups": None, + "custom:roles": "admin,editor", + }) + user = validator.validate_token(token) + + assert user.roles == ["admin", "editor"] + + def test_custom_roles_comma_separated_with_spaces(self, validator, make_cognito_jwt): + """Comma-separated with spaces around values.""" + token = make_cognito_jwt(claims={ + "cognito:groups": None, + "custom:roles": " admin , editor , viewer ", + }) + user = validator.validate_token(token) + + assert user.roles == ["admin", "editor", "viewer"] + + # ---- cognito:groups fallback ---- + + def test_cognito_groups_used_when_no_custom_roles(self, validator, make_cognito_jwt): + """cognito:groups is used as fallback when custom:roles is absent.""" + token = make_cognito_jwt(claims={ + "cognito:groups": ["admin", "editor"], + "custom:roles": None, + }) + user = validator.validate_token(token) + + assert user.roles == ["admin", "editor"] + + # ---- no roles at all ---- + + def test_no_roles_returns_empty_list(self, validator, make_cognito_jwt): + token = make_cognito_jwt(claims={ + "cognito:groups": None, + "custom:roles": None, + }) + user = validator.validate_token(token) + + assert user.roles == [] + + # ---- picture ---- + + def test_picture_extracted(self, validator, make_cognito_jwt): + token = make_cognito_jwt(claims={ + "picture": "https://example.com/photo.jpg", + }) + user = validator.validate_token(token) + + assert user.picture == "https://example.com/photo.jpg" + + def test_picture_none_when_absent(self, validator, make_cognito_jwt): + token = make_cognito_jwt() + user = validator.validate_token(token) + + assert user.picture is None + + +# --------------------------------------------------------------------------- +# Invalid signature +# --------------------------------------------------------------------------- + + +class TestInvalidSignature: + """Validates: Requirement 10.1""" + + def test_invalid_signature_raises_401(self, validator, make_cognito_jwt): + token = make_cognito_jwt() + bad_client = MagicMock() + bad_client.get_signing_key_from_jwt = MagicMock( + side_effect=pyjwt.exceptions.InvalidSignatureError("bad sig") + ) + validator._jwks_client = bad_client + + with pytest.raises(HTTPException) as exc_info: + validator.validate_token(token) + + assert exc_info.value.status_code == 401 + assert "Invalid token signature" in exc_info.value.detail + + +# --------------------------------------------------------------------------- +# Missing sub claim +# --------------------------------------------------------------------------- + + +class TestMissingSub: + """Validates: Requirement 10.4""" + + def test_missing_sub_raises_error(self, validator, make_cognito_jwt, rsa_key_pair): + """Token with 'sub' key removed should raise 401.""" + import time as _time + import jwt as pyjwt + + now = int(_time.time()) + claims = { + "email": "test@example.com", + "name": "Test", + "client_id": APP_CLIENT_ID, + "iss": ISSUER, + "iat": now, + "exp": now + 3600, + } + private_key = rsa_key_pair["private_pem"] + token = pyjwt.encode(claims, private_key, algorithm="RS256", headers={"kid": "test-key-id"}) + with pytest.raises(HTTPException) as exc_info: + validator.validate_token(token) + assert exc_info.value.status_code == 401 + + def test_token_without_sub_key_raises_401(self, validator, rsa_key_pair): + """Token completely missing the 'sub' key.""" + now = int(time.time()) + claims = { + "email": "test@example.com", + "name": "Test", + "client_id": APP_CLIENT_ID, + "iss": ISSUER, + "iat": now, + "exp": now + 3600, + } + token = pyjwt.encode( + claims, + rsa_key_pair["private_pem"], + algorithm="RS256", + headers={"kid": "test-key-id"}, + ) + + with pytest.raises(HTTPException) as exc_info: + validator.validate_token(token) + + assert exc_info.value.status_code == 401 diff --git a/backend/tests/auth/test_dependencies.py b/backend/tests/auth/test_dependencies.py index de2ab368..c336d115 100644 --- a/backend/tests/auth/test_dependencies.py +++ b/backend/tests/auth/test_dependencies.py @@ -1,11 +1,11 @@ """Tests for FastAPI auth dependencies. Covers: -- get_current_user: Bearer token validation via GenericOIDCJWTValidator +- get_current_user: Bearer token validation via CognitoJWTValidator - get_current_user_trusted: JWT decode without signature verification - get_current_user_id: convenience wrapper returning user_id string -Requirements: 3.1–3.10 +Requirements: 10.5, 10.6 """ import time @@ -40,21 +40,19 @@ def _bearer(token: str): class TestGetCurrentUser: - """Tests for the get_current_user dependency.""" + """Tests for the get_current_user dependency (Cognito-based).""" @pytest.mark.asyncio - async def test_valid_bearer_token(self, make_jwt, make_provider, make_user): - """Req 3.2: valid Bearer token resolves provider, validates, returns User with raw_token.""" - provider = make_provider() - token = make_jwt(provider=provider) + async def test_valid_bearer_token(self, make_jwt, make_user): + """Req 10.5: valid Bearer token validated by CognitoJWTValidator, returns User with raw_token.""" + token = make_jwt() expected_user = make_user(raw_token=None) mock_validator = MagicMock() - mock_validator.resolve_provider_from_token = AsyncMock(return_value=provider) mock_validator.validate_token = MagicMock(return_value=expected_user) with patch( - "apis.shared.auth.dependencies._get_generic_validator", + "apis.shared.auth.dependencies._get_cognito_validator", return_value=mock_validator, ), patch( "apis.shared.auth.dependencies._get_user_sync_service", @@ -65,12 +63,11 @@ async def test_valid_bearer_token(self, make_jwt, make_provider, make_user): assert isinstance(user, User) assert user.raw_token == token assert user.user_id == expected_user.user_id - mock_validator.resolve_provider_from_token.assert_awaited_once_with(token) - mock_validator.validate_token.assert_called_once_with(token, provider) + mock_validator.validate_token.assert_called_once_with(token) @pytest.mark.asyncio async def test_no_credentials_401(self): - """Req 3.3: None credentials raises 401 with WWW-Authenticate header.""" + """Req 10.5: None credentials raises 401 with WWW-Authenticate header.""" with pytest.raises(HTTPException) as exc_info: await get_current_user(credentials=None) @@ -78,19 +75,17 @@ async def test_no_credentials_401(self): assert "WWW-Authenticate" in (exc_info.value.headers or {}) @pytest.mark.asyncio - async def test_failed_validation_401(self, make_jwt, make_provider): - """Req 3.4: token that fails validation raises 401.""" - provider = make_provider() - token = make_jwt(provider=provider) + async def test_failed_validation_401(self, make_jwt): + """Req 10.5: token that fails Cognito validation raises 401.""" + token = make_jwt() mock_validator = MagicMock() - mock_validator.resolve_provider_from_token = AsyncMock(return_value=provider) mock_validator.validate_token = MagicMock( - side_effect=HTTPException(status_code=401, detail="Invalid token signature") + side_effect=HTTPException(status_code=401, detail="Invalid token signature.") ) with patch( - "apis.shared.auth.dependencies._get_generic_validator", + "apis.shared.auth.dependencies._get_cognito_validator", return_value=mock_validator, ), patch( "apis.shared.auth.dependencies._get_user_sync_service", @@ -103,11 +98,11 @@ async def test_failed_validation_401(self, make_jwt, make_provider): @pytest.mark.asyncio async def test_no_validator_500(self, make_jwt): - """Req 3.5: no generic validator available raises 500.""" + """Req 10.6: no Cognito validator available raises 500.""" token = make_jwt() with patch( - "apis.shared.auth.dependencies._get_generic_validator", + "apis.shared.auth.dependencies._get_cognito_validator", return_value=None, ): with pytest.raises(HTTPException) as exc_info: @@ -117,22 +112,27 @@ async def test_no_validator_500(self, make_jwt): assert "Authentication service not configured" in exc_info.value.detail @pytest.mark.asyncio - async def test_no_matching_provider_500(self, make_jwt): - """When resolve_provider_from_token returns None, falls through to 500.""" + async def test_unexpected_exception_401(self, make_jwt): + """Unexpected exception during validation raises 401.""" token = make_jwt() mock_validator = MagicMock() - mock_validator.resolve_provider_from_token = AsyncMock(return_value=None) + mock_validator.validate_token = MagicMock( + side_effect=RuntimeError("unexpected") + ) with patch( - "apis.shared.auth.dependencies._get_generic_validator", + "apis.shared.auth.dependencies._get_cognito_validator", return_value=mock_validator, + ), patch( + "apis.shared.auth.dependencies._get_user_sync_service", + return_value=None, ): with pytest.raises(HTTPException) as exc_info: await get_current_user(credentials=_bearer(token)) - # When provider is None, the if-block is skipped and we hit the 500 - assert exc_info.value.status_code == 500 + assert exc_info.value.status_code == 401 + assert exc_info.value.detail == "Authentication failed." # --------------------------------------------------------------------------- @@ -144,9 +144,8 @@ class TestGetCurrentUserTrusted: """Tests for the get_current_user_trusted dependency.""" @pytest.mark.asyncio - async def test_trusted_decode_success(self, make_jwt, make_provider): - """Req 3.6: valid Bearer token decoded without signature verification, returns User.""" - provider = make_provider() + async def test_trusted_decode_success(self, make_jwt): + """Valid Bearer token decoded without signature verification, returns User.""" token = make_jwt( claims={ "sub": "trusted-user-001", @@ -154,16 +153,9 @@ async def test_trusted_decode_success(self, make_jwt, make_provider): "name": "Trusted User", "roles": ["Admin"], }, - provider=provider, ) - mock_validator = MagicMock() - mock_validator.resolve_provider_from_token = AsyncMock(return_value=provider) - with patch( - "apis.shared.auth.dependencies._get_generic_validator", - return_value=mock_validator, - ), patch( "apis.shared.auth.dependencies._get_user_sync_service", return_value=None, ): @@ -177,22 +169,37 @@ async def test_trusted_decode_success(self, make_jwt, make_provider): assert user.raw_token == token @pytest.mark.asyncio - async def test_trusted_malformed_token(self): - """Req 3.7: malformed token raises 401 with 'Malformed token.'.""" + async def test_trusted_cognito_groups(self, make_jwt): + """Trusted path extracts cognito:groups as roles.""" + token = make_jwt( + claims={ + "sub": "cognito-user-001", + "email": "cognito@example.com", + "name": "Cognito User", + "cognito:groups": ["system_admin", "developer"], + }, + ) + with patch( - "apis.shared.auth.dependencies._get_generic_validator", + "apis.shared.auth.dependencies._get_user_sync_service", return_value=None, ): - with pytest.raises(HTTPException) as exc_info: - await get_current_user_trusted(credentials=_bearer("not.a.jwt")) + user = await get_current_user_trusted(credentials=_bearer(token)) + + assert user.roles == ["system_admin", "developer"] + + @pytest.mark.asyncio + async def test_trusted_malformed_token(self): + """Malformed token raises 401 with 'Malformed token.'.""" + with pytest.raises(HTTPException) as exc_info: + await get_current_user_trusted(credentials=_bearer("not.a.jwt")) assert exc_info.value.status_code == 401 assert exc_info.value.detail == "Malformed token." @pytest.mark.asyncio - async def test_trusted_no_validator_fallback(self, make_jwt, make_provider): - """Req 3.8: no validator falls back to standard OIDC claims (sub, email, name, roles).""" - provider = make_provider() + async def test_trusted_fallback_claims(self, make_jwt): + """Standard OIDC claims (sub, email, name, roles) are extracted correctly.""" token = make_jwt( claims={ "sub": "fallback-user", @@ -200,13 +207,9 @@ async def test_trusted_no_validator_fallback(self, make_jwt, make_provider): "name": "Fallback User", "roles": ["Reader"], }, - provider=provider, ) with patch( - "apis.shared.auth.dependencies._get_generic_validator", - return_value=None, - ), patch( "apis.shared.auth.dependencies._get_user_sync_service", return_value=None, ): @@ -218,52 +221,17 @@ async def test_trusted_no_validator_fallback(self, make_jwt, make_provider): assert user.roles == ["Reader"] @pytest.mark.asyncio - async def test_trusted_missing_user_id(self, make_jwt, make_provider): - """Req 3.9: missing user_id claim raises 401 with 'Invalid user.'.""" - provider = make_provider() - # Create token without 'sub' claim + async def test_trusted_missing_user_id(self, make_jwt): + """Missing sub claim raises 401 with 'Invalid user.'.""" token = make_jwt( claims={ "sub": None, "email": "nouser@example.com", "name": "No User", }, - provider=provider, ) with patch( - "apis.shared.auth.dependencies._get_generic_validator", - return_value=None, - ), patch( - "apis.shared.auth.dependencies._get_user_sync_service", - return_value=None, - ): - with pytest.raises(HTTPException) as exc_info: - await get_current_user_trusted(credentials=_bearer(token)) - - assert exc_info.value.status_code == 401 - assert exc_info.value.detail == "Invalid user." - - @pytest.mark.asyncio - async def test_trusted_missing_user_id_with_provider(self, make_jwt, make_provider): - """Req 3.9 (provider path): missing user_id claim with provider raises 401.""" - provider = make_provider() - token = make_jwt( - claims={ - "sub": None, - "email": "nouser@example.com", - "name": "No User", - }, - provider=provider, - ) - - mock_validator = MagicMock() - mock_validator.resolve_provider_from_token = AsyncMock(return_value=provider) - - with patch( - "apis.shared.auth.dependencies._get_generic_validator", - return_value=mock_validator, - ), patch( "apis.shared.auth.dependencies._get_user_sync_service", return_value=None, ): @@ -292,18 +260,16 @@ class TestGetCurrentUserId: """Tests for the get_current_user_id dependency.""" @pytest.mark.asyncio - async def test_returns_string(self, make_jwt, make_provider, make_user): - """Req 3.10: get_current_user_id returns the user_id string.""" - provider = make_provider() - token = make_jwt(provider=provider) + async def test_returns_string(self, make_jwt, make_user): + """get_current_user_id returns the user_id string.""" + token = make_jwt() expected_user = make_user(user_id="uid-42") mock_validator = MagicMock() - mock_validator.resolve_provider_from_token = AsyncMock(return_value=provider) mock_validator.validate_token = MagicMock(return_value=expected_user) with patch( - "apis.shared.auth.dependencies._get_generic_validator", + "apis.shared.auth.dependencies._get_cognito_validator", return_value=mock_validator, ), patch( "apis.shared.auth.dependencies._get_user_sync_service", diff --git a/backend/tests/auth/test_generic_jwt_validator.py b/backend/tests/auth/test_generic_jwt_validator.py deleted file mode 100644 index 755d63a0..00000000 --- a/backend/tests/auth/test_generic_jwt_validator.py +++ /dev/null @@ -1,586 +0,0 @@ -"""Tests for GenericOIDCJWTValidator. - -Covers: valid RS256 decode, invalid signature, expired token, issuer matching -(exact, Entra ID v1↔v2 cross-version, mismatch), audience validation, scope -enforcement, user_id pattern validation, missing user_id claim, name construction -from first/last claims, roles normalization, email fallback, JWKS client caching, -resolve_provider_from_token, invalidate_cache, dot-notation claim extraction, -and URI-style claim lookup. - -Requirements: 1.1–1.22 -""" - -import time -from unittest.mock import AsyncMock, MagicMock, patch - -import jwt as pyjwt -import pytest -from fastapi import HTTPException - -from apis.shared.auth.generic_jwt_validator import GenericOIDCJWTValidator - - -# --------------------------------------------------------------------------- -# Fixtures -# --------------------------------------------------------------------------- - - -@pytest.fixture -def validator(mock_provider_repo): - """Create a GenericOIDCJWTValidator with a mocked provider repo.""" - return GenericOIDCJWTValidator(provider_repo=mock_provider_repo) - - -@pytest.fixture -def provider_default(make_provider): - """A default test provider.""" - return make_provider() - - -def _inject_jwks(validator, provider, mock_jwks_client): - """Pre-populate the JWKS client cache so validate_token skips real JWKS fetch.""" - validator._jwks_clients[provider.jwks_uri] = mock_jwks_client - - -# --------------------------------------------------------------------------- -# 1.2 – Valid RS256 decode -# --------------------------------------------------------------------------- - - -class TestValidRS256Decode: - """Validates: Requirement 1.2""" - - def test_valid_token_returns_user( - self, validator, mock_jwks_client, make_jwt, provider_default - ): - token = make_jwt(provider=provider_default) - _inject_jwks(validator, provider_default, mock_jwks_client) - - user = validator.validate_token(token, provider_default) - - assert user.email == "test@example.com" - assert user.user_id == "user-001" - assert user.name == "Test User" - assert user.roles == ["User"] - - -# --------------------------------------------------------------------------- -# 1.3 – Invalid signature -# --------------------------------------------------------------------------- - - -class TestInvalidSignature: - """Validates: Requirement 1.3""" - - def test_invalid_signature_raises_401( - self, validator, make_jwt, provider_default - ): - token = make_jwt(provider=provider_default) - # Create a JWKS client that raises InvalidSignatureError - bad_client = MagicMock() - bad_client.get_signing_key_from_jwt = MagicMock( - side_effect=pyjwt.exceptions.InvalidSignatureError("bad sig") - ) - _inject_jwks(validator, provider_default, bad_client) - - with pytest.raises(HTTPException) as exc_info: - validator.validate_token(token, provider_default) - - assert exc_info.value.status_code == 401 - assert "Invalid token signature" in exc_info.value.detail - - -# --------------------------------------------------------------------------- -# 1.4 – Expired token -# --------------------------------------------------------------------------- - - -class TestExpiredToken: - """Validates: Requirement 1.4""" - - def test_expired_token_raises_401( - self, validator, mock_jwks_client, make_jwt, provider_default - ): - token = make_jwt(provider=provider_default, expired=True) - _inject_jwks(validator, provider_default, mock_jwks_client) - - with pytest.raises(HTTPException) as exc_info: - validator.validate_token(token, provider_default) - - assert exc_info.value.status_code == 401 - assert "Token expired" in exc_info.value.detail - - -# --------------------------------------------------------------------------- -# 1.5 – Exact issuer match -# --------------------------------------------------------------------------- - - -class TestExactIssuerMatch: - """Validates: Requirement 1.5""" - - def test_exact_issuer_accepted( - self, validator, mock_jwks_client, make_jwt, make_provider - ): - provider = make_provider(issuer_url="https://auth.example.com/") - token = make_jwt( - claims={"iss": "https://auth.example.com/"}, - provider=provider, - ) - _inject_jwks(validator, provider, mock_jwks_client) - - user = validator.validate_token(token, provider) - assert user.user_id == "user-001" - - -# --------------------------------------------------------------------------- -# 1.6 – Entra ID v1 token ↔ v2 provider -# --------------------------------------------------------------------------- - - -class TestEntraIDV1TokenV2Provider: - """Validates: Requirement 1.6""" - - def test_v1_token_v2_provider_accepted( - self, validator, mock_jwks_client, make_jwt, make_provider - ): - tenant = "my-tenant-id" - provider = make_provider( - issuer_url=f"https://login.microsoftonline.com/{tenant}/v2.0" - ) - token = make_jwt( - claims={"iss": f"https://sts.windows.net/{tenant}/"}, - provider=provider, - ) - _inject_jwks(validator, provider, mock_jwks_client) - - user = validator.validate_token(token, provider) - assert user.user_id == "user-001" - - -# --------------------------------------------------------------------------- -# 1.7 – Entra ID v2 token ↔ v1 provider -# --------------------------------------------------------------------------- - - -class TestEntraIDV2TokenV1Provider: - """Validates: Requirement 1.7""" - - def test_v2_token_v1_provider_accepted( - self, validator, mock_jwks_client, make_jwt, make_provider - ): - tenant = "my-tenant-id" - provider = make_provider( - issuer_url=f"https://sts.windows.net/{tenant}/" - ) - token = make_jwt( - claims={"iss": f"https://login.microsoftonline.com/{tenant}/v2.0"}, - provider=provider, - ) - _inject_jwks(validator, provider, mock_jwks_client) - - user = validator.validate_token(token, provider) - assert user.user_id == "user-001" - - -# --------------------------------------------------------------------------- -# 1.8 – Issuer mismatch rejection -# --------------------------------------------------------------------------- - - -class TestIssuerMismatch: - """Validates: Requirement 1.8""" - - def test_issuer_mismatch_raises_401( - self, validator, mock_jwks_client, make_jwt, make_provider - ): - provider = make_provider(issuer_url="https://auth.example.com/") - token = make_jwt( - claims={"iss": "https://evil.example.com/"}, - provider=provider, - ) - _inject_jwks(validator, provider, mock_jwks_client) - - with pytest.raises(HTTPException) as exc_info: - validator.validate_token(token, provider) - - assert exc_info.value.status_code == 401 - - -# --------------------------------------------------------------------------- -# 1.9 – Audience not in allowed list -# --------------------------------------------------------------------------- - - -class TestAudienceValidation: - """Validates: Requirements 1.9, 1.10""" - - def test_audience_not_allowed_raises_401( - self, validator, mock_jwks_client, make_jwt, make_provider - ): - provider = make_provider( - allowed_audiences=["allowed-client"], - ) - token = make_jwt( - claims={"aud": "wrong-client"}, - provider=provider, - ) - _inject_jwks(validator, provider, mock_jwks_client) - - with pytest.raises(HTTPException) as exc_info: - validator.validate_token(token, provider) - - assert exc_info.value.status_code == 401 - assert "Invalid token audience" in exc_info.value.detail - - # 1.10 – Audience list containing at least one allowed value - def test_audience_list_with_allowed_value_accepted( - self, validator, mock_jwks_client, make_jwt, make_provider - ): - provider = make_provider( - allowed_audiences=["allowed-client"], - ) - token = make_jwt( - claims={"aud": ["other-client", "allowed-client"]}, - provider=provider, - ) - _inject_jwks(validator, provider, mock_jwks_client) - - user = validator.validate_token(token, provider) - assert user.user_id == "user-001" - - -# --------------------------------------------------------------------------- -# 1.11 – Scope enforcement -# --------------------------------------------------------------------------- - - -class TestScopeEnforcement: - """Validates: Requirement 1.11""" - - def test_missing_required_scope_raises_401( - self, validator, mock_jwks_client, make_jwt, make_provider - ): - provider = make_provider(required_scopes=["api.read", "api.write"]) - token = make_jwt( - claims={"scp": "api.read"}, - provider=provider, - ) - _inject_jwks(validator, provider, mock_jwks_client) - - with pytest.raises(HTTPException) as exc_info: - validator.validate_token(token, provider) - - assert exc_info.value.status_code == 401 - assert "Token missing required scope" in exc_info.value.detail - - def test_all_required_scopes_present_accepted( - self, validator, mock_jwks_client, make_jwt, make_provider - ): - provider = make_provider(required_scopes=["api.read", "api.write"]) - token = make_jwt( - claims={"scp": "api.read api.write"}, - provider=provider, - ) - _inject_jwks(validator, provider, mock_jwks_client) - - user = validator.validate_token(token, provider) - assert user.user_id == "user-001" - - -# --------------------------------------------------------------------------- -# 1.12 – user_id pattern validation -# --------------------------------------------------------------------------- - - -class TestUserIdPattern: - """Validates: Requirement 1.12""" - - def test_user_id_not_matching_pattern_raises_401( - self, validator, mock_jwks_client, make_jwt, make_provider - ): - provider = make_provider( - user_id_pattern=r"^[0-9a-f\-]{36}$", # UUID pattern - ) - token = make_jwt( - claims={"sub": "not-a-uuid"}, - provider=provider, - ) - _inject_jwks(validator, provider, mock_jwks_client) - - with pytest.raises(HTTPException) as exc_info: - validator.validate_token(token, provider) - - assert exc_info.value.status_code == 401 - assert "Invalid user" in exc_info.value.detail - - def test_user_id_matching_pattern_accepted( - self, validator, mock_jwks_client, make_jwt, make_provider - ): - provider = make_provider( - user_id_pattern=r"^user-\d+$", - ) - token = make_jwt( - claims={"sub": "user-001"}, - provider=provider, - ) - _inject_jwks(validator, provider, mock_jwks_client) - - user = validator.validate_token(token, provider) - assert user.user_id == "user-001" - - -# --------------------------------------------------------------------------- -# 1.13 – Missing user_id claim -# --------------------------------------------------------------------------- - - -class TestMissingUserId: - """Validates: Requirement 1.13""" - - def test_missing_user_id_claim_raises_401( - self, validator, mock_jwks_client, make_jwt, make_provider - ): - provider = make_provider(user_id_claim="custom_id") - # Token has no "custom_id" claim - token = make_jwt(provider=provider) - _inject_jwks(validator, provider, mock_jwks_client) - - with pytest.raises(HTTPException) as exc_info: - validator.validate_token(token, provider) - - assert exc_info.value.status_code == 401 - assert "Invalid user" in exc_info.value.detail - - -# --------------------------------------------------------------------------- -# 1.14 – Name construction from first/last claims -# --------------------------------------------------------------------------- - - -class TestNameFromFirstLast: - """Validates: Requirement 1.14""" - - def test_name_built_from_first_last_when_name_absent( - self, validator, mock_jwks_client, make_jwt, make_provider - ): - provider = make_provider( - name_claim="name", - first_name_claim="given_name", - last_name_claim="family_name", - ) - # Explicitly set "name" to None so _extract_claim returns None, - # triggering the first_name + last_name fallback. - token = make_jwt( - claims={ - "sub": "user-001", - "email": "jane@example.com", - "name": None, - "given_name": "Jane", - "family_name": "Doe", - "roles": ["User"], - }, - provider=provider, - ) - _inject_jwks(validator, provider, mock_jwks_client) - - user = validator.validate_token(token, provider) - assert user.name == "Jane Doe" - - -# --------------------------------------------------------------------------- -# 1.15 – Roles normalization from string -# --------------------------------------------------------------------------- - - -class TestRolesNormalization: - """Validates: Requirement 1.15""" - - def test_string_roles_normalized_to_list( - self, validator, mock_jwks_client, make_jwt, provider_default - ): - token = make_jwt( - claims={"roles": "Admin"}, - provider=provider_default, - ) - _inject_jwks(validator, provider_default, mock_jwks_client) - - user = validator.validate_token(token, provider_default) - assert user.roles == ["Admin"] - - -# --------------------------------------------------------------------------- -# 1.16 – Email fallback to preferred_username -# --------------------------------------------------------------------------- - - -class TestEmailFallback: - """Validates: Requirement 1.16""" - - def test_email_falls_back_to_preferred_username( - self, validator, mock_jwks_client, make_jwt, provider_default - ): - # Explicitly set "email" to None so _extract_claim returns None, - # triggering the preferred_username fallback. - token = make_jwt( - claims={ - "sub": "user-001", - "email": None, - "preferred_username": "jdoe@example.com", - "name": "J Doe", - "roles": ["User"], - }, - provider=provider_default, - ) - _inject_jwks(validator, provider_default, mock_jwks_client) - - user = validator.validate_token(token, provider_default) - assert user.email == "jdoe@example.com" - - -# --------------------------------------------------------------------------- -# 1.17 – JWKS client caching -# --------------------------------------------------------------------------- - - -class TestJWKSClientCaching: - """Validates: Requirement 1.17""" - - def test_jwks_client_reused_for_same_uri( - self, validator, mock_jwks_client, make_jwt, provider_default - ): - _inject_jwks(validator, provider_default, mock_jwks_client) - - # Call twice - token1 = make_jwt(provider=provider_default) - validator.validate_token(token1, provider_default) - - token2 = make_jwt( - claims={"sub": "user-002", "email": "other@example.com"}, - provider=provider_default, - ) - validator.validate_token(token2, provider_default) - - # The same client instance should be in the cache - assert len(validator._jwks_clients) == 1 - assert provider_default.jwks_uri in validator._jwks_clients - - -# --------------------------------------------------------------------------- -# 1.18, 1.19 – resolve_provider_from_token -# --------------------------------------------------------------------------- - - -class TestResolveProviderFromToken: - """Validates: Requirements 1.18, 1.19""" - - @pytest.mark.asyncio - async def test_resolve_returns_matching_provider( - self, validator, make_jwt, make_provider, mock_provider_repo - ): - provider = make_provider( - issuer_url="https://login.example.com/", - enabled=True, - ) - mock_provider_repo.list_providers = AsyncMock(return_value=[provider]) - token = make_jwt( - claims={"iss": "https://login.example.com/"}, - provider=provider, - ) - - result = await validator.resolve_provider_from_token(token) - - assert result is not None - assert result.provider_id == provider.provider_id - - @pytest.mark.asyncio - async def test_resolve_returns_none_for_unknown_issuer( - self, validator, make_jwt, make_provider, mock_provider_repo - ): - provider = make_provider( - issuer_url="https://login.example.com/", - enabled=True, - ) - mock_provider_repo.list_providers = AsyncMock(return_value=[provider]) - token = make_jwt( - claims={"iss": "https://unknown.example.com/"}, - provider=provider, - ) - - result = await validator.resolve_provider_from_token(token) - - assert result is None - - -# --------------------------------------------------------------------------- -# 1.20 – invalidate_cache -# --------------------------------------------------------------------------- - - -class TestInvalidateCache: - """Validates: Requirement 1.20""" - - def test_invalidate_cache_clears_both_caches( - self, validator, mock_jwks_client, make_jwt, provider_default - ): - # Populate caches - _inject_jwks(validator, provider_default, mock_jwks_client) - validator._issuer_to_provider["https://login.example.com/"] = provider_default - - assert len(validator._jwks_clients) == 1 - assert len(validator._issuer_to_provider) == 1 - - validator.invalidate_cache() - - assert len(validator._jwks_clients) == 0 - assert len(validator._issuer_to_provider) == 0 - - -# --------------------------------------------------------------------------- -# 1.21 – Dot-notation claim extraction -# --------------------------------------------------------------------------- - - -class TestDotNotationClaimExtraction: - """Validates: Requirement 1.21""" - - def test_dot_notation_traverses_nested_dicts(self, validator): - payload = {"address": {"street": "123 Main", "country": "US"}} - result = validator._extract_claim(payload, "address.country") - assert result == "US" - - def test_dot_notation_missing_intermediate_returns_none(self, validator): - payload = {"address": {"street": "123 Main"}} - result = validator._extract_claim(payload, "address.country") - assert result is None - - def test_dot_notation_deep_nesting(self, validator): - payload = {"a": {"b": {"c": "deep_value"}}} - result = validator._extract_claim(payload, "a.b.c") - assert result == "deep_value" - - -# --------------------------------------------------------------------------- -# 1.22 – URI-style claim lookup -# --------------------------------------------------------------------------- - - -class TestURIStyleClaimLookup: - """Validates: Requirement 1.22""" - - def test_uri_claim_direct_lookup(self, validator): - payload = { - "http://schemas.example.com/claims/id": "ext-user-42", - "sub": "user-001", - } - result = validator._extract_claim( - payload, "http://schemas.example.com/claims/id" - ) - assert result == "ext-user-42" - - def test_uri_claim_missing_returns_none(self, validator): - payload = {"sub": "user-001"} - result = validator._extract_claim( - payload, "http://schemas.example.com/claims/missing" - ) - assert result is None diff --git a/backend/tests/auth/test_oidc_auth_service.py b/backend/tests/auth/test_oidc_auth_service.py deleted file mode 100644 index 049a32d2..00000000 --- a/backend/tests/auth/test_oidc_auth_service.py +++ /dev/null @@ -1,269 +0,0 @@ -"""Tests for GenericOIDCAuthService OIDC flow methods. - -Covers: generate_state, build_authorization_url, exchange_code_for_tokens, -refresh_access_token, and build_logout_url. - -Requirements: 10.1–10.10 -""" - -import json -from unittest.mock import AsyncMock, MagicMock, patch -from urllib.parse import parse_qs, urlparse - -import jwt -import pytest - -from apis.app_api.auth.service import GenericOIDCAuthService -from apis.shared.auth.state_store import InMemoryStateStore, OIDCStateData - - -# --------------------------------------------------------------------------- -# Helpers -# --------------------------------------------------------------------------- - - -def _build_service(provider, pkce_enabled=True): - """Create a GenericOIDCAuthService with an InMemoryStateStore.""" - provider.pkce_enabled = pkce_enabled - return GenericOIDCAuthService( - provider=provider, - client_secret="test-secret", - state_store=InMemoryStateStore(), - ) - - -def _make_httpx_response(status_code, json_body): - """Build a mock httpx.Response.""" - resp = MagicMock() - resp.status_code = status_code - resp.json.return_value = json_body - if status_code >= 400: - import httpx as _httpx - - resp.raise_for_status.side_effect = _httpx.HTTPStatusError( - message="error", - request=MagicMock(), - response=resp, - ) - else: - resp.raise_for_status.return_value = None - return resp - - -# --------------------------------------------------------------------------- -# Tests -# --------------------------------------------------------------------------- - - -class TestGenerateState: - """Requirement 10.2: generate_state stores state.""" - - def test_generate_state_stores_state(self, make_provider): - """generate_state should store state in the state store with provider_id, - code_verifier, nonce, and optional redirect_uri.""" - provider = make_provider(pkce_enabled=True) - svc = _build_service(provider, pkce_enabled=True) - - state, code_challenge, nonce = svc.generate_state(redirect_uri="http://localhost/cb") - - # State should be retrievable from the store - is_valid, data = svc.state_store.get_and_delete_state(state) - assert is_valid is True - assert data is not None - assert data.provider_id == provider.provider_id - assert data.nonce == nonce - assert data.redirect_uri == "http://localhost/cb" - # PKCE enabled → code_verifier stored - assert data.code_verifier is not None - - -class TestBuildAuthorizationUrl: - """Requirements 10.3, 10.4: build_authorization_url with/without PKCE.""" - - def test_build_authorization_url_with_pkce(self, make_provider): - """With PKCE enabled, URL should include code_challenge and code_challenge_method.""" - provider = make_provider(pkce_enabled=True) - svc = _build_service(provider, pkce_enabled=True) - - state, code_challenge, nonce = svc.generate_state() - url = svc.build_authorization_url(state, code_challenge, nonce) - - parsed = urlparse(url) - params = parse_qs(parsed.query) - - assert params["code_challenge"] == [code_challenge] - assert params["code_challenge_method"] == ["S256"] - assert params["state"] == [state] - assert params["nonce"] == [nonce] - assert params["client_id"] == [provider.client_id] - - def test_build_authorization_url_without_pkce(self, make_provider): - """With PKCE disabled, URL should omit code_challenge and code_challenge_method.""" - provider = make_provider(pkce_enabled=False) - svc = _build_service(provider, pkce_enabled=False) - - state, code_challenge, nonce = svc.generate_state() - url = svc.build_authorization_url(state, code_challenge, nonce) - - parsed = urlparse(url) - params = parse_qs(parsed.query) - - assert "code_challenge" not in params - assert "code_challenge_method" not in params - assert params["state"] == [state] - assert params["nonce"] == [nonce] - - -class TestExchangeCodeInvalidState: - """Requirement 10.5: exchange_code invalid state 400.""" - - @pytest.mark.asyncio - async def test_exchange_code_invalid_state_raises_400(self, make_provider): - """exchange_code_for_tokens with an unknown state should raise 400.""" - from fastapi import HTTPException - - provider = make_provider() - svc = _build_service(provider) - - with pytest.raises(HTTPException) as exc_info: - await svc.exchange_code_for_tokens(code="auth-code", state="bogus-state") - - assert exc_info.value.status_code == 400 - assert "Invalid or expired state" in exc_info.value.detail - - -class TestExchangeCodeNonceMismatch: - """Requirement 10.6: exchange_code nonce mismatch 400.""" - - @pytest.mark.asyncio - async def test_exchange_code_nonce_mismatch_raises_400(self, make_provider): - """If the ID token nonce doesn't match the stored nonce, raise 400.""" - from fastapi import HTTPException - - provider = make_provider() - svc = _build_service(provider) - - state, _challenge, nonce = svc.generate_state() - - # Build a fake ID token with a WRONG nonce - fake_id_token = jwt.encode({"nonce": "wrong-nonce"}, "secret", algorithm="HS256") - - token_response_body = { - "access_token": "at-123", - "refresh_token": "rt-123", - "id_token": fake_id_token, - "token_type": "Bearer", - "expires_in": 3600, - "scope": "openid", - } - - mock_resp = _make_httpx_response(200, token_response_body) - - with patch("apis.app_api.auth.service.httpx.AsyncClient") as mock_client_cls: - mock_client = AsyncMock() - mock_client.post = AsyncMock(return_value=mock_resp) - mock_client.__aenter__ = AsyncMock(return_value=mock_client) - mock_client.__aexit__ = AsyncMock(return_value=False) - mock_client_cls.return_value = mock_client - - with pytest.raises(HTTPException) as exc_info: - await svc.exchange_code_for_tokens(code="auth-code", state=state) - - assert exc_info.value.status_code == 400 - assert "nonce validation failed" in exc_info.value.detail - - -class TestExchangeCodeSuccess: - """Requirement 10.7: exchange_code success returns token dict.""" - - @pytest.mark.asyncio - async def test_exchange_code_success_returns_token_dict(self, make_provider): - """Successful exchange should return dict with all expected keys.""" - provider = make_provider() - svc = _build_service(provider) - - state, _challenge, nonce = svc.generate_state() - - # Build a fake ID token with the CORRECT nonce - fake_id_token = jwt.encode({"nonce": nonce}, "secret", algorithm="HS256") - - token_response_body = { - "access_token": "at-123", - "refresh_token": "rt-123", - "id_token": fake_id_token, - "token_type": "Bearer", - "expires_in": 3600, - "scope": "openid profile", - } - - mock_resp = _make_httpx_response(200, token_response_body) - - with patch("apis.app_api.auth.service.httpx.AsyncClient") as mock_client_cls: - mock_client = AsyncMock() - mock_client.post = AsyncMock(return_value=mock_resp) - mock_client.__aenter__ = AsyncMock(return_value=mock_client) - mock_client.__aexit__ = AsyncMock(return_value=False) - mock_client_cls.return_value = mock_client - - result = await svc.exchange_code_for_tokens(code="auth-code", state=state) - - assert result["access_token"] == "at-123" - assert result["refresh_token"] == "rt-123" - assert result["id_token"] == fake_id_token - assert result["token_type"] == "Bearer" - assert result["expires_in"] == 3600 - assert result["scope"] == "openid profile" - assert result["provider_id"] == provider.provider_id - - -class TestRefreshAccessToken: - """Requirement 10.8: refresh_access_token 400 response raises 401.""" - - @pytest.mark.asyncio - async def test_refresh_400_raises_401(self, make_provider): - """A 400 from the token endpoint should raise HTTPException 401.""" - from fastapi import HTTPException - - provider = make_provider() - svc = _build_service(provider) - - mock_resp = _make_httpx_response(400, {"error": "invalid_grant"}) - - with patch("apis.app_api.auth.service.httpx.AsyncClient") as mock_client_cls: - mock_client = AsyncMock() - mock_client.post = AsyncMock(return_value=mock_resp) - mock_client.__aenter__ = AsyncMock(return_value=mock_client) - mock_client.__aexit__ = AsyncMock(return_value=False) - mock_client_cls.return_value = mock_client - - with pytest.raises(HTTPException) as exc_info: - await svc.refresh_access_token(refresh_token="expired-rt") - - assert exc_info.value.status_code == 401 - assert "Invalid or expired refresh token" in exc_info.value.detail - - -class TestBuildLogoutUrl: - """Requirements 10.9, 10.10: build_logout_url.""" - - def test_build_logout_url_with_redirect(self, make_provider): - """build_logout_url should append post_logout_redirect_uri as a query param.""" - provider = make_provider(end_session_endpoint="https://login.example.com/logout") - svc = _build_service(provider) - - url = svc.build_logout_url(post_logout_redirect_uri="http://localhost:4200") - - parsed = urlparse(url) - params = parse_qs(parsed.query) - assert parsed.scheme == "https" - assert "login.example.com" in parsed.netloc - assert params["post_logout_redirect_uri"] == ["http://localhost:4200"] - - def test_build_logout_url_no_endpoint_returns_empty(self, make_provider): - """If no end_session_endpoint is configured, return empty string.""" - provider = make_provider(end_session_endpoint=None) - svc = _build_service(provider) - - url = svc.build_logout_url(post_logout_redirect_uri="http://localhost:4200") - - assert url == "" diff --git a/backend/tests/auth/test_pkce.py b/backend/tests/auth/test_pkce.py deleted file mode 100644 index ae80f083..00000000 --- a/backend/tests/auth/test_pkce.py +++ /dev/null @@ -1,59 +0,0 @@ -"""Unit tests for PKCE code verifier and challenge generation. - -Covers: -- Verifier length 43–128 characters (Req 9.2) -- Challenge equals BASE64URL(SHA256(verifier)) with padding stripped (Req 9.3) -- Uniqueness across calls (Req 9.5) -""" - -import base64 -import hashlib - -from apis.app_api.auth.service import generate_pkce_pair - - -class TestVerifierLength: - """Req 9.2: code_verifier is between 43 and 128 characters.""" - - def test_verifier_within_bounds(self): - verifier, _ = generate_pkce_pair() - assert 43 <= len(verifier) <= 128 - - def test_verifier_length_consistent_across_calls(self): - for _ in range(20): - verifier, _ = generate_pkce_pair() - assert 43 <= len(verifier) <= 128 - - -class TestChallengeCorrectness: - """Req 9.3: code_challenge equals BASE64URL(SHA256(code_verifier)) with padding stripped.""" - - def test_challenge_matches_sha256_of_verifier(self): - verifier, challenge = generate_pkce_pair() - - digest = hashlib.sha256(verifier.encode("ascii")).digest() - expected = base64.urlsafe_b64encode(digest).rstrip(b"=").decode("ascii") - - assert challenge == expected - - def test_challenge_has_no_padding(self): - _, challenge = generate_pkce_pair() - assert "=" not in challenge - - def test_challenge_uses_url_safe_alphabet(self): - """BASE64URL uses A-Z, a-z, 0-9, '-', '_' only.""" - _, challenge = generate_pkce_pair() - allowed = set("ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-_") - assert all(c in allowed for c in challenge) - - -class TestUniqueness: - """Req 9.5: generate_pkce_pair() produces unique verifiers each time.""" - - def test_verifiers_are_unique(self): - verifiers = {generate_pkce_pair()[0] for _ in range(50)} - assert len(verifiers) == 50 - - def test_challenges_are_unique(self): - challenges = {generate_pkce_pair()[1] for _ in range(50)} - assert len(challenges) == 50 diff --git a/backend/tests/auth/test_rbac.py b/backend/tests/auth/test_rbac.py index 779cbb22..509b8f2a 100644 --- a/backend/tests/auth/test_rbac.py +++ b/backend/tests/auth/test_rbac.py @@ -1,179 +1,125 @@ -"""Tests for RBAC role-checking utilities. +"""Tests for AppRole-based RBAC utilities. -Covers require_roles (OR-logic), require_all_roles (AND-logic), -has_any_role, has_all_roles, predefined checkers, and edge cases. +Covers require_app_roles, require_admin, and fail-closed behavior. Requirements: 4.1–4.12 """ import pytest +from unittest.mock import AsyncMock, MagicMock from fastapi import HTTPException -from apis.shared.auth.rbac import ( - has_all_roles, - has_any_role, - require_admin, - require_all_roles, - require_roles, -) +from apis.shared.auth.rbac import require_app_roles, require_admin +from apis.shared.rbac.models import UserEffectivePermissions # --------------------------------------------------------------------------- -# require_roles — OR logic +# Helpers # --------------------------------------------------------------------------- - -class TestRequireRoles: - """Tests for require_roles() OR-logic dependency.""" - - @pytest.mark.asyncio - async def test_or_logic_grant(self, make_user): - """User with one of the required roles is granted access (4.2).""" - user = make_user(roles=["Admin", "Viewer"]) - checker = require_roles("Admin", "SuperAdmin") - result = await checker(user=user) - assert result is user - - @pytest.mark.asyncio - async def test_or_logic_deny(self, make_user): - """User with none of the required roles is denied with 403 (4.3).""" - user = make_user(roles=["Viewer"]) - checker = require_roles("Admin", "SuperAdmin") - with pytest.raises(HTTPException) as exc_info: - await checker(user=user) - assert exc_info.value.status_code == 403 - assert "Required roles" in exc_info.value.detail - - @pytest.mark.asyncio - async def test_empty_roles_403(self, make_user): - """User with empty roles list gets 403 with specific message (4.6).""" - user = make_user(roles=[]) - checker = require_roles("Admin") - with pytest.raises(HTTPException) as exc_info: - await checker(user=user) - assert exc_info.value.status_code == 403 - assert exc_info.value.detail == "User has no assigned roles." +def _mock_permissions(app_roles: list[str]) -> UserEffectivePermissions: + """Build a UserEffectivePermissions with the given AppRoles.""" + return UserEffectivePermissions( + user_id="user-001", + app_roles=app_roles, + tools=["*"] if "system_admin" in app_roles else [], + models=["*"] if "system_admin" in app_roles else [], + quota_tier=None, + resolved_at="2025-01-01T00:00:00Z", + ) # --------------------------------------------------------------------------- -# require_all_roles — AND logic +# require_app_roles # --------------------------------------------------------------------------- -class TestRequireAllRoles: - """Tests for require_all_roles() AND-logic dependency.""" +class TestRequireAppRoles: + """Tests for require_app_roles() — AppRole-based OR-logic dependency.""" + + @pytest.fixture(autouse=True) + def _patch_service(self, monkeypatch): + self.mock_service = MagicMock() + self.mock_service.resolve_user_permissions = AsyncMock() + import apis.shared.rbac.service as svc_mod + monkeypatch.setattr(svc_mod, "_service_instance", self.mock_service) @pytest.mark.asyncio - async def test_and_logic_grant(self, make_user): - """User with all required roles is granted access (4.4).""" - user = make_user(roles=["Admin", "Security", "Viewer"]) - checker = require_all_roles("Admin", "Security") + async def test_matching_app_role_grants_access(self, make_user): + """User with a matching AppRole is granted access.""" + self.mock_service.resolve_user_permissions.return_value = _mock_permissions(["editor"]) + checker = require_app_roles("editor", "admin") + user = make_user(roles=["some_jwt_group"]) result = await checker(user=user) assert result is user @pytest.mark.asyncio - async def test_and_logic_deny_with_missing_detail(self, make_user): - """User missing a role is denied with 403 listing missing roles (4.5).""" - user = make_user(roles=["Admin"]) - checker = require_all_roles("Admin", "Security") + async def test_no_matching_app_role_denied(self, make_user): + """User without any matching AppRole gets 403.""" + self.mock_service.resolve_user_permissions.return_value = _mock_permissions(["default"]) + checker = require_app_roles("editor", "admin") + user = make_user(roles=["some_jwt_group"]) with pytest.raises(HTTPException) as exc_info: await checker(user=user) assert exc_info.value.status_code == 403 - assert "Security" in exc_info.value.detail - assert "Missing required roles" in exc_info.value.detail @pytest.mark.asyncio - async def test_empty_roles_403(self, make_user): - """User with empty roles list gets 403 with specific message (4.6).""" - user = make_user(roles=[]) - checker = require_all_roles("Admin", "Security") + async def test_service_failure_denies_access(self, make_user): + """If AppRoleService raises, access is denied (fail-closed).""" + self.mock_service.resolve_user_permissions.side_effect = RuntimeError("DB down") + checker = require_app_roles("editor") + user = make_user(roles=["some_jwt_group"]) with pytest.raises(HTTPException) as exc_info: await checker(user=user) assert exc_info.value.status_code == 403 - assert exc_info.value.detail == "User has no assigned roles." - - -# --------------------------------------------------------------------------- -# has_any_role — helper -# --------------------------------------------------------------------------- - - -class TestHasAnyRole: - """Tests for has_any_role() helper function.""" - - def test_true_when_matching(self, make_user): - """Returns True when user has at least one matching role (4.7).""" - user = make_user(roles=["Faculty", "Viewer"]) - assert has_any_role(user, "Admin", "Faculty") is True - - def test_false_when_no_match(self, make_user): - """Returns False when user has no matching role (4.8).""" - user = make_user(roles=["Viewer"]) - assert has_any_role(user, "Admin") is False - - def test_empty_roles_returns_false(self, make_user): - """Returns False when user has empty roles list (4.11).""" - user = make_user(roles=[]) - assert has_any_role(user, "Admin") is False - - -# --------------------------------------------------------------------------- -# has_all_roles — helper -# --------------------------------------------------------------------------- - - -class TestHasAllRoles: - """Tests for has_all_roles() helper function.""" - - def test_true_when_all_present(self, make_user): - """Returns True when user has all specified roles (4.9).""" - user = make_user(roles=["Admin", "Security", "Viewer"]) - assert has_all_roles(user, "Admin", "Security") is True - - def test_false_when_missing_one(self, make_user): - """Returns False when user is missing at least one role (4.10).""" - user = make_user(roles=["Admin"]) - assert has_all_roles(user, "Admin", "Security") is False - - def test_empty_roles_returns_false(self, make_user): - """Returns False when user has empty roles list (4.11).""" - user = make_user(roles=[]) - assert has_all_roles(user, "Admin") is False # --------------------------------------------------------------------------- -# Predefined checkers +# require_admin (predefined checker) # --------------------------------------------------------------------------- class TestRequireAdmin: - """Tests for the predefined require_admin checker (4.12).""" + """Tests for the predefined require_admin checker.""" + + @pytest.fixture(autouse=True) + def _patch_service(self, monkeypatch): + self.mock_service = MagicMock() + self.mock_service.resolve_user_permissions = AsyncMock() + import apis.shared.rbac.service as svc_mod + monkeypatch.setattr(svc_mod, "_service_instance", self.mock_service) @pytest.mark.asyncio - async def test_admin_role_granted(self, make_user): - """User with Admin role passes require_admin.""" - user = make_user(roles=["Admin"]) + async def test_system_admin_granted(self, make_user): + """User whose JWT maps to system_admin AppRole passes.""" + self.mock_service.resolve_user_permissions.return_value = _mock_permissions(["system_admin"]) + user = make_user(roles=["system_admin"]) result = await require_admin(user=user) assert result is user @pytest.mark.asyncio - async def test_superadmin_role_granted(self, make_user): - """User with SuperAdmin role passes require_admin.""" - user = make_user(roles=["SuperAdmin"]) - result = await require_admin(user=user) - assert result is user + async def test_non_admin_denied(self, make_user): + """User without system_admin AppRole is denied.""" + self.mock_service.resolve_user_permissions.return_value = _mock_permissions(["default"]) + user = make_user(roles=["Viewer"]) + with pytest.raises(HTTPException) as exc_info: + await require_admin(user=user) + assert exc_info.value.status_code == 403 @pytest.mark.asyncio - async def test_dotnetdevelopers_role_granted(self, make_user): - """User with DotNetDevelopers role passes require_admin.""" - user = make_user(roles=["DotNetDevelopers"]) - result = await require_admin(user=user) - assert result is user + async def test_no_roles_denied(self, make_user): + """User with no resolved AppRoles is denied.""" + self.mock_service.resolve_user_permissions.return_value = _mock_permissions([]) + user = make_user(roles=[]) + with pytest.raises(HTTPException) as exc_info: + await require_admin(user=user) + assert exc_info.value.status_code == 403 @pytest.mark.asyncio - async def test_non_admin_denied(self, make_user): - """User without any admin role is denied.""" - user = make_user(roles=["Viewer"]) + async def test_service_failure_denies(self, make_user): + """If AppRoleService raises, access is denied (fail-closed).""" + self.mock_service.resolve_user_permissions.side_effect = RuntimeError("DB down") + user = make_user(roles=["system_admin"]) with pytest.raises(HTTPException) as exc_info: await require_admin(user=user) assert exc_info.value.status_code == 403 diff --git a/backend/tests/rbac/test_app_role_admin_service.py b/backend/tests/rbac/test_app_role_admin_service.py index 0cb42e0b..5a63dd24 100644 --- a/backend/tests/rbac/test_app_role_admin_service.py +++ b/backend/tests/rbac/test_app_role_admin_service.py @@ -122,21 +122,27 @@ async def test_create_role_duplicate_raises(service, mock_app_role_repo, admin): # --------------------------------------------------------------------------- @pytest.mark.asyncio -async def test_update_system_admin_protected_fields_raises( +async def test_update_system_admin_protected_fields_stripped( service, mock_app_role_repo, make_app_role, admin ): - """Updating protected fields on system_admin raises ValueError.""" + """Updating protected fields on system_admin silently strips them.""" system_admin_role = make_app_role( role_id="system_admin", display_name="System Admin", is_system_role=True, ) mock_app_role_repo.get_role.return_value = system_admin_role + mock_app_role_repo.update_role.return_value = system_admin_role - updates = AppRoleUpdate(priority=999) + # priority is a protected field — should be silently stripped + updates = AppRoleUpdate(priority=999, display_name="Updated Admin") - with pytest.raises(ValueError, match="protected fields"): - await service.update_role("system_admin", updates, admin) + result = await service.update_role("system_admin", updates, admin) + assert result is not None + # display_name (allowed) should have been applied + assert result.display_name == "Updated Admin" + # priority (protected) should NOT have changed + assert result.priority != 999 # --------------------------------------------------------------------------- diff --git a/backend/tests/routes/test_auth.py b/backend/tests/routes/test_auth.py index 00255296..be458fa5 100644 --- a/backend/tests/routes/test_auth.py +++ b/backend/tests/routes/test_auth.py @@ -2,16 +2,14 @@ Endpoints under test: - GET /auth/providers → 200 with provider list (public, no auth) -- POST /auth/token → 200 with tokens on valid exchange -- POST /auth/token → 400 on invalid/expired state -Requirements: 6.1, 6.2, 6.3, 6.4 +Requirements: 6.1, 6.2 """ from unittest.mock import AsyncMock, MagicMock, patch import pytest -from fastapi import FastAPI, HTTPException +from fastapi import FastAPI from fastapi.testclient import TestClient from apis.app_api.auth.routes import router @@ -115,115 +113,3 @@ def test_returns_200_with_empty_list_on_exception(self, client): assert resp.status_code == 200 assert resp.json()["providers"] == [] - - -# --------------------------------------------------------------------------- -# Requirement 6.3: Valid auth callback returns tokens -# --------------------------------------------------------------------------- - - -class TestExchangeToken: - """POST /auth/token exchanges authorization code for tokens.""" - - def test_valid_exchange_returns_tokens(self, client): - """Req 6.3: Should return 200 with tokens for valid code+state.""" - mock_service = MagicMock() - mock_service.exchange_code_for_tokens = AsyncMock( - return_value={ - "access_token": "at-123", - "refresh_token": "rt-456", - "id_token": "id-789", - "token_type": "Bearer", - "expires_in": 3600, - "scope": "openid profile", - } - ) - - with patch( - "apis.app_api.auth.routes._peek_provider_from_state", - return_value="test-provider", - ), patch( - "apis.app_api.auth.routes.get_generic_auth_service", - new_callable=AsyncMock, - return_value=mock_service, - ): - resp = client.post( - "/auth/token", - json={"code": "auth-code", "state": "valid-state"}, - ) - - assert resp.status_code == 200 - body = resp.json() - assert body["access_token"] == "at-123" - assert body["refresh_token"] == "rt-456" - assert body["id_token"] == "id-789" - assert body["token_type"] == "Bearer" - assert body["expires_in"] == 3600 - - -# --------------------------------------------------------------------------- -# Requirement 6.4: Invalid/expired callback returns 400 or 401 -# --------------------------------------------------------------------------- - - -class TestExchangeTokenErrors: - """POST /auth/token rejects invalid or expired callbacks.""" - - def test_invalid_state_returns_400(self, client): - """Req 6.4: Should return 400 when state cannot resolve to a provider.""" - with patch( - "apis.app_api.auth.routes._peek_provider_from_state", - return_value=None, - ): - resp = client.post( - "/auth/token", - json={"code": "auth-code", "state": "bogus-state"}, - ) - - assert resp.status_code == 400 - - def test_expired_state_returns_400(self, client): - """Req 6.4: Should return 400 when exchange raises HTTPException.""" - mock_service = MagicMock() - mock_service.exchange_code_for_tokens = AsyncMock( - side_effect=HTTPException( - status_code=400, detail="Invalid or expired state" - ), - ) - - with patch( - "apis.app_api.auth.routes._peek_provider_from_state", - return_value="test-provider", - ), patch( - "apis.app_api.auth.routes.get_generic_auth_service", - new_callable=AsyncMock, - return_value=mock_service, - ): - resp = client.post( - "/auth/token", - json={"code": "auth-code", "state": "expired-state"}, - ) - - assert resp.status_code == 400 - - def test_exchange_generic_error_returns_400(self, client): - """Req 6.4: Should return 400 when exchange raises unexpected error.""" - mock_service = MagicMock() - mock_service.exchange_code_for_tokens = AsyncMock( - side_effect=RuntimeError("Connection refused"), - ) - - with patch( - "apis.app_api.auth.routes._peek_provider_from_state", - return_value="test-provider", - ), patch( - "apis.app_api.auth.routes.get_generic_auth_service", - new_callable=AsyncMock, - return_value=mock_service, - ): - resp = client.post( - "/auth/token", - json={"code": "auth-code", "state": "some-state"}, - ) - - assert resp.status_code == 400 diff --git a/backend/tests/routes/test_pbt_auth_sweep.py b/backend/tests/routes/test_pbt_auth_sweep.py index 2bc84365..b9b8bd3b 100644 --- a/backend/tests/routes/test_pbt_auth_sweep.py +++ b/backend/tests/routes/test_pbt_auth_sweep.py @@ -42,6 +42,8 @@ "/auth/logout", "/oauth/callback", "/chat/api-converse", + "/system/status", + "/system/first-boot", "/openapi.json", "/docs", "/docs/oauth2-redirect", @@ -116,24 +118,26 @@ def _dummy_path(path: str) -> str: # Validates: Requirements 7.2, 7.3 # --------------------------------------------------------------------------- -# Roles that grant admin access (from require_admin definition) -ADMIN_ROLES = {"Admin", "SuperAdmin", "DotNetDevelopers"} - -# Strategy: generate a list of role strings that does NOT contain any admin role. -NON_ADMIN_ROLE_NAMES = st.text( - alphabet=st.characters(whitelist_categories=("L",)), - min_size=1, - max_size=20, -).filter(lambda r: r not in ADMIN_ROLES) - -non_admin_roles_strategy = st.lists(NON_ADMIN_ROLE_NAMES, min_size=0, max_size=5) +# Strategy: generate a list of arbitrary role strings for Hypothesis. +non_admin_roles_strategy = st.lists( + st.text( + alphabet=st.characters(whitelist_categories=("L",)), + min_size=1, + max_size=20, + ), + min_size=0, + max_size=5, +) class TestNonAdminRoleRejection: """Property 4: Non-admin role rejection. - For any User whose roles do not contain "Admin", "SuperAdmin", or - "DotNetDevelopers", admin endpoints return HTTP 403. + For any User whose JWT roles do not map to the ``system_admin`` AppRole, + admin endpoints return HTTP 403. + + Since ``require_admin`` now resolves permissions via the AppRoleService, + we mock the service to return no admin AppRoles for the generated users. """ @given(roles=non_admin_roles_strategy) @@ -146,10 +150,8 @@ def test_non_admin_roles_get_403(self, roles): **Validates: Requirements 7.2, 7.3** """ - # Build a minimal app with just the admin router so we test the - # real require_admin dependency chain without side-effects from - # the full app's lifespan. from apis.app_api.admin.routes import router as admin_router + from apis.shared.rbac.models import UserEffectivePermissions app = FastAPI() app.include_router(admin_router) @@ -163,10 +165,25 @@ def test_non_admin_roles_get_403(self, roles): ) app.dependency_overrides[get_current_user] = lambda: user - client = TestClient(app, raise_server_exceptions=False) + # Mock AppRoleService to return no admin AppRoles (simulates + # JWT roles that don't map to system_admin in DynamoDB) + mock_service = AsyncMock() + mock_service.resolve_user_permissions = AsyncMock( + return_value=UserEffectivePermissions( + user_id="prop4-user", + app_roles=["default"], + tools=[], + models=[], + quota_tier=None, + resolved_at="2025-01-01T00:00:00Z", + ) + ) + + with patch("apis.shared.rbac.service._service_instance", mock_service): + client = TestClient(app, raise_server_exceptions=False) - # Pick a representative admin endpoint — GET /admin/managed-models - resp = client.get("/admin/managed-models") + # Pick a representative admin endpoint — GET /admin/managed-models + resp = client.get("/admin/managed-models") assert resp.status_code == 403, ( f"Expected 403 for roles={roles}, got {resp.status_code}: {resp.text}" diff --git a/backend/tests/routes/test_pbt_request_validation.py b/backend/tests/routes/test_pbt_request_validation.py index 9fea6c7a..421c4fb5 100644 --- a/backend/tests/routes/test_pbt_request_validation.py +++ b/backend/tests/routes/test_pbt_request_validation.py @@ -284,8 +284,8 @@ def test_invalid_session_id_returns_404_or_422(self, session_id, sessions_app): # URL-encode the session_id to handle special characters resp = client.get(f"/sessions/{session_id}/metadata") - assert resp.status_code in (404, 422), ( - f"Expected 404 or 422 for session_id '{session_id}', got {resp.status_code}" + assert resp.status_code in (404, 405, 422), ( + f"Expected 404, 405, or 422 for session_id '{session_id}', got {resp.status_code}" ) diff --git a/backend/tests/shared/test_auth_providers_extended.py b/backend/tests/shared/test_auth_providers_extended.py index b025a1b1..fa9394f0 100644 --- a/backend/tests/shared/test_auth_providers_extended.py +++ b/backend/tests/shared/test_auth_providers_extended.py @@ -44,6 +44,7 @@ async def test_create_with_auto_discovery(self): create = self._make_create( authorization_endpoint=None, token_endpoint=None, jwks_uri=None, ) + create.auto_discover = True discovery_data = { "issuer": "https://auth.example.com", "authorization_endpoint": "https://auth.example.com/authorize", diff --git a/backend/tests/shared/test_cognito_idp_service.py b/backend/tests/shared/test_cognito_idp_service.py new file mode 100644 index 00000000..1b91c6f3 --- /dev/null +++ b/backend/tests/shared/test_cognito_idp_service.py @@ -0,0 +1,1177 @@ +"""Tests for Cognito Identity Provider service and create_provider Cognito integration. + +Covers: +- CognitoIdentityProviderService CRUD operations +- AuthProviderService.create_provider Cognito registration with rollback +- cognitoProviderName stored in DynamoDB +""" + +import json +import pytest +import boto3 +from moto import mock_aws +from unittest.mock import MagicMock, patch +from botocore.exceptions import ClientError + +from apis.shared.auth_providers.models import AuthProviderCreate + +AWS_REGION = "us-east-1" +USER_POOL_NAME = "test-pool" + + +def _make_create(**kw): + defaults = dict( + provider_id="okta-1", + display_name="Okta", + provider_type="oidc", + issuer_url="https://okta.example.com", + client_id="cid", + client_secret="secret", + enabled=True, + authorization_endpoint="https://okta.example.com/authorize", + token_endpoint="https://okta.example.com/token", + jwks_uri="https://okta.example.com/keys", + ) + defaults.update(kw) + return AuthProviderCreate(**defaults) + + +@pytest.fixture() +def aws_env(monkeypatch): + """Activate moto mock_aws and set default env vars.""" + monkeypatch.setenv("AWS_DEFAULT_REGION", AWS_REGION) + monkeypatch.setenv("AWS_ACCESS_KEY_ID", "testing") + monkeypatch.setenv("AWS_SECRET_ACCESS_KEY", "testing") + monkeypatch.setenv("AWS_SECURITY_TOKEN", "testing") + monkeypatch.setenv("AWS_SESSION_TOKEN", "testing") + with mock_aws(): + yield + + +@pytest.fixture() +def cognito_pool(aws_env): + """Create a Cognito User Pool and App Client for testing.""" + client = boto3.client("cognito-idp", region_name=AWS_REGION) + + pool = client.create_user_pool( + PoolName=USER_POOL_NAME, + Schema=[ + {"Name": "email", "AttributeDataType": "String", "Required": True}, + ], + ) + pool_id = pool["UserPool"]["Id"] + + app_client = client.create_user_pool_client( + UserPoolId=pool_id, + ClientName="test-app-client", + GenerateSecret=False, + SupportedIdentityProviders=["COGNITO"], + AllowedOAuthFlows=["code"], + AllowedOAuthScopes=["openid", "profile", "email"], + CallbackURLs=["http://localhost:4200/auth/callback"], + ) + client_id = app_client["UserPoolClient"]["ClientId"] + + return {"pool_id": pool_id, "client_id": client_id, "boto_client": client} + + +@pytest.fixture() +def cognito_idp_service(cognito_pool): + """Create a CognitoIdentityProviderService with the moto pool.""" + from apis.shared.auth_providers.cognito_idp_service import ( + CognitoIdentityProviderService, + ) + + return CognitoIdentityProviderService( + user_pool_id=cognito_pool["pool_id"], + app_client_id=cognito_pool["client_id"], + region=AWS_REGION, + ) + + +@pytest.fixture() +def auth_providers_table(aws_env, monkeypatch): + """Create the auth providers DynamoDB table.""" + ddb = boto3.client("dynamodb", region_name=AWS_REGION) + name = "test-auth-providers" + monkeypatch.setenv("DYNAMODB_AUTH_PROVIDERS_TABLE_NAME", name) + ddb.create_table( + TableName=name, + KeySchema=[ + {"AttributeName": "PK", "KeyType": "HASH"}, + {"AttributeName": "SK", "KeyType": "RANGE"}, + ], + AttributeDefinitions=[ + {"AttributeName": "PK", "AttributeType": "S"}, + {"AttributeName": "SK", "AttributeType": "S"}, + {"AttributeName": "GSI1PK", "AttributeType": "S"}, + ], + GlobalSecondaryIndexes=[ + { + "IndexName": "EnabledProvidersIndex", + "KeySchema": [{"AttributeName": "GSI1PK", "KeyType": "HASH"}], + "Projection": {"ProjectionType": "ALL"}, + } + ], + BillingMode="PAY_PER_REQUEST", + ) + return boto3.resource("dynamodb", region_name=AWS_REGION).Table(name) + + +@pytest.fixture() +def secrets_manager(aws_env, monkeypatch): + """Create Secrets Manager secret for auth provider secrets.""" + sm = boto3.client("secretsmanager", region_name=AWS_REGION) + sm.create_secret(Name="auth-provider-secrets", SecretString="{}") + monkeypatch.setenv("AUTH_PROVIDER_SECRETS_ARN", "auth-provider-secrets") + return sm + + +@pytest.fixture() +def auth_repo(auth_providers_table, secrets_manager): + """Create an AuthProviderRepository.""" + from apis.shared.auth_providers.repository import AuthProviderRepository + + return AuthProviderRepository( + table_name="test-auth-providers", + secrets_arn="auth-provider-secrets", + region=AWS_REGION, + ) + + +@pytest.fixture() +def service_with_cognito(auth_repo, cognito_idp_service): + """Create an AuthProviderService with Cognito IdP integration.""" + from apis.shared.auth_providers.service import AuthProviderService + + return AuthProviderService( + repository=auth_repo, + cognito_idp_service=cognito_idp_service, + ) + + +# =================================================================== +# CognitoIdentityProviderService unit tests +# =================================================================== + + +class TestCognitoIdentityProviderService: + def test_enabled(self, cognito_idp_service): + assert cognito_idp_service.enabled is True + + def test_disabled_when_no_pool(self): + from apis.shared.auth_providers.cognito_idp_service import ( + CognitoIdentityProviderService, + ) + + svc = CognitoIdentityProviderService(user_pool_id=None, app_client_id=None) + assert svc.enabled is False + + def test_create_identity_provider(self, cognito_idp_service, cognito_pool): + cognito_idp_service.create_identity_provider( + provider_name="okta-1", + issuer_url="https://okta.example.com", + client_id="cid", + client_secret="secret", + ) + # Verify it was created + client = cognito_pool["boto_client"] + resp = client.describe_identity_provider( + UserPoolId=cognito_pool["pool_id"], + ProviderName="okta-1", + ) + assert resp["IdentityProvider"]["ProviderName"] == "okta-1" + assert resp["IdentityProvider"]["ProviderType"] == "OIDC" + details = resp["IdentityProvider"]["ProviderDetails"] + assert details["oidc_issuer"] == "https://okta.example.com" + assert details["client_id"] == "cid" + + def test_create_identity_provider_with_custom_mapping( + self, cognito_idp_service, cognito_pool + ): + custom_mapping = { + "email": "mail", + "name": "displayName", + "custom:provider_sub": "sub", + } + cognito_idp_service.create_identity_provider( + provider_name="custom-1", + issuer_url="https://custom.example.com", + client_id="cid", + client_secret="secret", + attribute_mapping=custom_mapping, + ) + client = cognito_pool["boto_client"] + resp = client.describe_identity_provider( + UserPoolId=cognito_pool["pool_id"], + ProviderName="custom-1", + ) + mapping = resp["IdentityProvider"]["AttributeMapping"] + assert mapping["email"] == "mail" + assert mapping["name"] == "displayName" + + def test_delete_identity_provider(self, cognito_idp_service, cognito_pool): + cognito_idp_service.create_identity_provider( + provider_name="to-delete", + issuer_url="https://example.com", + client_id="cid", + client_secret="secret", + ) + cognito_idp_service.delete_identity_provider("to-delete") + # Verify it's gone + client = cognito_pool["boto_client"] + with pytest.raises(ClientError) as exc_info: + client.describe_identity_provider( + UserPoolId=cognito_pool["pool_id"], + ProviderName="to-delete", + ) + assert exc_info.value.response["Error"]["Code"] == "ResourceNotFoundException" + + def test_delete_nonexistent_is_idempotent(self, cognito_idp_service): + # Should not raise + cognito_idp_service.delete_identity_provider("nonexistent-provider") + + def test_add_provider_to_app_client(self, cognito_idp_service, cognito_pool): + # First create the IdP + cognito_idp_service.create_identity_provider( + provider_name="okta-1", + issuer_url="https://okta.example.com", + client_id="cid", + client_secret="secret", + ) + cognito_idp_service.add_provider_to_app_client("okta-1") + + providers = cognito_idp_service.get_supported_identity_providers() + assert "COGNITO" in providers + assert "okta-1" in providers + + def test_add_duplicate_provider_is_idempotent( + self, cognito_idp_service, cognito_pool + ): + cognito_idp_service.create_identity_provider( + provider_name="okta-1", + issuer_url="https://okta.example.com", + client_id="cid", + client_secret="secret", + ) + cognito_idp_service.add_provider_to_app_client("okta-1") + cognito_idp_service.add_provider_to_app_client("okta-1") + + providers = cognito_idp_service.get_supported_identity_providers() + assert providers.count("okta-1") == 1 + + def test_remove_provider_from_app_client( + self, cognito_idp_service, cognito_pool + ): + cognito_idp_service.create_identity_provider( + provider_name="okta-1", + issuer_url="https://okta.example.com", + client_id="cid", + client_secret="secret", + ) + cognito_idp_service.add_provider_to_app_client("okta-1") + cognito_idp_service.remove_provider_from_app_client("okta-1") + + providers = cognito_idp_service.get_supported_identity_providers() + assert "okta-1" not in providers + assert "COGNITO" in providers + + def test_get_supported_identity_providers_default(self, cognito_idp_service): + providers = cognito_idp_service.get_supported_identity_providers() + assert "COGNITO" in providers + + +# =================================================================== +# AuthProviderService create_provider with Cognito integration +# =================================================================== + + +class TestCreateProviderWithCognito: + @pytest.mark.asyncio + async def test_create_registers_in_cognito( + self, service_with_cognito, cognito_pool + ): + """Creating a provider should register it in Cognito and store cognitoProviderName.""" + data = _make_create() + provider = await service_with_cognito.create_provider(data, created_by="admin@test.com") + + assert provider.cognito_provider_name == "okta-1" + + # Verify in Cognito + client = cognito_pool["boto_client"] + resp = client.describe_identity_provider( + UserPoolId=cognito_pool["pool_id"], + ProviderName="okta-1", + ) + assert resp["IdentityProvider"]["ProviderType"] == "OIDC" + + @pytest.mark.asyncio + async def test_create_adds_to_app_client( + self, service_with_cognito, cognito_idp_service + ): + """Creating a provider should add it to the App Client's supported providers.""" + data = _make_create() + await service_with_cognito.create_provider(data) + + providers = cognito_idp_service.get_supported_identity_providers() + assert "okta-1" in providers + assert "COGNITO" in providers + + @pytest.mark.asyncio + async def test_create_stores_cognito_provider_name_in_dynamo( + self, service_with_cognito, auth_providers_table + ): + """The DynamoDB item should contain cognitoProviderName.""" + data = _make_create() + await service_with_cognito.create_provider(data) + + resp = auth_providers_table.get_item( + Key={"PK": "AUTH_PROVIDER#okta-1", "SK": "AUTH_PROVIDER#okta-1"} + ) + item = resp["Item"] + assert item["cognitoProviderName"] == "okta-1" + + @pytest.mark.asyncio + async def test_create_attribute_mapping_uses_claim_config( + self, service_with_cognito, cognito_pool + ): + """Attribute mapping should reflect the provider's claim configuration.""" + data = _make_create( + email_claim="mail", + name_claim="displayName", + first_name_claim="firstName", + last_name_claim="lastName", + picture_claim="avatar", + ) + await service_with_cognito.create_provider(data) + + client = cognito_pool["boto_client"] + resp = client.describe_identity_provider( + UserPoolId=cognito_pool["pool_id"], + ProviderName="okta-1", + ) + mapping = resp["IdentityProvider"]["AttributeMapping"] + assert mapping["email"] == "mail" + assert mapping["name"] == "displayName" + assert mapping["given_name"] == "firstName" + assert mapping["family_name"] == "lastName" + assert mapping["picture"] == "avatar" + assert mapping["custom:provider_sub"] == "sub" + + @pytest.mark.asyncio + async def test_rollback_on_update_client_failure( + self, auth_repo, cognito_pool + ): + """If UpdateUserPoolClient fails, the identity provider should be rolled back.""" + from apis.shared.auth_providers.cognito_idp_service import ( + CognitoIdentityProviderService, + ) + from apis.shared.auth_providers.service import AuthProviderService + + svc = CognitoIdentityProviderService( + user_pool_id=cognito_pool["pool_id"], + app_client_id=cognito_pool["client_id"], + region=AWS_REGION, + ) + + # Patch add_provider_to_app_client to fail + original_add = svc.add_provider_to_app_client + def failing_add(name): + raise ClientError( + {"Error": {"Code": "InvalidParameterException", "Message": "test failure"}}, + "UpdateUserPoolClient", + ) + svc.add_provider_to_app_client = failing_add + + service = AuthProviderService(repository=auth_repo, cognito_idp_service=svc) + + from fastapi import HTTPException + with pytest.raises(HTTPException) as exc_info: + await service.create_provider(_make_create()) + assert exc_info.value.status_code == 502 + + # Verify the identity provider was rolled back (deleted from Cognito) + client = cognito_pool["boto_client"] + with pytest.raises(ClientError) as exc_info: + client.describe_identity_provider( + UserPoolId=cognito_pool["pool_id"], + ProviderName="okta-1", + ) + assert exc_info.value.response["Error"]["Code"] == "ResourceNotFoundException" + + @pytest.mark.asyncio + async def test_rollback_on_dynamo_failure( + self, cognito_pool, secrets_manager, monkeypatch + ): + """If DynamoDB write fails, the Cognito identity provider should be rolled back.""" + from apis.shared.auth_providers.cognito_idp_service import ( + CognitoIdentityProviderService, + ) + from apis.shared.auth_providers.repository import AuthProviderRepository + from apis.shared.auth_providers.service import AuthProviderService + + cognito_svc = CognitoIdentityProviderService( + user_pool_id=cognito_pool["pool_id"], + app_client_id=cognito_pool["client_id"], + region=AWS_REGION, + ) + + # Create a repo that will fail on put_item + repo = AuthProviderRepository( + table_name="test-auth-providers", + secrets_arn="auth-provider-secrets", + region=AWS_REGION, + ) + original_put = repo._table.put_item + def failing_put(**kwargs): + raise ClientError( + {"Error": {"Code": "InternalServerError", "Message": "DynamoDB failure"}}, + "PutItem", + ) + repo._table.put_item = failing_put + + service = AuthProviderService( + repository=repo, cognito_idp_service=cognito_svc + ) + + with pytest.raises(ClientError): + await service.create_provider(_make_create()) + + # Verify the identity provider was rolled back + client = cognito_pool["boto_client"] + with pytest.raises(ClientError) as exc_info: + client.describe_identity_provider( + UserPoolId=cognito_pool["pool_id"], + ProviderName="okta-1", + ) + assert exc_info.value.response["Error"]["Code"] == "ResourceNotFoundException" + + # Verify it was also removed from App Client + providers = cognito_svc.get_supported_identity_providers() + assert "okta-1" not in providers + + @pytest.mark.asyncio + async def test_create_without_cognito_still_works(self, auth_repo): + """When Cognito IdP service is None, create_provider should work as before.""" + from apis.shared.auth_providers.service import AuthProviderService + + service = AuthProviderService(repository=auth_repo, cognito_idp_service=None) + data = _make_create() + provider = await service.create_provider(data) + + assert provider.provider_id == "okta-1" + assert provider.cognito_provider_name is None + + @pytest.mark.asyncio + async def test_create_with_disabled_cognito_skips_registration(self, auth_repo): + """When Cognito IdP service is disabled, create_provider should skip Cognito.""" + from apis.shared.auth_providers.cognito_idp_service import ( + CognitoIdentityProviderService, + ) + from apis.shared.auth_providers.service import AuthProviderService + + disabled_svc = CognitoIdentityProviderService( + user_pool_id=None, app_client_id=None + ) + service = AuthProviderService( + repository=auth_repo, cognito_idp_service=disabled_svc + ) + data = _make_create() + provider = await service.create_provider(data) + + assert provider.provider_id == "okta-1" + assert provider.cognito_provider_name is None + + +# =================================================================== +# CognitoIdentityProviderService.update_identity_provider tests +# =================================================================== + + +class TestUpdateIdentityProvider: + def test_update_identity_provider_changes_issuer( + self, cognito_idp_service, cognito_pool + ): + """update_identity_provider should update ProviderDetails with new issuer URL.""" + cognito_idp_service.create_identity_provider( + provider_name="okta-1", + issuer_url="https://okta.example.com", + client_id="cid", + client_secret="secret", + ) + + cognito_idp_service.update_identity_provider( + provider_name="okta-1", + issuer_url="https://okta-new.example.com", + ) + + client = cognito_pool["boto_client"] + resp = client.describe_identity_provider( + UserPoolId=cognito_pool["pool_id"], + ProviderName="okta-1", + ) + details = resp["IdentityProvider"]["ProviderDetails"] + assert details["oidc_issuer"] == "https://okta-new.example.com" + # Unchanged fields preserved + assert details["client_id"] == "cid" + + def test_update_identity_provider_changes_client_id_and_secret( + self, cognito_idp_service, cognito_pool + ): + """update_identity_provider should update client_id and client_secret.""" + cognito_idp_service.create_identity_provider( + provider_name="okta-1", + issuer_url="https://okta.example.com", + client_id="old-cid", + client_secret="old-secret", + ) + + cognito_idp_service.update_identity_provider( + provider_name="okta-1", + client_id="new-cid", + client_secret="new-secret", + ) + + client = cognito_pool["boto_client"] + resp = client.describe_identity_provider( + UserPoolId=cognito_pool["pool_id"], + ProviderName="okta-1", + ) + details = resp["IdentityProvider"]["ProviderDetails"] + assert details["client_id"] == "new-cid" + assert details["client_secret"] == "new-secret" + # Issuer unchanged + assert details["oidc_issuer"] == "https://okta.example.com" + + def test_update_identity_provider_changes_attribute_mapping( + self, cognito_idp_service, cognito_pool + ): + """update_identity_provider should replace attribute mapping when provided.""" + cognito_idp_service.create_identity_provider( + provider_name="okta-1", + issuer_url="https://okta.example.com", + client_id="cid", + client_secret="secret", + ) + + new_mapping = {"email": "mail", "custom:provider_sub": "sub"} + cognito_idp_service.update_identity_provider( + provider_name="okta-1", + attribute_mapping=new_mapping, + ) + + client = cognito_pool["boto_client"] + resp = client.describe_identity_provider( + UserPoolId=cognito_pool["pool_id"], + ProviderName="okta-1", + ) + mapping = resp["IdentityProvider"]["AttributeMapping"] + assert mapping["email"] == "mail" + + def test_update_identity_provider_raises_when_disabled(self): + """update_identity_provider should raise RuntimeError when service is disabled.""" + from apis.shared.auth_providers.cognito_idp_service import ( + CognitoIdentityProviderService, + ) + + svc = CognitoIdentityProviderService(user_pool_id=None, app_client_id=None) + with pytest.raises(RuntimeError, match="not enabled"): + svc.update_identity_provider(provider_name="x", issuer_url="https://x.com") + + +# =================================================================== +# AuthProviderService.update_provider with Cognito sync tests +# =================================================================== + + +class TestUpdateProviderWithCognito: + @pytest.mark.asyncio + async def test_update_syncs_oidc_changes_to_cognito( + self, service_with_cognito, cognito_pool + ): + """Updating OIDC fields should call Cognito UpdateIdentityProvider.""" + # Create a provider first + data = _make_create() + await service_with_cognito.create_provider(data) + + # Update issuer_url and client_id + from apis.shared.auth_providers.models import AuthProviderUpdate + + updates = AuthProviderUpdate( + issuer_url="https://new-issuer.example.com", + client_id="new-client-id", + ) + result = await service_with_cognito.update_provider("okta-1", updates) + assert result is not None + + # Verify Cognito was updated + client = cognito_pool["boto_client"] + resp = client.describe_identity_provider( + UserPoolId=cognito_pool["pool_id"], + ProviderName="okta-1", + ) + details = resp["IdentityProvider"]["ProviderDetails"] + assert details["oidc_issuer"] == "https://new-issuer.example.com" + assert details["client_id"] == "new-client-id" + + @pytest.mark.asyncio + async def test_update_syncs_attribute_mapping_changes( + self, service_with_cognito, cognito_pool + ): + """Updating claim fields should rebuild and sync attribute mapping to Cognito.""" + data = _make_create() + await service_with_cognito.create_provider(data) + + from apis.shared.auth_providers.models import AuthProviderUpdate + + updates = AuthProviderUpdate(email_claim="mail", name_claim="displayName") + await service_with_cognito.update_provider("okta-1", updates) + + client = cognito_pool["boto_client"] + resp = client.describe_identity_provider( + UserPoolId=cognito_pool["pool_id"], + ProviderName="okta-1", + ) + mapping = resp["IdentityProvider"]["AttributeMapping"] + assert mapping["email"] == "mail" + assert mapping["name"] == "displayName" + assert mapping["custom:provider_sub"] == "sub" + + @pytest.mark.asyncio + async def test_update_skips_cognito_when_no_oidc_fields_changed( + self, service_with_cognito, cognito_pool + ): + """Updating non-OIDC fields should NOT call Cognito UpdateIdentityProvider.""" + data = _make_create() + await service_with_cognito.create_provider(data) + + # Get original Cognito state + client = cognito_pool["boto_client"] + before = client.describe_identity_provider( + UserPoolId=cognito_pool["pool_id"], + ProviderName="okta-1", + ) + before_details = before["IdentityProvider"]["ProviderDetails"] + + from apis.shared.auth_providers.models import AuthProviderUpdate + + # Only update display_name (not an OIDC field) + updates = AuthProviderUpdate(display_name="Okta Renamed") + result = await service_with_cognito.update_provider("okta-1", updates) + assert result is not None + assert result.display_name == "Okta Renamed" + + # Cognito provider details should be unchanged + after = client.describe_identity_provider( + UserPoolId=cognito_pool["pool_id"], + ProviderName="okta-1", + ) + after_details = after["IdentityProvider"]["ProviderDetails"] + assert after_details["oidc_issuer"] == before_details["oidc_issuer"] + assert after_details["client_id"] == before_details["client_id"] + + @pytest.mark.asyncio + async def test_update_works_when_cognito_disabled(self, auth_repo): + """When Cognito is disabled, update_provider should work without Cognito calls.""" + from apis.shared.auth_providers.cognito_idp_service import ( + CognitoIdentityProviderService, + ) + from apis.shared.auth_providers.service import AuthProviderService + from apis.shared.auth_providers.models import AuthProviderUpdate + + disabled_svc = CognitoIdentityProviderService( + user_pool_id=None, app_client_id=None + ) + service = AuthProviderService( + repository=auth_repo, cognito_idp_service=disabled_svc + ) + + # Create provider without Cognito + no_cognito_service = AuthProviderService( + repository=auth_repo, cognito_idp_service=None + ) + data = _make_create() + await no_cognito_service.create_provider(data) + + # Update with disabled Cognito service + updates = AuthProviderUpdate(issuer_url="https://new.example.com") + result = await service.update_provider("okta-1", updates) + assert result is not None + assert result.issuer_url == "https://new.example.com" + + @pytest.mark.asyncio + async def test_update_cognito_failure_blocks_dynamo_update( + self, auth_repo, cognito_pool + ): + """If Cognito UpdateIdentityProvider fails, DynamoDB should NOT be updated.""" + from apis.shared.auth_providers.cognito_idp_service import ( + CognitoIdentityProviderService, + ) + from apis.shared.auth_providers.service import AuthProviderService + from apis.shared.auth_providers.models import AuthProviderUpdate + from fastapi import HTTPException + + cognito_svc = CognitoIdentityProviderService( + user_pool_id=cognito_pool["pool_id"], + app_client_id=cognito_pool["client_id"], + region=AWS_REGION, + ) + + service = AuthProviderService( + repository=auth_repo, cognito_idp_service=cognito_svc + ) + + # Create provider with Cognito + data = _make_create() + await service.create_provider(data) + + # Patch update_identity_provider to fail + original_update = cognito_svc.update_identity_provider + def failing_update(**kwargs): + raise ClientError( + {"Error": {"Code": "InvalidParameterException", "Message": "test failure"}}, + "UpdateIdentityProvider", + ) + cognito_svc.update_identity_provider = failing_update + + updates = AuthProviderUpdate(issuer_url="https://should-not-persist.example.com") + with pytest.raises(HTTPException) as exc_info: + await service.update_provider("okta-1", updates) + assert exc_info.value.status_code == 502 + + # Verify DynamoDB was NOT updated + provider = await auth_repo.get_provider("okta-1") + assert provider.issuer_url == "https://okta.example.com" + + +# =================================================================== +# AuthProviderService.delete_provider with Cognito cleanup tests +# =================================================================== + + +class TestDeleteProviderWithCognito: + @pytest.mark.asyncio + async def test_delete_provider_with_cognito_registration( + self, service_with_cognito, cognito_pool, cognito_idp_service, auth_providers_table + ): + """Deleting a provider with Cognito registration should remove from Cognito, App Client, and DynamoDB.""" + # Create a provider (registers in Cognito + adds to App Client) + data = _make_create() + await service_with_cognito.create_provider(data) + + # Verify it exists in Cognito and App Client + providers = cognito_idp_service.get_supported_identity_providers() + assert "okta-1" in providers + + # Delete + result = await service_with_cognito.delete_provider("okta-1") + assert result is True + + # Verify removed from Cognito + client = cognito_pool["boto_client"] + with pytest.raises(ClientError) as exc_info: + client.describe_identity_provider( + UserPoolId=cognito_pool["pool_id"], + ProviderName="okta-1", + ) + assert exc_info.value.response["Error"]["Code"] == "ResourceNotFoundException" + + # Verify removed from App Client + providers = cognito_idp_service.get_supported_identity_providers() + assert "okta-1" not in providers + assert "COGNITO" in providers + + # Verify removed from DynamoDB + resp = auth_providers_table.get_item( + Key={"PK": "AUTH_PROVIDER#okta-1", "SK": "AUTH_PROVIDER#okta-1"} + ) + assert "Item" not in resp + + @pytest.mark.asyncio + async def test_delete_provider_without_cognito_registration( + self, auth_repo, auth_providers_table + ): + """Deleting a provider without cognito_provider_name should skip Cognito calls.""" + from apis.shared.auth_providers.service import AuthProviderService + + # Create provider without Cognito + service = AuthProviderService(repository=auth_repo, cognito_idp_service=None) + data = _make_create() + await service.create_provider(data) + + # Delete — should succeed without touching Cognito + result = await service.delete_provider("okta-1") + assert result is True + + # Verify removed from DynamoDB + resp = auth_providers_table.get_item( + Key={"PK": "AUTH_PROVIDER#okta-1", "SK": "AUTH_PROVIDER#okta-1"} + ) + assert "Item" not in resp + + @pytest.mark.asyncio + async def test_delete_provider_when_cognito_disabled( + self, auth_repo, auth_providers_table + ): + """When Cognito service is disabled, delete should still work for DynamoDB.""" + from apis.shared.auth_providers.cognito_idp_service import ( + CognitoIdentityProviderService, + ) + from apis.shared.auth_providers.service import AuthProviderService + + disabled_svc = CognitoIdentityProviderService( + user_pool_id=None, app_client_id=None + ) + + # Create provider without Cognito first + no_cognito_service = AuthProviderService( + repository=auth_repo, cognito_idp_service=None + ) + data = _make_create() + await no_cognito_service.create_provider(data) + + # Delete with disabled Cognito service + service = AuthProviderService( + repository=auth_repo, cognito_idp_service=disabled_svc + ) + result = await service.delete_provider("okta-1") + assert result is True + + # Verify removed from DynamoDB + resp = auth_providers_table.get_item( + Key={"PK": "AUTH_PROVIDER#okta-1", "SK": "AUTH_PROVIDER#okta-1"} + ) + assert "Item" not in resp + + @pytest.mark.asyncio + async def test_delete_cognito_failure_still_deletes_from_dynamo( + self, auth_repo, cognito_pool, auth_providers_table + ): + """If Cognito delete fails, DynamoDB delete should still proceed (best-effort).""" + from apis.shared.auth_providers.cognito_idp_service import ( + CognitoIdentityProviderService, + ) + from apis.shared.auth_providers.service import AuthProviderService + + cognito_svc = CognitoIdentityProviderService( + user_pool_id=cognito_pool["pool_id"], + app_client_id=cognito_pool["client_id"], + region=AWS_REGION, + ) + + service = AuthProviderService( + repository=auth_repo, cognito_idp_service=cognito_svc + ) + + # Create provider with Cognito + data = _make_create() + await service.create_provider(data) + + # Patch both Cognito methods to fail + def failing_remove(name): + raise ClientError( + {"Error": {"Code": "InternalErrorException", "Message": "test failure"}}, + "UpdateUserPoolClient", + ) + + def failing_delete(name): + raise ClientError( + {"Error": {"Code": "InternalErrorException", "Message": "test failure"}}, + "DeleteIdentityProvider", + ) + + cognito_svc.remove_provider_from_app_client = failing_remove + cognito_svc.delete_identity_provider = failing_delete + + # Delete should still succeed (best-effort Cognito cleanup) + result = await service.delete_provider("okta-1") + assert result is True + + # Verify removed from DynamoDB despite Cognito failures + resp = auth_providers_table.get_item( + Key={"PK": "AUTH_PROVIDER#okta-1", "SK": "AUTH_PROVIDER#okta-1"} + ) + assert "Item" not in resp + + @pytest.mark.asyncio + async def test_delete_nonexistent_provider_returns_false( + self, service_with_cognito + ): + """Deleting a provider that doesn't exist should return False.""" + result = await service_with_cognito.delete_provider("nonexistent-provider") + assert result is False + + +# =================================================================== +# Configurable attribute mappings and OIDC discovery tests (Task 6.4) +# =================================================================== + + +class TestAttributeMappings: + """Tests for _build_attribute_mapping and custom claim passthrough to Cognito.""" + + @pytest.mark.asyncio + async def test_default_attribute_mapping( + self, service_with_cognito, cognito_pool + ): + """Default claim fields should produce default Cognito attribute mapping.""" + data = _make_create() + await service_with_cognito.create_provider(data) + + client = cognito_pool["boto_client"] + resp = client.describe_identity_provider( + UserPoolId=cognito_pool["pool_id"], + ProviderName="okta-1", + ) + mapping = resp["IdentityProvider"]["AttributeMapping"] + # Default: email→email, custom:provider_sub→sub + assert mapping["email"] == "email" + assert mapping["custom:provider_sub"] == "sub" + + @pytest.mark.asyncio + async def test_custom_email_claim_mapping( + self, service_with_cognito, cognito_pool + ): + """Custom email_claim should map Cognito 'email' to the custom claim name.""" + data = _make_create(email_claim="preferred_email") + await service_with_cognito.create_provider(data) + + client = cognito_pool["boto_client"] + resp = client.describe_identity_provider( + UserPoolId=cognito_pool["pool_id"], + ProviderName="okta-1", + ) + mapping = resp["IdentityProvider"]["AttributeMapping"] + assert mapping["email"] == "preferred_email" + + @pytest.mark.asyncio + async def test_all_custom_claim_mappings( + self, service_with_cognito, cognito_pool + ): + """All custom claim fields should be reflected in Cognito attribute mapping.""" + data = _make_create( + email_claim="mail", + name_claim="full_name", + first_name_claim="fname", + last_name_claim="lname", + picture_claim="photo_url", + ) + await service_with_cognito.create_provider(data) + + client = cognito_pool["boto_client"] + resp = client.describe_identity_provider( + UserPoolId=cognito_pool["pool_id"], + ProviderName="okta-1", + ) + mapping = resp["IdentityProvider"]["AttributeMapping"] + assert mapping["email"] == "mail" + assert mapping["name"] == "full_name" + assert mapping["given_name"] == "fname" + assert mapping["family_name"] == "lname" + assert mapping["picture"] == "photo_url" + assert mapping["custom:provider_sub"] == "sub" + + @pytest.mark.asyncio + async def test_partial_custom_claim_mappings( + self, service_with_cognito, cognito_pool + ): + """Only specified custom claims should appear in mapping; unset ones omitted.""" + data = _make_create( + name_claim="displayName", + first_name_claim=None, + last_name_claim=None, + picture_claim=None, + ) + await service_with_cognito.create_provider(data) + + client = cognito_pool["boto_client"] + resp = client.describe_identity_provider( + UserPoolId=cognito_pool["pool_id"], + ProviderName="okta-1", + ) + mapping = resp["IdentityProvider"]["AttributeMapping"] + assert mapping["email"] == "email" + assert mapping["name"] == "displayName" + assert mapping["custom:provider_sub"] == "sub" + assert "given_name" not in mapping + assert "family_name" not in mapping + assert "picture" not in mapping + + @pytest.mark.asyncio + async def test_provider_sub_always_mapped( + self, service_with_cognito, cognito_pool + ): + """custom:provider_sub→sub should always be present regardless of other claims.""" + data = _make_create( + email_claim="e", + first_name_claim=None, + last_name_claim=None, + picture_claim=None, + ) + await service_with_cognito.create_provider(data) + + client = cognito_pool["boto_client"] + resp = client.describe_identity_provider( + UserPoolId=cognito_pool["pool_id"], + ProviderName="okta-1", + ) + mapping = resp["IdentityProvider"]["AttributeMapping"] + assert mapping["custom:provider_sub"] == "sub" + + @pytest.mark.asyncio + async def test_update_attribute_mapping_syncs_to_cognito( + self, service_with_cognito, cognito_pool + ): + """Updating claim fields should rebuild and sync attribute mapping to Cognito.""" + data = _make_create() + await service_with_cognito.create_provider(data) + + from apis.shared.auth_providers.models import AuthProviderUpdate + + updates = AuthProviderUpdate( + email_claim="work_email", + first_name_claim="givenName", + last_name_claim="surname", + ) + await service_with_cognito.update_provider("okta-1", updates) + + client = cognito_pool["boto_client"] + resp = client.describe_identity_provider( + UserPoolId=cognito_pool["pool_id"], + ProviderName="okta-1", + ) + mapping = resp["IdentityProvider"]["AttributeMapping"] + assert mapping["email"] == "work_email" + assert mapping["given_name"] == "givenName" + assert mapping["family_name"] == "surname" + assert mapping["custom:provider_sub"] == "sub" + + +class TestOIDCDiscoveryAutoDiscover: + """Tests for the auto_discover flag controlling OIDC endpoint discovery.""" + + @pytest.mark.asyncio + async def test_auto_discover_true_triggers_discovery( + self, service_with_cognito + ): + """When auto_discover=True and endpoints missing, discovery should be attempted.""" + data = _make_create( + authorization_endpoint=None, + token_endpoint=None, + jwks_uri=None, + ) + data.auto_discover = True + + # Patch discover_endpoints to track if it was called + called = {"count": 0} + original = service_with_cognito.discover_endpoints + + async def tracking_discover(issuer_url): + called["count"] += 1 + from apis.shared.auth_providers.models import OIDCDiscoveryResponse + return OIDCDiscoveryResponse( + issuer=issuer_url, + authorization_endpoint="https://okta.example.com/authorize", + token_endpoint="https://okta.example.com/token", + jwks_uri="https://okta.example.com/keys", + userinfo_endpoint="https://okta.example.com/userinfo", + ) + + service_with_cognito.discover_endpoints = tracking_discover + + provider = await service_with_cognito.create_provider(data) + assert called["count"] == 1 + assert provider.authorization_endpoint == "https://okta.example.com/authorize" + assert provider.token_endpoint == "https://okta.example.com/token" + assert provider.jwks_uri == "https://okta.example.com/keys" + + @pytest.mark.asyncio + async def test_auto_discover_false_skips_discovery( + self, service_with_cognito + ): + """When auto_discover=False, discovery should NOT be attempted even if endpoints missing.""" + data = _make_create( + authorization_endpoint=None, + token_endpoint=None, + jwks_uri=None, + ) + data.auto_discover = False + + # Patch discover_endpoints to track if it was called + called = {"count": 0} + + async def tracking_discover(issuer_url): + called["count"] += 1 + from apis.shared.auth_providers.models import OIDCDiscoveryResponse + return OIDCDiscoveryResponse(issuer=issuer_url) + + service_with_cognito.discover_endpoints = tracking_discover + + provider = await service_with_cognito.create_provider(data) + assert called["count"] == 0 + # Endpoints remain None since discovery was skipped + assert provider.authorization_endpoint is None + assert provider.token_endpoint is None + assert provider.jwks_uri is None + + @pytest.mark.asyncio + async def test_auto_discover_default_is_false(self): + """auto_discover should default to False (opt-in).""" + data = _make_create() + assert data.auto_discover is False + + @pytest.mark.asyncio + async def test_auto_discover_skipped_when_endpoints_provided( + self, service_with_cognito + ): + """When all endpoints are already provided, discovery should not run even with auto_discover=True.""" + data = _make_create( + authorization_endpoint="https://okta.example.com/authorize", + token_endpoint="https://okta.example.com/token", + jwks_uri="https://okta.example.com/keys", + ) + data.auto_discover = True + + called = {"count": 0} + + async def tracking_discover(issuer_url): + called["count"] += 1 + from apis.shared.auth_providers.models import OIDCDiscoveryResponse + return OIDCDiscoveryResponse(issuer=issuer_url) + + service_with_cognito.discover_endpoints = tracking_discover + + provider = await service_with_cognito.create_provider(data) + assert called["count"] == 0 + assert provider.authorization_endpoint == "https://okta.example.com/authorize" + + @pytest.mark.asyncio + async def test_auto_discover_populates_missing_endpoints_only( + self, service_with_cognito + ): + """Discovery should only fill in missing endpoints, not overwrite provided ones.""" + data = _make_create( + authorization_endpoint="https://custom.example.com/auth", + token_endpoint=None, + jwks_uri=None, + ) + data.auto_discover = True + + async def mock_discover(issuer_url): + from apis.shared.auth_providers.models import OIDCDiscoveryResponse + return OIDCDiscoveryResponse( + issuer=issuer_url, + authorization_endpoint="https://discovered.example.com/authorize", + token_endpoint="https://discovered.example.com/token", + jwks_uri="https://discovered.example.com/keys", + userinfo_endpoint="https://discovered.example.com/userinfo", + ) + + service_with_cognito.discover_endpoints = mock_discover + + provider = await service_with_cognito.create_provider(data) + # Provided endpoint should NOT be overwritten + assert provider.authorization_endpoint == "https://custom.example.com/auth" + # Missing endpoints should be filled from discovery + assert provider.token_endpoint == "https://discovered.example.com/token" + assert provider.jwks_uri == "https://discovered.example.com/keys" diff --git a/backend/tests/system/__init__.py b/backend/tests/system/__init__.py new file mode 100644 index 00000000..8b137891 --- /dev/null +++ b/backend/tests/system/__init__.py @@ -0,0 +1 @@ + diff --git a/backend/tests/system/test_first_boot.py b/backend/tests/system/test_first_boot.py new file mode 100644 index 00000000..4481d57a --- /dev/null +++ b/backend/tests/system/test_first_boot.py @@ -0,0 +1,286 @@ +"""Unit tests for the POST /system/first-boot endpoint and CognitoService.""" + +import asyncio +from unittest.mock import MagicMock, patch + +import pytest +from botocore.exceptions import ClientError +from fastapi import HTTPException + +from apis.app_api.system.cognito_service import CognitoService + +pytestmark = pytest.mark.asyncio + + +# ========================================================================= +# CognitoService tests +# ========================================================================= + + +class TestCognitoService: + """Unit tests for CognitoService.""" + + def _make_service(self) -> CognitoService: + with patch("apis.app_api.system.cognito_service.boto3") as mock_boto: + mock_client = MagicMock() + mock_boto.client.return_value = mock_client + svc = CognitoService(user_pool_id="us-east-1_TestPool") + svc._client = mock_client + return svc + + def test_disabled_when_no_pool_id(self): + with patch.dict("os.environ", {}, clear=True): + svc = CognitoService(user_pool_id=None) + assert svc.enabled is False + + def test_enabled_when_pool_id_set(self): + svc = self._make_service() + assert svc.enabled is True + assert svc.user_pool_id == "us-east-1_TestPool" + + def test_create_admin_user_success(self): + svc = self._make_service() + svc._client.admin_create_user.return_value = { + "User": { + "Attributes": [ + {"Name": "sub", "Value": "abc-123-def"}, + {"Name": "email", "Value": "admin@example.com"}, + ] + } + } + + user_sub = svc.create_admin_user("admin", "admin@example.com", "P@ssw0rd!") + assert user_sub == "abc-123-def" + + svc._client.admin_create_user.assert_called_once_with( + UserPoolId="us-east-1_TestPool", + Username="admin", + UserAttributes=[ + {"Name": "email", "Value": "admin@example.com"}, + {"Name": "email_verified", "Value": "true"}, + ], + MessageAction="SUPPRESS", + ) + svc._client.admin_set_user_password.assert_called_once_with( + UserPoolId="us-east-1_TestPool", + Username="admin", + Password="P@ssw0rd!", + Permanent=True, + ) + + def test_create_admin_user_raises_on_disabled(self): + with patch.dict("os.environ", {}, clear=True): + svc = CognitoService(user_pool_id=None) + with pytest.raises(RuntimeError, match="not enabled"): + svc.create_admin_user("admin", "a@b.com", "pass") + + def test_delete_user_calls_admin_delete(self): + svc = self._make_service() + svc.delete_user("admin") + svc._client.admin_delete_user.assert_called_once_with( + UserPoolId="us-east-1_TestPool", + Username="admin", + ) + + def test_delete_user_swallows_errors(self): + svc = self._make_service() + svc._client.admin_delete_user.side_effect = ClientError( + {"Error": {"Code": "UserNotFoundException", "Message": ""}}, + "AdminDeleteUser", + ) + # Should not raise + svc.delete_user("admin") + + def test_disable_self_signup(self): + svc = self._make_service() + svc.disable_self_signup() + svc._client.update_user_pool.assert_called_once() + call_kwargs = svc._client.update_user_pool.call_args[1] + assert call_kwargs["AdminCreateUserConfig"]["AllowAdminCreateUserOnly"] is True + + def test_disable_self_signup_raises_on_disabled(self): + with patch.dict("os.environ", {}, clear=True): + svc = CognitoService(user_pool_id=None) + with pytest.raises(RuntimeError, match="not enabled"): + svc.disable_self_signup() + + +# ========================================================================= +# First-boot endpoint tests +# ========================================================================= + + +class TestFirstBootEndpoint: + """Validates: Requirements 2.3, 2.4, 2.5, 2.6, 2.7, 2.8.""" + + def _make_mocks(self): + """Create mocked dependencies for the first-boot endpoint.""" + mock_settings_repo = MagicMock() + mock_cognito = MagicMock() + mock_user_repo = MagicMock() + mock_user_repo.enabled = True + + # Default: first-boot not yet completed + future_none = asyncio.Future() + future_none.set_result(None) + mock_settings_repo.get_first_boot_status.return_value = future_none + + # Default: mark completed succeeds + future_mark = asyncio.Future() + future_mark.set_result(None) + mock_settings_repo.mark_first_boot_completed.return_value = future_mark + + # Default: Cognito create succeeds + mock_cognito.create_admin_user.return_value = "sub-uuid-123" + mock_cognito.enabled = True + + # Default: user repo create succeeds + future_create = asyncio.Future() + future_create.set_result(None) + mock_user_repo.create_user.return_value = future_create + + return mock_settings_repo, mock_cognito, mock_user_repo + + async def _call_first_boot( + self, mock_settings_repo, mock_cognito, mock_user_repo, + username="admin", email="admin@example.com", password="Str0ng!Pass1", + ): + """Call the first_boot endpoint with mocked dependencies.""" + from apis.app_api.system.models import FirstBootRequest + from apis.app_api.system.routes import first_boot + + request = FirstBootRequest( + username=username, email=email, password=password + ) + + with patch( + "apis.app_api.system.routes.get_system_settings_repository", + return_value=mock_settings_repo, + ), patch( + "apis.app_api.system.routes.get_cognito_service", + return_value=mock_cognito, + ), patch( + "apis.app_api.system.routes.UserRepository", + return_value=mock_user_repo, + ): + return await first_boot(request) + + async def test_successful_first_boot(self): + """Req 2.3, 2.4, 2.5: creates Cognito user, DynamoDB record, marks completed.""" + mock_settings, mock_cognito, mock_user_repo = self._make_mocks() + + result = await self._call_first_boot(mock_settings, mock_cognito, mock_user_repo) + + assert result.success is True + assert result.user_id == "sub-uuid-123" + mock_cognito.create_admin_user.assert_called_once_with( + username="admin", email="admin@example.com", password="Str0ng!Pass1" + ) + mock_user_repo.create_user.assert_called_once() + # Verify the user profile has system_admin role + created_profile = mock_user_repo.create_user.call_args[0][0] + assert "system_admin" in created_profile.roles + mock_settings.mark_first_boot_completed.assert_called_once() + mock_cognito.disable_self_signup.assert_called_once() + + async def test_rejects_when_already_completed(self): + """Req 2.7: returns 409 if first-boot already done.""" + mock_settings, mock_cognito, mock_user_repo = self._make_mocks() + + future_completed = asyncio.Future() + future_completed.set_result({"completed": True}) + mock_settings.get_first_boot_status.return_value = future_completed + + with pytest.raises(HTTPException) as exc_info: + await self._call_first_boot(mock_settings, mock_cognito, mock_user_repo) + assert exc_info.value.status_code == 409 + + # Cognito should never be called + mock_cognito.create_admin_user.assert_not_called() + + async def test_returns_400_on_invalid_password(self): + """Req 2.8: returns 400 when Cognito rejects the password.""" + mock_settings, mock_cognito, mock_user_repo = self._make_mocks() + mock_cognito.create_admin_user.side_effect = ClientError( + {"Error": {"Code": "InvalidPasswordException", "Message": "Too weak"}}, + "AdminCreateUser", + ) + + with pytest.raises(HTTPException) as exc_info: + await self._call_first_boot(mock_settings, mock_cognito, mock_user_repo) + assert exc_info.value.status_code == 400 + + async def test_returns_409_on_username_exists(self): + """Returns 409 when Cognito username already exists.""" + mock_settings, mock_cognito, mock_user_repo = self._make_mocks() + mock_cognito.create_admin_user.side_effect = ClientError( + {"Error": {"Code": "UsernameExistsException", "Message": "exists"}}, + "AdminCreateUser", + ) + + with pytest.raises(HTTPException) as exc_info: + await self._call_first_boot(mock_settings, mock_cognito, mock_user_repo) + assert exc_info.value.status_code == 409 + + async def test_rolls_back_cognito_on_user_repo_failure(self): + """Rollback: deletes Cognito user if DynamoDB user creation fails.""" + mock_settings, mock_cognito, mock_user_repo = self._make_mocks() + + future_fail = asyncio.Future() + future_fail.set_exception(RuntimeError("DynamoDB write failed")) + mock_user_repo.create_user.return_value = future_fail + + with pytest.raises(HTTPException) as exc_info: + await self._call_first_boot(mock_settings, mock_cognito, mock_user_repo) + assert exc_info.value.status_code == 500 + + mock_cognito.delete_user.assert_called_once_with("admin") + + async def test_rolls_back_cognito_on_conditional_check_failure(self): + """Race condition: conditional write fails → 409 + rollback.""" + mock_settings, mock_cognito, mock_user_repo = self._make_mocks() + + future_race = asyncio.Future() + future_race.set_exception( + ClientError( + {"Error": {"Code": "ConditionalCheckFailedException", "Message": ""}}, + "PutItem", + ) + ) + mock_settings.mark_first_boot_completed.return_value = future_race + + with pytest.raises(HTTPException) as exc_info: + await self._call_first_boot(mock_settings, mock_cognito, mock_user_repo) + assert exc_info.value.status_code == 409 + + mock_cognito.delete_user.assert_called_once_with("admin") + + async def test_disable_self_signup_failure_is_non_fatal(self): + """Req 2.6: disable_self_signup failure doesn't fail the endpoint.""" + mock_settings, mock_cognito, mock_user_repo = self._make_mocks() + mock_cognito.disable_self_signup.side_effect = ClientError( + {"Error": {"Code": "InternalErrorException", "Message": "oops"}}, + "UpdateUserPool", + ) + + result = await self._call_first_boot(mock_settings, mock_cognito, mock_user_repo) + # Should still succeed + assert result.success is True + assert result.user_id == "sub-uuid-123" + + async def test_user_profile_has_correct_fields(self): + """Req 2.4: user record has system_admin role and correct fields.""" + mock_settings, mock_cognito, mock_user_repo = self._make_mocks() + + await self._call_first_boot( + mock_settings, mock_cognito, mock_user_repo, + username="myadmin", email="myadmin@corp.io", password="Str0ng!Pass1", + ) + + created_profile = mock_user_repo.create_user.call_args[0][0] + assert created_profile.user_id == "sub-uuid-123" + assert created_profile.email == "myadmin@corp.io" + assert created_profile.name == "myadmin" + assert created_profile.roles == ["system_admin"] + assert created_profile.email_domain == "corp.io" + assert created_profile.status == "active" diff --git a/backend/tests/system/test_system.py b/backend/tests/system/test_system.py new file mode 100644 index 00000000..b55a26e1 --- /dev/null +++ b/backend/tests/system/test_system.py @@ -0,0 +1,278 @@ +"""Unit tests for system settings models and repository.""" + +import pytest +from unittest.mock import MagicMock, patch +from botocore.exceptions import ClientError + +from apis.app_api.system.models import ( + FirstBootRequest, + FirstBootResponse, + SystemStatusResponse, +) +from apis.app_api.system.repository import ( + FIRST_BOOT_PK, + FIRST_BOOT_SK, + SystemSettingsRepository, +) + +pytestmark = pytest.mark.asyncio + + +# ========================================================================= +# Model validation tests +# ========================================================================= + + +class TestFirstBootRequest: + """Validates: Requirement 12.1 — first-boot request validation.""" + + def test_valid_request(self): + req = FirstBootRequest( + username="admin", email="admin@example.com", password="Str0ng!Pass" + ) + assert req.username == "admin" + assert req.email == "admin@example.com" + assert req.password == "Str0ng!Pass" + + def test_username_too_short(self): + with pytest.raises(Exception): + FirstBootRequest(username="ab", email="a@b.com", password="12345678") + + def test_username_too_long(self): + with pytest.raises(Exception): + FirstBootRequest( + username="x" * 129, email="a@b.com", password="12345678" + ) + + def test_invalid_email(self): + with pytest.raises(Exception): + FirstBootRequest( + username="admin", email="not-an-email", password="12345678" + ) + + def test_password_too_short(self): + with pytest.raises(Exception): + FirstBootRequest( + username="admin", email="a@b.com", password="short" + ) + + +class TestFirstBootResponse: + def test_response_fields(self): + resp = FirstBootResponse( + success=True, user_id="uid-123", message="done" + ) + assert resp.success is True + assert resp.user_id == "uid-123" + + +class TestSystemStatusResponse: + def test_status_fields(self): + status = SystemStatusResponse(first_boot_completed=False) + assert status.first_boot_completed is False + + +# ========================================================================= +# Repository tests +# ========================================================================= + + +class TestSystemSettingsRepository: + """Validates: Requirements 12.1, 12.4, 12.5.""" + + def _make_repo(self) -> SystemSettingsRepository: + """Create a repository with a mocked DynamoDB table.""" + with patch.dict( + "os.environ", + {"DYNAMODB_AUTH_PROVIDERS_TABLE_NAME": "test-table"}, + clear=False, + ), patch("apis.app_api.system.repository.boto3") as mock_boto: + mock_table = MagicMock() + mock_resource = MagicMock() + mock_resource.Table.return_value = mock_table + mock_boto.Session.return_value.resource.return_value = mock_resource + mock_boto.resource.return_value = mock_resource + + repo = SystemSettingsRepository(table_name="test-table") + repo._table = mock_table + return repo + + @pytest.mark.asyncio + async def test_get_first_boot_status_not_found(self): + """Requirement 12.5: missing item means not bootstrapped.""" + repo = self._make_repo() + repo._table.get_item.return_value = {} + + result = await repo.get_first_boot_status() + assert result is None + + repo._table.get_item.assert_called_once_with( + Key={"PK": FIRST_BOOT_PK, "SK": FIRST_BOOT_SK} + ) + + @pytest.mark.asyncio + async def test_get_first_boot_status_found(self): + repo = self._make_repo() + repo._table.get_item.return_value = { + "Item": { + "PK": FIRST_BOOT_PK, + "SK": FIRST_BOOT_SK, + "completed": True, + "completedBy": "uid-1", + } + } + + result = await repo.get_first_boot_status() + assert result is not None + assert result["completed"] is True + + @pytest.mark.asyncio + async def test_mark_first_boot_completed_success(self): + """Requirement 12.1: stores first-boot item in DynamoDB.""" + repo = self._make_repo() + + await repo.mark_first_boot_completed( + user_id="uid-1", username="admin", email="admin@example.com" + ) + + repo._table.put_item.assert_called_once() + call_kwargs = repo._table.put_item.call_args[1] + item = call_kwargs["Item"] + assert item["PK"] == FIRST_BOOT_PK + assert item["SK"] == FIRST_BOOT_SK + assert item["completed"] is True + assert item["completedBy"] == "uid-1" + assert item["adminUsername"] == "admin" + assert item["adminEmail"] == "admin@example.com" + assert "completedAt" in item + assert call_kwargs["ConditionExpression"] == "attribute_not_exists(PK)" + + @pytest.mark.asyncio + async def test_mark_first_boot_completed_race_condition(self): + """Requirement 12.4: conditional write rejects duplicate.""" + repo = self._make_repo() + repo._table.put_item.side_effect = ClientError( + {"Error": {"Code": "ConditionalCheckFailedException", "Message": ""}}, + "PutItem", + ) + + with pytest.raises(ClientError) as exc_info: + await repo.mark_first_boot_completed( + user_id="uid-2", username="hacker", email="h@x.com" + ) + assert ( + exc_info.value.response["Error"]["Code"] + == "ConditionalCheckFailedException" + ) + + @pytest.mark.asyncio + async def test_disabled_repo_returns_none(self): + """When table name is not set, repository is disabled.""" + with patch.dict("os.environ", {}, clear=True): + repo = SystemSettingsRepository(table_name=None) + assert repo.enabled is False + assert await repo.get_first_boot_status() is None + + @pytest.mark.asyncio + async def test_disabled_repo_raises_on_write(self): + """Disabled repository raises RuntimeError on write.""" + with patch.dict("os.environ", {}, clear=True): + repo = SystemSettingsRepository(table_name=None) + with pytest.raises(RuntimeError): + await repo.mark_first_boot_completed("u", "n", "e") + + +# ========================================================================= +# Route tests +# ========================================================================= + + +class TestGetSystemStatusRoute: + """Validates: Requirements 12.2, 12.3, 12.5.""" + + @pytest.mark.asyncio + async def test_status_returns_false_when_no_item(self): + """Requirement 12.5: missing item means not bootstrapped.""" + from apis.app_api.system.routes import get_system_status + + with patch( + "apis.app_api.system.routes.get_system_settings_repository" + ) as mock_get_repo: + mock_repo = MagicMock() + mock_repo.get_first_boot_status = MagicMock(return_value=None) + # Make the coroutine return None + import asyncio + + future = asyncio.Future() + future.set_result(None) + mock_repo.get_first_boot_status.return_value = future + mock_get_repo.return_value = mock_repo + + result = await get_system_status() + assert result.first_boot_completed is False + + @pytest.mark.asyncio + async def test_status_returns_true_when_completed(self): + """Requirement 12.2: returns true when first-boot item exists with completed=true.""" + from apis.app_api.system.routes import get_system_status + + with patch( + "apis.app_api.system.routes.get_system_settings_repository" + ) as mock_get_repo: + mock_repo = MagicMock() + import asyncio + + future = asyncio.Future() + future.set_result( + {"PK": FIRST_BOOT_PK, "SK": FIRST_BOOT_SK, "completed": True} + ) + mock_repo.get_first_boot_status.return_value = future + mock_get_repo.return_value = mock_repo + + result = await get_system_status() + assert result.first_boot_completed is True + + @pytest.mark.asyncio + async def test_status_returns_false_when_completed_is_false(self): + """Item exists but completed is False.""" + from apis.app_api.system.routes import get_system_status + + with patch( + "apis.app_api.system.routes.get_system_settings_repository" + ) as mock_get_repo: + mock_repo = MagicMock() + import asyncio + + future = asyncio.Future() + future.set_result( + {"PK": FIRST_BOOT_PK, "SK": FIRST_BOOT_SK, "completed": False} + ) + mock_repo.get_first_boot_status.return_value = future + mock_get_repo.return_value = mock_repo + + result = await get_system_status() + assert result.first_boot_completed is False + + @pytest.mark.asyncio + async def test_status_returns_false_on_dynamo_failure(self): + """Requirement 12.5: DynamoDB failure returns safe default false.""" + from apis.app_api.system.routes import get_system_status + + with patch( + "apis.app_api.system.routes.get_system_settings_repository" + ) as mock_get_repo: + mock_repo = MagicMock() + import asyncio + + future = asyncio.Future() + future.set_exception( + ClientError( + {"Error": {"Code": "InternalServerError", "Message": "boom"}}, + "GetItem", + ) + ) + mock_repo.get_first_boot_status.return_value = future + mock_get_repo.return_value = mock_repo + + result = await get_system_status() + assert result.first_boot_completed is False diff --git a/backend/tests/test_seed_system_admin_jwt.py b/backend/tests/test_seed_system_admin_jwt.py index 05144f9d..b8a9004e 100644 --- a/backend/tests/test_seed_system_admin_jwt.py +++ b/backend/tests/test_seed_system_admin_jwt.py @@ -1,4 +1,4 @@ -"""Tests for seed_system_admin_jwt_roles in seed_bootstrap_data.py.""" +"""Tests for seed_system_admin_role and seed_default_tools in seed_bootstrap_data.py.""" import sys import os @@ -13,7 +13,6 @@ ) from seed_bootstrap_data import ( # noqa: E402 - seed_system_admin_jwt_roles, seed_system_admin_role, seed_default_tools, ) @@ -55,118 +54,9 @@ def dynamodb_table(): yield table -class TestSeedSystemAdminJwtRoles: - def test_creates_full_role_when_missing(self, dynamodb_table): - """When system_admin role doesn't exist, creates DEFINITION + JWT_MAPPING + grants.""" - result = seed_system_admin_jwt_roles(TABLE_NAME, REGION, "Admin") - - assert result.created == 1 - assert result.failed == 0 - - # Verify DEFINITION item - resp = dynamodb_table.get_item( - Key={"PK": "ROLE#system_admin", "SK": "DEFINITION"} - ) - item = resp["Item"] - assert item["roleId"] == "system_admin" - assert item["jwtRoleMappings"] == ["Admin"] - assert item["grantedTools"] == ["*"] - assert item["grantedModels"] == ["*"] - assert item["isSystemRole"] is True - - # Verify JWT_MAPPING item with GSI keys - resp = dynamodb_table.get_item( - Key={"PK": "ROLE#system_admin", "SK": "JWT_MAPPING#Admin"} - ) - mapping = resp["Item"] - assert mapping["GSI1PK"] == "JWT_ROLE#Admin" - assert mapping["GSI1SK"] == "ROLE#system_admin" - assert mapping["roleId"] == "system_admin" - assert mapping["enabled"] is True - - # Verify TOOL_GRANT item - resp = dynamodb_table.get_item( - Key={"PK": "ROLE#system_admin", "SK": "TOOL_GRANT#*"} - ) - assert "Item" in resp - - # Verify MODEL_GRANT item - resp = dynamodb_table.get_item( - Key={"PK": "ROLE#system_admin", "SK": "MODEL_GRANT#*"} - ) - assert "Item" in resp - - def test_skips_when_mapping_already_exists(self, dynamodb_table): - """When system_admin already has the correct mapping, skip.""" - # Seed first - seed_system_admin_jwt_roles(TABLE_NAME, REGION, "Admin") - - # Seed again with same value - result = seed_system_admin_jwt_roles(TABLE_NAME, REGION, "Admin") - - assert result.skipped == 1 - assert result.created == 0 - assert result.failed == 0 - - def test_updates_when_mapping_differs(self, dynamodb_table): - """When system_admin has a different mapping, replace it.""" - # Seed with initial value - seed_system_admin_jwt_roles(TABLE_NAME, REGION, "OldRole") - - # Verify initial mapping - resp = dynamodb_table.get_item( - Key={"PK": "ROLE#system_admin", "SK": "JWT_MAPPING#OldRole"} - ) - assert "Item" in resp - - # Update to new value - result = seed_system_admin_jwt_roles(TABLE_NAME, REGION, "NewRole") - - assert result.created == 1 - assert result.failed == 0 - - # Old mapping should be gone - resp = dynamodb_table.get_item( - Key={"PK": "ROLE#system_admin", "SK": "JWT_MAPPING#OldRole"} - ) - assert "Item" not in resp - - # New mapping should exist with correct GSI keys - resp = dynamodb_table.get_item( - Key={"PK": "ROLE#system_admin", "SK": "JWT_MAPPING#NewRole"} - ) - mapping = resp["Item"] - assert mapping["GSI1PK"] == "JWT_ROLE#NewRole" - assert mapping["GSI1SK"] == "ROLE#system_admin" - assert mapping["roleId"] == "system_admin" - - # DEFINITION should reflect new mapping - resp = dynamodb_table.get_item( - Key={"PK": "ROLE#system_admin", "SK": "DEFINITION"} - ) - assert resp["Item"]["jwtRoleMappings"] == ["NewRole"] - - def test_gsi_queryable_after_creation(self, dynamodb_table): - """JWT_MAPPING items should be queryable via the GSI.""" - seed_system_admin_jwt_roles(TABLE_NAME, REGION, "DotNetDevelopers") - - # Query the GSI as AppRoleService would - resp = dynamodb_table.query( - IndexName="JwtRoleMappingIndex", - KeyConditionExpression=( - boto3.dynamodb.conditions.Key("GSI1PK").eq("JWT_ROLE#DotNetDevelopers") - ), - ) - - items = resp["Items"] - assert len(items) == 1 - assert items[0]["roleId"] == "system_admin" - assert items[0]["GSI1SK"] == "ROLE#system_admin" - - class TestSeedSystemAdminRole: def test_creates_role_with_grants(self, dynamodb_table): - """Creates DEFINITION + TOOL_GRANT#* + MODEL_GRANT#* without JWT mapping.""" + """Creates DEFINITION + TOOL_GRANT#* + MODEL_GRANT#* + JWT_MAPPING#system_admin.""" result = seed_system_admin_role(TABLE_NAME, REGION) assert result.created == 1 @@ -178,7 +68,7 @@ def test_creates_role_with_grants(self, dynamodb_table): ) item = resp["Item"] assert item["roleId"] == "system_admin" - assert item["jwtRoleMappings"] == [] + assert item["jwtRoleMappings"] == ["system_admin"] assert item["grantedTools"] == ["*"] assert item["grantedModels"] == ["*"] assert item["isSystemRole"] is True @@ -202,6 +92,16 @@ def test_creates_role_with_grants(self, dynamodb_table): assert grant["GSI3SK"] == "ROLE#system_admin" assert grant["enabled"] is True + # Verify JWT_MAPPING#system_admin (maps Cognito group → AppRole) + resp = dynamodb_table.get_item( + Key={"PK": "ROLE#system_admin", "SK": "JWT_MAPPING#system_admin"} + ) + mapping = resp["Item"] + assert mapping["GSI1PK"] == "JWT_ROLE#system_admin" + assert mapping["GSI1SK"] == "ROLE#system_admin" + assert mapping["roleId"] == "system_admin" + assert mapping["enabled"] is True + def test_skips_when_role_exists(self, dynamodb_table): """Skips if system_admin DEFINITION already present.""" seed_system_admin_role(TABLE_NAME, REGION) @@ -211,25 +111,6 @@ def test_skips_when_role_exists(self, dynamodb_table): assert result.skipped == 1 assert result.created == 0 - def test_jwt_seeder_works_after_role_seeder(self, dynamodb_table): - """JWT mapping seeder correctly updates role created without mappings.""" - seed_system_admin_role(TABLE_NAME, REGION) - - result = seed_system_admin_jwt_roles(TABLE_NAME, REGION, "Admin") - assert result.created == 1 - - # DEFINITION should now have the JWT mapping - resp = dynamodb_table.get_item( - Key={"PK": "ROLE#system_admin", "SK": "DEFINITION"} - ) - assert resp["Item"]["jwtRoleMappings"] == ["Admin"] - - # JWT_MAPPING item should exist - resp = dynamodb_table.get_item( - Key={"PK": "ROLE#system_admin", "SK": "JWT_MAPPING#Admin"} - ) - assert resp["Item"]["GSI1PK"] == "JWT_ROLE#Admin" - class TestSeedDefaultTools: def test_creates_both_tools(self, dynamodb_table): diff --git a/backend/uv.lock b/backend/uv.lock index 7d696dd5..40945a8c 100644 --- a/backend/uv.lock +++ b/backend/uv.lock @@ -10,7 +10,7 @@ resolution-markers = [ [[package]] name = "agentcore-stack" -version = "1.0.0b20" +version = "1.0.0b22" source = { editable = "." } dependencies = [ { name = "aiofiles" }, @@ -40,7 +40,7 @@ all = [ { name = "black" }, { name = "google-genai" }, { name = "hypothesis" }, - { name = "moto", extra = ["dynamodb"] }, + { name = "moto", extra = ["cognitoidp", "dynamodb"] }, { name = "mypy" }, { name = "numpy" }, { name = "openai" }, @@ -56,7 +56,7 @@ all = [ dev = [ { name = "black" }, { name = "hypothesis" }, - { name = "moto", extra = ["dynamodb"] }, + { name = "moto", extra = ["cognitoidp", "dynamodb"] }, { name = "mypy" }, { name = "numpy" }, { name = "pytest" }, @@ -73,16 +73,16 @@ requires-dist = [ { name = "aiofiles", specifier = "==25.1.0" }, { name = "authlib", specifier = "==1.6.9" }, { name = "aws-opentelemetry-distro", marker = "extra == 'agentcore'", specifier = "==0.16.0" }, - { name = "bedrock-agentcore", marker = "extra == 'agentcore'", specifier = "==1.4.8" }, + { name = "bedrock-agentcore", marker = "extra == 'agentcore'", specifier = "==1.6.0" }, { name = "black", marker = "extra == 'dev'", specifier = "==26.3.1" }, - { name = "boto3", specifier = "==1.42.78" }, + { name = "boto3", specifier = "==1.42.83" }, { name = "cachetools", specifier = "==6.2.4" }, - { name = "fastapi", specifier = "==0.135.2" }, - { name = "google-genai", marker = "extra == 'agentcore'", specifier = "==1.69.0" }, + { name = "fastapi", specifier = "==0.135.3" }, + { name = "google-genai", marker = "extra == 'agentcore'", specifier = "==1.70.0" }, { name = "httpx", specifier = "==0.28.1" }, - { name = "hypothesis", marker = "extra == 'dev'", specifier = "==6.151.10" }, - { name = "moto", extras = ["dynamodb"], marker = "extra == 'dev'", specifier = "==5.1.22" }, - { name = "mypy", marker = "extra == 'dev'", specifier = "==1.19.1" }, + { name = "hypothesis", marker = "extra == 'dev'", specifier = "==6.151.11" }, + { name = "moto", extras = ["dynamodb", "cognitoidp"], marker = "extra == 'dev'", specifier = "==5.1.22" }, + { name = "mypy", marker = "extra == 'dev'", specifier = "==1.20.0" }, { name = "numpy", marker = "extra == 'dev'", specifier = "==2.2.6" }, { name = "openai", marker = "extra == 'agentcore'", specifier = "==2.30.0" }, { name = "pyjwt", extras = ["crypto"], specifier = "==2.12.1" }, @@ -90,13 +90,13 @@ requires-dist = [ { name = "pytest-asyncio", marker = "extra == 'dev'", specifier = "==1.3.0" }, { name = "pytest-cov", marker = "extra == 'dev'", specifier = "==7.1.0" }, { name = "python-dotenv", specifier = "==1.2.2" }, - { name = "ruff", marker = "extra == 'dev'", specifier = "==0.15.8" }, + { name = "ruff", marker = "extra == 'dev'", specifier = "==0.15.9" }, { name = "starlette", specifier = "==1.0.0" }, - { name = "strands-agents", marker = "extra == 'agentcore'", specifier = "==1.33.0" }, + { name = "strands-agents", marker = "extra == 'agentcore'", specifier = "==1.34.1" }, { name = "strands-agents-tools", marker = "extra == 'agentcore'", specifier = "==0.3.0" }, { name = "tiktoken", marker = "extra == 'dev'", specifier = "==0.12.0" }, { name = "types-aiofiles", marker = "extra == 'dev'", specifier = "==25.1.0.20251011" }, - { name = "uvicorn", extras = ["standard"], specifier = "==0.42.0" }, + { name = "uvicorn", extras = ["standard"], specifier = "==0.44.0" }, ] provides-extras = ["agentcore", "dev", "all"] @@ -432,7 +432,7 @@ wheels = [ [[package]] name = "bedrock-agentcore" -version = "1.4.8" +version = "1.6.0" source = { registry = "https://pypi.org/simple" } dependencies = [ { name = "boto3" }, @@ -444,9 +444,9 @@ dependencies = [ { name = "uvicorn" }, { name = "websockets" }, ] -sdist = { url = "https://files.pythonhosted.org/packages/56/99/b08e9e6b849599316100b898f5ba27057f5141aaea36bcaf0ed3f695fdd5/bedrock_agentcore-1.4.8.tar.gz", hash = "sha256:ebabf85307b3590ef58c5ea25234cc3824560b5a7579f725bb00a8df7df6c4d4", size = 487391, upload-time = "2026-03-26T22:33:31.873Z" } +sdist = { url = "https://files.pythonhosted.org/packages/ca/f6/2884c954343e794e3419348f5ffb0276a26f57b30af11f9fe63c4ca535c0/bedrock_agentcore-1.6.0.tar.gz", hash = "sha256:7ea176c3226dc6af8c399a8f9abb58629948cd8ed8675ece9f2f32b94e861b92", size = 512010, upload-time = "2026-03-31T23:10:06.561Z" } wheels = [ - { url = "https://files.pythonhosted.org/packages/ec/6d/677b74eaa3c1f6601ff28b4c652c4c2cf313b7fb84cf36949d8ca0869029/bedrock_agentcore-1.4.8-py3-none-any.whl", hash = "sha256:9f0fb653d0f3cadca082132b49e73852483527824d93728eb4cefc0ce60545b4", size = 149662, upload-time = "2026-03-26T22:33:30.016Z" }, + { url = "https://files.pythonhosted.org/packages/a2/f8/bcf158979324f4f4d171588afffadb2154fa8499701290bfc7bdaf82bd3a/bedrock_agentcore-1.6.0-py3-none-any.whl", hash = "sha256:a4cd02f2bfb80fcc7a8c8835be8d55c778339f8286b071ac3aae579460dd2eb2", size = 164034, upload-time = "2026-03-31T23:10:04.902Z" }, ] [[package]] @@ -495,30 +495,30 @@ wheels = [ [[package]] name = "boto3" -version = "1.42.78" +version = "1.42.83" source = { registry = "https://pypi.org/simple" } dependencies = [ { name = "botocore" }, { name = "jmespath" }, { name = "s3transfer" }, ] -sdist = { url = "https://files.pythonhosted.org/packages/a8/2b/ebdad075934cf6bb78bf81fe31d83339bcd804ad6c856f7341376cbc88b6/boto3-1.42.78.tar.gz", hash = "sha256:cef2ebdb9be5c0e96822f8d3941ac4b816c90a5737a7ffb901d664c808964b63", size = 112789, upload-time = "2026-03-27T19:28:07.58Z" } +sdist = { url = "https://files.pythonhosted.org/packages/9f/87/1ed88eaa1e814841a37e71fee74c2b74341d14b791c0c6038b7ba914bea1/boto3-1.42.83.tar.gz", hash = "sha256:cc5621e603982cb3145b7f6c9970e02e297a1a0eb94637cc7f7b69d3017640ee", size = 112719, upload-time = "2026-04-03T19:34:21.254Z" } wheels = [ - { url = "https://files.pythonhosted.org/packages/57/bb/1f6dade1f1e86858bef7bd332bc8106c445f2dbabec7b32ab5d7d118c9b6/boto3-1.42.78-py3-none-any.whl", hash = "sha256:480a34a077484a5ca60124dfd150ba3ea6517fc89963a679e45b30c6db614d26", size = 140556, upload-time = "2026-03-27T19:28:06.125Z" }, + { url = "https://files.pythonhosted.org/packages/c1/b1/8a066bc8f02937d49783c0b3948ab951d8284e6fde436cab9f359dbd4d93/boto3-1.42.83-py3-none-any.whl", hash = "sha256:544846fdb10585bb7837e409868e8e04c6b372fa04479ba1597ce82cf1242076", size = 140555, upload-time = "2026-04-03T19:34:17.935Z" }, ] [[package]] name = "botocore" -version = "1.42.80" +version = "1.42.85" source = { registry = "https://pypi.org/simple" } dependencies = [ { name = "jmespath" }, { name = "python-dateutil" }, { name = "urllib3" }, ] -sdist = { url = "https://files.pythonhosted.org/packages/2e/42/d0ce09fe5b494e2a9de513206dec90fbe72bcb101457a60f526a6b1c300b/botocore-1.42.80.tar.gz", hash = "sha256:fe32af53dc87f5f4d61879bc231e2ca2cc0719b19b8f6d268e82a34f713a8a09", size = 15110373, upload-time = "2026-03-31T19:33:33.82Z" } +sdist = { url = "https://files.pythonhosted.org/packages/0a/ac/7f14b05cf43e4baae99f4570b02e10b2aebf242dfd86245523340390c834/botocore-1.42.85.tar.gz", hash = "sha256:2ee61f80b7724a143e16d0a85408ef5fa20b99dce7a3c8ec5d25cc8dced164c1", size = 15159562, upload-time = "2026-04-07T19:40:43.831Z" } wheels = [ - { url = "https://files.pythonhosted.org/packages/17/b0/c03f2ed8e7817db1c22d70720636a1b22a2a4d3aa3c09da0257072b30bc5/botocore-1.42.80-py3-none-any.whl", hash = "sha256:7291632b2ede71b7c69e6e366480bb6e2a5d2fae8f7d2d2eb49215e32b7c7a12", size = 14787168, upload-time = "2026-03-31T19:33:29.396Z" }, + { url = "https://files.pythonhosted.org/packages/16/f3/c1fbaff4c509c616fd01f44357283a8992f10b3a05d932b22e602aa3a221/botocore-1.42.85-py3-none-any.whl", hash = "sha256:828b67722caeb7e240eefedee74050e803d1fa102958ead9c4009101eefd5381", size = 14839741, upload-time = "2026-04-07T19:40:40.733Z" }, ] [[package]] @@ -980,7 +980,7 @@ wheels = [ [[package]] name = "fastapi" -version = "0.135.2" +version = "0.135.3" source = { registry = "https://pypi.org/simple" } dependencies = [ { name = "annotated-doc" }, @@ -989,9 +989,9 @@ dependencies = [ { name = "typing-extensions" }, { name = "typing-inspection" }, ] -sdist = { url = "https://files.pythonhosted.org/packages/c4/73/5903c4b13beae98618d64eb9870c3fac4f605523dd0312ca5c80dadbd5b9/fastapi-0.135.2.tar.gz", hash = "sha256:88a832095359755527b7f63bb4c6bc9edb8329a026189eed83d6c1afcf419d56", size = 395833, upload-time = "2026-03-23T14:12:41.697Z" } +sdist = { url = "https://files.pythonhosted.org/packages/f7/e6/7adb4c5fa231e82c35b8f5741a9f2d055f520c29af5546fd70d3e8e1cd2e/fastapi-0.135.3.tar.gz", hash = "sha256:bd6d7caf1a2bdd8d676843cdcd2287729572a1ef524fc4d65c17ae002a1be654", size = 396524, upload-time = "2026-04-01T16:23:58.188Z" } wheels = [ - { url = "https://files.pythonhosted.org/packages/8f/ea/18f6d0457f9efb2fc6fa594857f92810cadb03024975726db6546b3d6fcf/fastapi-0.135.2-py3-none-any.whl", hash = "sha256:0af0447d541867e8db2a6a25c23a8c4bd80e2394ac5529bd87501bbb9e240ca5", size = 117407, upload-time = "2026-03-23T14:12:43.284Z" }, + { url = "https://files.pythonhosted.org/packages/84/a4/5caa2de7f917a04ada20018eccf60d6cc6145b0199d55ca3711b0fc08312/fastapi-0.135.3-py3-none-any.whl", hash = "sha256:9b0f590c813acd13d0ab43dd8494138eb58e484bfac405db1f3187cfc5810d98", size = 117734, upload-time = "2026-04-01T16:23:59.328Z" }, ] [[package]] @@ -1135,7 +1135,7 @@ requests = [ [[package]] name = "google-genai" -version = "1.69.0" +version = "1.70.0" source = { registry = "https://pypi.org/simple" } dependencies = [ { name = "anyio" }, @@ -1149,9 +1149,9 @@ dependencies = [ { name = "typing-extensions" }, { name = "websockets" }, ] -sdist = { url = "https://files.pythonhosted.org/packages/00/5e/c0a5e6ff60d18d3f19819a9b1fbd6a1ef2162d025696d8660550739168dc/google_genai-1.69.0.tar.gz", hash = "sha256:5f1a6a478e0c5851506a3d337534bab27b3c33120e27bf9174507ea79dfb8673", size = 519538, upload-time = "2026-03-28T15:33:27.308Z" } +sdist = { url = "https://files.pythonhosted.org/packages/74/dd/28e4682904b183acbfad3fe6409f13a42f69bb8eab6e882d3bcbea1dde01/google_genai-1.70.0.tar.gz", hash = "sha256:36b67b0fc6f319e08d1f1efd808b790107b1809c8743a05d55dfcf9d9fad7719", size = 519550, upload-time = "2026-04-01T10:52:46.487Z" } wheels = [ - { url = "https://files.pythonhosted.org/packages/42/58/ef0586019f54b2ebb36deed7608ccb5efe1377564d2aaea6b1e295d1fadc/google_genai-1.69.0-py3-none-any.whl", hash = "sha256:252e714d724aba74949647b9de511a6a6f7804b3b317ab39ddee9cc2f001cacc", size = 760551, upload-time = "2026-03-28T15:33:24.957Z" }, + { url = "https://files.pythonhosted.org/packages/36/a3/d4564c8a9beaf6a3cef8d70fa6354318572cebfee65db4f01af0d41f45ba/google_genai-1.70.0-py3-none-any.whl", hash = "sha256:b74c24549d8b4208f4c736fd11857374788e1ffffc725de45d706e35c97fceee", size = 760584, upload-time = "2026-04-01T10:52:44.349Z" }, ] [[package]] @@ -1318,15 +1318,15 @@ wheels = [ [[package]] name = "hypothesis" -version = "6.151.10" +version = "6.151.11" source = { registry = "https://pypi.org/simple" } dependencies = [ { name = "exceptiongroup", marker = "python_full_version < '3.11'" }, { name = "sortedcontainers" }, ] -sdist = { url = "https://files.pythonhosted.org/packages/f5/dd/633e2cd62377333b7681628aee2ec1d88166f5bdf916b08c98b1e8288ad3/hypothesis-6.151.10.tar.gz", hash = "sha256:6c9565af8b4aa3a080b508f66ce9c2a77dd613c7e9073e27fc7e4ef9f45f8a27", size = 463762, upload-time = "2026-03-29T01:06:22.19Z" } +sdist = { url = "https://files.pythonhosted.org/packages/a9/58/41af0d539b3c95644d1e4e353cbd6ac9473e892ea21802546a8886b79078/hypothesis-6.151.11.tar.gz", hash = "sha256:f33dcb68b62c7b07c9ac49664989be898fa8ce57583f0dc080259a197c6c7ff1", size = 463779, upload-time = "2026-04-05T17:35:55.935Z" } wheels = [ - { url = "https://files.pythonhosted.org/packages/40/da/439bb2e451979f5e88c13bbebc3e9e17754429cfb528c93677b2bd81783b/hypothesis-6.151.10-py3-none-any.whl", hash = "sha256:b0d7728f0c8c2be009f89fcdd6066f70c5439aa0f94adbb06e98261d05f49b05", size = 529493, upload-time = "2026-03-29T01:06:19.161Z" }, + { url = "https://files.pythonhosted.org/packages/1d/06/f49393eca84b87b17a67aaebf9f6251190ba1e9fe9f2236504049fc43fee/hypothesis-6.151.11-py3-none-any.whl", hash = "sha256:7ac05173206746cec8312f95164a30a4eb4916815413a278922e63ff1e404648", size = 529572, upload-time = "2026-04-05T17:35:53.438Z" }, ] [[package]] @@ -1477,6 +1477,18 @@ wheels = [ { url = "https://files.pythonhosted.org/packages/14/2f/967ba146e6d58cf6a652da73885f52fc68001525b4197effc174321d70b4/jmespath-1.1.0-py3-none-any.whl", hash = "sha256:a5663118de4908c91729bea0acadca56526eb2698e83de10cd116ae0f4e97c64", size = 20419, upload-time = "2026-01-22T16:35:24.919Z" }, ] +[[package]] +name = "joserfc" +version = "1.6.3" +source = { registry = "https://pypi.org/simple" } +dependencies = [ + { name = "cryptography" }, +] +sdist = { url = "https://files.pythonhosted.org/packages/ce/90/b8cc8635c4ce2e5e8104bf26ef147f6e599478f6329107283cdc53aae97f/joserfc-1.6.3.tar.gz", hash = "sha256:c00c2830db969b836cba197e830e738dd9dda0955f1794e55d3c636f17f5c9a6", size = 229090, upload-time = "2026-02-25T15:33:38.167Z" } +wheels = [ + { url = "https://files.pythonhosted.org/packages/12/4f/124b3301067b752f44f292f0b9a74e837dd75ff863ee39500a082fc4c733/joserfc-1.6.3-py3-none-any.whl", hash = "sha256:6beab3635358cbc565cb94fb4c53d0557e6d10a15b933e2134939351590bda9a", size = 70465, upload-time = "2026-02-25T15:33:36.997Z" }, +] + [[package]] name = "jsonschema" version = "4.26.0" @@ -1754,6 +1766,9 @@ wheels = [ ] [package.optional-dependencies] +cognitoidp = [ + { name = "joserfc" }, +] dynamodb = [ { name = "docker" }, { name = "py-partiql-parser" }, @@ -1908,7 +1923,7 @@ wheels = [ [[package]] name = "mypy" -version = "1.19.1" +version = "1.20.0" source = { registry = "https://pypi.org/simple" } dependencies = [ { name = "librt", marker = "platform_python_implementation != 'PyPy'" }, @@ -1917,39 +1932,51 @@ dependencies = [ { name = "tomli", marker = "python_full_version < '3.11'" }, { name = "typing-extensions" }, ] -sdist = { url = "https://files.pythonhosted.org/packages/f5/db/4efed9504bc01309ab9c2da7e352cc223569f05478012b5d9ece38fd44d2/mypy-1.19.1.tar.gz", hash = "sha256:19d88bb05303fe63f71dd2c6270daca27cb9401c4ca8255fe50d1d920e0eb9ba", size = 3582404, upload-time = "2025-12-15T05:03:48.42Z" } -wheels = [ - { url = "https://files.pythonhosted.org/packages/2f/63/e499890d8e39b1ff2df4c0c6ce5d371b6844ee22b8250687a99fd2f657a8/mypy-1.19.1-cp310-cp310-macosx_10_9_x86_64.whl", hash = "sha256:5f05aa3d375b385734388e844bc01733bd33c644ab48e9684faa54e5389775ec", size = 13101333, upload-time = "2025-12-15T05:03:03.28Z" }, - { url = "https://files.pythonhosted.org/packages/72/4b/095626fc136fba96effc4fd4a82b41d688ab92124f8c4f7564bffe5cf1b0/mypy-1.19.1-cp310-cp310-macosx_11_0_arm64.whl", hash = "sha256:022ea7279374af1a5d78dfcab853fe6a536eebfda4b59deab53cd21f6cd9f00b", size = 12164102, upload-time = "2025-12-15T05:02:33.611Z" }, - { url = "https://files.pythonhosted.org/packages/0c/5b/952928dd081bf88a83a5ccd49aaecfcd18fd0d2710c7ff07b8fb6f7032b9/mypy-1.19.1-cp310-cp310-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:ee4c11e460685c3e0c64a4c5de82ae143622410950d6be863303a1c4ba0e36d6", size = 12765799, upload-time = "2025-12-15T05:03:28.44Z" }, - { url = "https://files.pythonhosted.org/packages/2a/0d/93c2e4a287f74ef11a66fb6d49c7a9f05e47b0a4399040e6719b57f500d2/mypy-1.19.1-cp310-cp310-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:de759aafbae8763283b2ee5869c7255391fbc4de3ff171f8f030b5ec48381b74", size = 13522149, upload-time = "2025-12-15T05:02:36.011Z" }, - { url = "https://files.pythonhosted.org/packages/7b/0e/33a294b56aaad2b338d203e3a1d8b453637ac36cb278b45005e0901cf148/mypy-1.19.1-cp310-cp310-musllinux_1_2_x86_64.whl", hash = "sha256:ab43590f9cd5108f41aacf9fca31841142c786827a74ab7cc8a2eacb634e09a1", size = 13810105, upload-time = "2025-12-15T05:02:40.327Z" }, - { url = "https://files.pythonhosted.org/packages/0e/fd/3e82603a0cb66b67c5e7abababce6bf1a929ddf67bf445e652684af5c5a0/mypy-1.19.1-cp310-cp310-win_amd64.whl", hash = "sha256:2899753e2f61e571b3971747e302d5f420c3fd09650e1951e99f823bc3089dac", size = 10057200, upload-time = "2025-12-15T05:02:51.012Z" }, - { url = "https://files.pythonhosted.org/packages/ef/47/6b3ebabd5474d9cdc170d1342fbf9dddc1b0ec13ec90bf9004ee6f391c31/mypy-1.19.1-cp311-cp311-macosx_10_9_x86_64.whl", hash = "sha256:d8dfc6ab58ca7dda47d9237349157500468e404b17213d44fc1cb77bce532288", size = 13028539, upload-time = "2025-12-15T05:03:44.129Z" }, - { url = "https://files.pythonhosted.org/packages/5c/a6/ac7c7a88a3c9c54334f53a941b765e6ec6c4ebd65d3fe8cdcfbe0d0fd7db/mypy-1.19.1-cp311-cp311-macosx_11_0_arm64.whl", hash = "sha256:e3f276d8493c3c97930e354b2595a44a21348b320d859fb4a2b9f66da9ed27ab", size = 12083163, upload-time = "2025-12-15T05:03:37.679Z" }, - { url = "https://files.pythonhosted.org/packages/67/af/3afa9cf880aa4a2c803798ac24f1d11ef72a0c8079689fac5cfd815e2830/mypy-1.19.1-cp311-cp311-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:2abb24cf3f17864770d18d673c85235ba52456b36a06b6afc1e07c1fdcd3d0e6", size = 12687629, upload-time = "2025-12-15T05:02:31.526Z" }, - { url = "https://files.pythonhosted.org/packages/2d/46/20f8a7114a56484ab268b0ab372461cb3a8f7deed31ea96b83a4e4cfcfca/mypy-1.19.1-cp311-cp311-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:a009ffa5a621762d0c926a078c2d639104becab69e79538a494bcccb62cc0331", size = 13436933, upload-time = "2025-12-15T05:03:15.606Z" }, - { url = "https://files.pythonhosted.org/packages/5b/f8/33b291ea85050a21f15da910002460f1f445f8007adb29230f0adea279cb/mypy-1.19.1-cp311-cp311-musllinux_1_2_x86_64.whl", hash = "sha256:f7cee03c9a2e2ee26ec07479f38ea9c884e301d42c6d43a19d20fb014e3ba925", size = 13661754, upload-time = "2025-12-15T05:02:26.731Z" }, - { url = "https://files.pythonhosted.org/packages/fd/a3/47cbd4e85bec4335a9cd80cf67dbc02be21b5d4c9c23ad6b95d6c5196bac/mypy-1.19.1-cp311-cp311-win_amd64.whl", hash = "sha256:4b84a7a18f41e167f7995200a1d07a4a6810e89d29859df936f1c3923d263042", size = 10055772, upload-time = "2025-12-15T05:03:26.179Z" }, - { url = "https://files.pythonhosted.org/packages/06/8a/19bfae96f6615aa8a0604915512e0289b1fad33d5909bf7244f02935d33a/mypy-1.19.1-cp312-cp312-macosx_10_13_x86_64.whl", hash = "sha256:a8174a03289288c1f6c46d55cef02379b478bfbc8e358e02047487cad44c6ca1", size = 13206053, upload-time = "2025-12-15T05:03:46.622Z" }, - { url = "https://files.pythonhosted.org/packages/a5/34/3e63879ab041602154ba2a9f99817bb0c85c4df19a23a1443c8986e4d565/mypy-1.19.1-cp312-cp312-macosx_11_0_arm64.whl", hash = "sha256:ffcebe56eb09ff0c0885e750036a095e23793ba6c2e894e7e63f6d89ad51f22e", size = 12219134, upload-time = "2025-12-15T05:03:24.367Z" }, - { url = "https://files.pythonhosted.org/packages/89/cc/2db6f0e95366b630364e09845672dbee0cbf0bbe753a204b29a944967cd9/mypy-1.19.1-cp312-cp312-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:b64d987153888790bcdb03a6473d321820597ab8dd9243b27a92153c4fa50fd2", size = 12731616, upload-time = "2025-12-15T05:02:44.725Z" }, - { url = "https://files.pythonhosted.org/packages/00/be/dd56c1fd4807bc1eba1cf18b2a850d0de7bacb55e158755eb79f77c41f8e/mypy-1.19.1-cp312-cp312-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:c35d298c2c4bba75feb2195655dfea8124d855dfd7343bf8b8c055421eaf0cf8", size = 13620847, upload-time = "2025-12-15T05:03:39.633Z" }, - { url = "https://files.pythonhosted.org/packages/6d/42/332951aae42b79329f743bf1da088cd75d8d4d9acc18fbcbd84f26c1af4e/mypy-1.19.1-cp312-cp312-musllinux_1_2_x86_64.whl", hash = "sha256:34c81968774648ab5ac09c29a375fdede03ba253f8f8287847bd480782f73a6a", size = 13834976, upload-time = "2025-12-15T05:03:08.786Z" }, - { url = "https://files.pythonhosted.org/packages/6f/63/e7493e5f90e1e085c562bb06e2eb32cae27c5057b9653348d38b47daaecc/mypy-1.19.1-cp312-cp312-win_amd64.whl", hash = "sha256:b10e7c2cd7870ba4ad9b2d8a6102eb5ffc1f16ca35e3de6bfa390c1113029d13", size = 10118104, upload-time = "2025-12-15T05:03:10.834Z" }, - { url = "https://files.pythonhosted.org/packages/de/9f/a6abae693f7a0c697dbb435aac52e958dc8da44e92e08ba88d2e42326176/mypy-1.19.1-cp313-cp313-macosx_10_13_x86_64.whl", hash = "sha256:e3157c7594ff2ef1634ee058aafc56a82db665c9438fd41b390f3bde1ab12250", size = 13201927, upload-time = "2025-12-15T05:02:29.138Z" }, - { url = "https://files.pythonhosted.org/packages/9a/a4/45c35ccf6e1c65afc23a069f50e2c66f46bd3798cbe0d680c12d12935caa/mypy-1.19.1-cp313-cp313-macosx_11_0_arm64.whl", hash = "sha256:bdb12f69bcc02700c2b47e070238f42cb87f18c0bc1fc4cdb4fb2bc5fd7a3b8b", size = 12206730, upload-time = "2025-12-15T05:03:01.325Z" }, - { url = "https://files.pythonhosted.org/packages/05/bb/cdcf89678e26b187650512620eec8368fded4cfd99cfcb431e4cdfd19dec/mypy-1.19.1-cp313-cp313-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:f859fb09d9583a985be9a493d5cfc5515b56b08f7447759a0c5deaf68d80506e", size = 12724581, upload-time = "2025-12-15T05:03:20.087Z" }, - { url = "https://files.pythonhosted.org/packages/d1/32/dd260d52babf67bad8e6770f8e1102021877ce0edea106e72df5626bb0ec/mypy-1.19.1-cp313-cp313-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:c9a6538e0415310aad77cb94004ca6482330fece18036b5f360b62c45814c4ef", size = 13616252, upload-time = "2025-12-15T05:02:49.036Z" }, - { url = "https://files.pythonhosted.org/packages/71/d0/5e60a9d2e3bd48432ae2b454b7ef2b62a960ab51292b1eda2a95edd78198/mypy-1.19.1-cp313-cp313-musllinux_1_2_x86_64.whl", hash = "sha256:da4869fc5e7f62a88f3fe0b5c919d1d9f7ea3cef92d3689de2823fd27e40aa75", size = 13840848, upload-time = "2025-12-15T05:02:55.95Z" }, - { url = "https://files.pythonhosted.org/packages/98/76/d32051fa65ecf6cc8c6610956473abdc9b4c43301107476ac03559507843/mypy-1.19.1-cp313-cp313-win_amd64.whl", hash = "sha256:016f2246209095e8eda7538944daa1d60e1e8134d98983b9fc1e92c1fc0cb8dd", size = 10135510, upload-time = "2025-12-15T05:02:58.438Z" }, - { url = "https://files.pythonhosted.org/packages/de/eb/b83e75f4c820c4247a58580ef86fcd35165028f191e7e1ba57128c52782d/mypy-1.19.1-cp314-cp314-macosx_10_15_x86_64.whl", hash = "sha256:06e6170bd5836770e8104c8fdd58e5e725cfeb309f0a6c681a811f557e97eac1", size = 13199744, upload-time = "2025-12-15T05:03:30.823Z" }, - { url = "https://files.pythonhosted.org/packages/94/28/52785ab7bfa165f87fcbb61547a93f98bb20e7f82f90f165a1f69bce7b3d/mypy-1.19.1-cp314-cp314-macosx_11_0_arm64.whl", hash = "sha256:804bd67b8054a85447c8954215a906d6eff9cabeabe493fb6334b24f4bfff718", size = 12215815, upload-time = "2025-12-15T05:02:42.323Z" }, - { url = "https://files.pythonhosted.org/packages/0a/c6/bdd60774a0dbfb05122e3e925f2e9e846c009e479dcec4821dad881f5b52/mypy-1.19.1-cp314-cp314-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:21761006a7f497cb0d4de3d8ef4ca70532256688b0523eee02baf9eec895e27b", size = 12740047, upload-time = "2025-12-15T05:03:33.168Z" }, - { url = "https://files.pythonhosted.org/packages/32/2a/66ba933fe6c76bd40d1fe916a83f04fed253152f451a877520b3c4a5e41e/mypy-1.19.1-cp314-cp314-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:28902ee51f12e0f19e1e16fbe2f8f06b6637f482c459dd393efddd0ec7f82045", size = 13601998, upload-time = "2025-12-15T05:03:13.056Z" }, - { url = "https://files.pythonhosted.org/packages/e3/da/5055c63e377c5c2418760411fd6a63ee2b96cf95397259038756c042574f/mypy-1.19.1-cp314-cp314-musllinux_1_2_x86_64.whl", hash = "sha256:481daf36a4c443332e2ae9c137dfee878fcea781a2e3f895d54bd3002a900957", size = 13807476, upload-time = "2025-12-15T05:03:17.977Z" }, - { url = "https://files.pythonhosted.org/packages/cd/09/4ebd873390a063176f06b0dbf1f7783dd87bd120eae7727fa4ae4179b685/mypy-1.19.1-cp314-cp314-win_amd64.whl", hash = "sha256:8bb5c6f6d043655e055be9b542aa5f3bdd30e4f3589163e85f93f3640060509f", size = 10281872, upload-time = "2025-12-15T05:03:05.549Z" }, - { url = "https://files.pythonhosted.org/packages/8d/f4/4ce9a05ce5ded1de3ec1c1d96cf9f9504a04e54ce0ed55cfa38619a32b8d/mypy-1.19.1-py3-none-any.whl", hash = "sha256:f1235f5ea01b7db5468d53ece6aaddf1ad0b88d9e7462b86ef96fe04995d7247", size = 2471239, upload-time = "2025-12-15T05:03:07.248Z" }, +sdist = { url = "https://files.pythonhosted.org/packages/f8/5c/b0089fe7fef0a994ae5ee07029ced0526082c6cfaaa4c10d40a10e33b097/mypy-1.20.0.tar.gz", hash = "sha256:eb96c84efcc33f0b5e0e04beacf00129dd963b67226b01c00b9dfc8affb464c3", size = 3815028, upload-time = "2026-03-31T16:55:14.959Z" } +wheels = [ + { url = "https://files.pythonhosted.org/packages/4d/a2/a965c8c3fcd4fa8b84ba0d46606181b0d0a1d50f274c67877f3e9ed4882c/mypy-1.20.0-cp310-cp310-macosx_10_9_x86_64.whl", hash = "sha256:d99f515f95fd03a90875fdb2cca12ff074aa04490db4d190905851bdf8a549a8", size = 14430138, upload-time = "2026-03-31T16:52:37.843Z" }, + { url = "https://files.pythonhosted.org/packages/53/6e/043477501deeb8eabbab7f1a2f6cac62cfb631806dc1d6862a04a7f5011b/mypy-1.20.0-cp310-cp310-macosx_11_0_arm64.whl", hash = "sha256:bd0212976dc57a5bfeede7c219e7cd66568a32c05c9129686dd487c059c1b88a", size = 13311282, upload-time = "2026-03-31T16:55:11.021Z" }, + { url = "https://files.pythonhosted.org/packages/65/aa/bd89b247b83128197a214f29f0632ff3c14f54d4cd70d144d157bd7d7d6e/mypy-1.20.0-cp310-cp310-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:f8426d4d75d68714abc17a4292d922f6ba2cfb984b72c2278c437f6dae797865", size = 13750889, upload-time = "2026-03-31T16:52:02.909Z" }, + { url = "https://files.pythonhosted.org/packages/fa/9d/2860be7355c45247ccc0be1501c91176318964c2a137bd4743f58ce6200e/mypy-1.20.0-cp310-cp310-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:02cca0761c75b42a20a2757ae58713276605eb29a08dd8a6e092aa347c4115ca", size = 14619788, upload-time = "2026-03-31T16:50:48.928Z" }, + { url = "https://files.pythonhosted.org/packages/75/7f/3ef3e360c91f3de120f205c8ce405e9caf9fc52ef14b65d37073e322c114/mypy-1.20.0-cp310-cp310-musllinux_1_2_x86_64.whl", hash = "sha256:b3a49064504be59e59da664c5e149edc1f26c67c4f8e8456f6ba6aba55033018", size = 14918849, upload-time = "2026-03-31T16:51:10.478Z" }, + { url = "https://files.pythonhosted.org/packages/ae/72/af970dfe167ef788df7c5e6109d2ed0229f164432ce828bc9741a4250e64/mypy-1.20.0-cp310-cp310-win_amd64.whl", hash = "sha256:ebea00201737ad4391142808ed16e875add5c17f676e0912b387739f84991e13", size = 10822007, upload-time = "2026-03-31T16:50:25.268Z" }, + { url = "https://files.pythonhosted.org/packages/93/94/ba9065c2ebe5421619aff684b793d953e438a8bfe31a320dd6d1e0706e81/mypy-1.20.0-cp310-cp310-win_arm64.whl", hash = "sha256:e80cf77847d0d3e6e3111b7b25db32a7f8762fd4b9a3a72ce53fe16a2863b281", size = 9756158, upload-time = "2026-03-31T16:48:36.213Z" }, + { url = "https://files.pythonhosted.org/packages/6e/1c/74cb1d9993236910286865679d1c616b136b2eae468493aa939431eda410/mypy-1.20.0-cp311-cp311-macosx_10_9_x86_64.whl", hash = "sha256:4525e7010b1b38334516181c5b81e16180b8e149e6684cee5a727c78186b4e3b", size = 14343972, upload-time = "2026-03-31T16:49:04.887Z" }, + { url = "https://files.pythonhosted.org/packages/d5/0d/01399515eca280386e308cf57901e68d3a52af18691941b773b3380c1df8/mypy-1.20.0-cp311-cp311-macosx_11_0_arm64.whl", hash = "sha256:a17c5d0bdcca61ce24a35beb828a2d0d323d3fcf387d7512206888c900193367", size = 13225007, upload-time = "2026-03-31T16:50:08.151Z" }, + { url = "https://files.pythonhosted.org/packages/56/ac/b4ba5094fb2d7fe9d2037cd8d18bbe02bcf68fd22ab9ff013f55e57ba095/mypy-1.20.0-cp311-cp311-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:f75ff57defcd0f1d6e006d721ccdec6c88d4f6a7816eb92f1c4890d979d9ee62", size = 13663752, upload-time = "2026-03-31T16:49:26.064Z" }, + { url = "https://files.pythonhosted.org/packages/db/a7/460678d3cf7da252d2288dad0c602294b6ec22a91932ec368cc11e44bb6e/mypy-1.20.0-cp311-cp311-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:b503ab55a836136b619b5fc21c8803d810c5b87551af8600b72eecafb0059cb0", size = 14532265, upload-time = "2026-03-31T16:53:55.077Z" }, + { url = "https://files.pythonhosted.org/packages/a3/3e/051cca8166cf0438ae3ea80e0e7c030d7a8ab98dffc93f80a1aa3f23c1a2/mypy-1.20.0-cp311-cp311-musllinux_1_2_x86_64.whl", hash = "sha256:1973868d2adbb4584a3835780b27436f06d1dc606af5be09f187aaa25be1070f", size = 14768476, upload-time = "2026-03-31T16:50:34.587Z" }, + { url = "https://files.pythonhosted.org/packages/be/66/8e02ec184f852ed5c4abb805583305db475930854e09964b55e107cdcbc4/mypy-1.20.0-cp311-cp311-win_amd64.whl", hash = "sha256:2fcedb16d456106e545b2bfd7ef9d24e70b38ec252d2a629823a4d07ebcdb69e", size = 10818226, upload-time = "2026-03-31T16:53:15.624Z" }, + { url = "https://files.pythonhosted.org/packages/13/4b/383ad1924b28f41e4879a74151e7a5451123330d45652da359f9183bcd45/mypy-1.20.0-cp311-cp311-win_arm64.whl", hash = "sha256:379edf079ce44ac8d2805bcf9b3dd7340d4f97aad3a5e0ebabbf9d125b84b442", size = 9750091, upload-time = "2026-03-31T16:54:12.162Z" }, + { url = "https://files.pythonhosted.org/packages/be/dd/3afa29b58c2e57c79116ed55d700721c3c3b15955e2b6251dd165d377c0e/mypy-1.20.0-cp312-cp312-macosx_10_13_x86_64.whl", hash = "sha256:002b613ae19f4ac7d18b7e168ffe1cb9013b37c57f7411984abbd3b817b0a214", size = 14509525, upload-time = "2026-03-31T16:55:01.824Z" }, + { url = "https://files.pythonhosted.org/packages/54/eb/227b516ab8cad9f2a13c5e7a98d28cd6aa75e9c83e82776ae6c1c4c046c7/mypy-1.20.0-cp312-cp312-macosx_11_0_arm64.whl", hash = "sha256:a9336b5e6712f4adaf5afc3203a99a40b379049104349d747eb3e5a3aa23ac2e", size = 13326469, upload-time = "2026-03-31T16:51:41.23Z" }, + { url = "https://files.pythonhosted.org/packages/57/d4/1ddb799860c1b5ac6117ec307b965f65deeb47044395ff01ab793248a591/mypy-1.20.0-cp312-cp312-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:f13b3e41bce9d257eded794c0f12878af3129d80aacd8a3ee0dee51f3a978651", size = 13705953, upload-time = "2026-03-31T16:48:55.69Z" }, + { url = "https://files.pythonhosted.org/packages/c5/b7/54a720f565a87b893182a2a393370289ae7149e4715859e10e1c05e49154/mypy-1.20.0-cp312-cp312-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:9804c3ad27f78e54e58b32e7cb532d128b43dbfb9f3f9f06262b821a0f6bd3f5", size = 14710363, upload-time = "2026-03-31T16:53:26.948Z" }, + { url = "https://files.pythonhosted.org/packages/b2/2a/74810274848d061f8a8ea4ac23aaad43bd3d8c1882457999c2e568341c57/mypy-1.20.0-cp312-cp312-musllinux_1_2_x86_64.whl", hash = "sha256:697f102c5c1d526bdd761a69f17c6070f9892eebcb94b1a5963d679288c09e78", size = 14947005, upload-time = "2026-03-31T16:50:17.591Z" }, + { url = "https://files.pythonhosted.org/packages/77/91/21b8ba75f958bcda75690951ce6fa6b7138b03471618959529d74b8544e2/mypy-1.20.0-cp312-cp312-win_amd64.whl", hash = "sha256:0ecd63f75fdd30327e4ad8b5704bd6d91fc6c1b2e029f8ee14705e1207212489", size = 10880616, upload-time = "2026-03-31T16:52:19.986Z" }, + { url = "https://files.pythonhosted.org/packages/8a/15/3d8198ef97c1ca03aea010cce4f1d4f3bc5d9849e8c0140111ca2ead9fdd/mypy-1.20.0-cp312-cp312-win_arm64.whl", hash = "sha256:f194db59657c58593a3c47c6dfd7bad4ef4ac12dbc94d01b3a95521f78177e33", size = 9813091, upload-time = "2026-03-31T16:53:44.385Z" }, + { url = "https://files.pythonhosted.org/packages/d6/a7/f64ea7bd592fa431cb597418b6dec4a47f7d0c36325fec7ac67bc8402b94/mypy-1.20.0-cp313-cp313-macosx_10_13_x86_64.whl", hash = "sha256:b20c8b0fd5877abdf402e79a3af987053de07e6fb208c18df6659f708b535134", size = 14485344, upload-time = "2026-03-31T16:49:16.78Z" }, + { url = "https://files.pythonhosted.org/packages/bb/72/8927d84cfc90c6abea6e96663576e2e417589347eb538749a464c4c218a0/mypy-1.20.0-cp313-cp313-macosx_11_0_arm64.whl", hash = "sha256:367e5c993ba34d5054d11937d0485ad6dfc60ba760fa326c01090fc256adf15c", size = 13327400, upload-time = "2026-03-31T16:53:08.02Z" }, + { url = "https://files.pythonhosted.org/packages/ab/4a/11ab99f9afa41aa350178d24a7d2da17043228ea10f6456523f64b5a6cf6/mypy-1.20.0-cp313-cp313-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:f799d9db89fc00446f03281f84a221e50018fc40113a3ba9864b132895619ebe", size = 13706384, upload-time = "2026-03-31T16:52:28.577Z" }, + { url = "https://files.pythonhosted.org/packages/42/79/694ca73979cfb3535ebfe78733844cd5aff2e63304f59bf90585110d975a/mypy-1.20.0-cp313-cp313-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:555658c611099455b2da507582ea20d2043dfdfe7f5ad0add472b1c6238b433f", size = 14700378, upload-time = "2026-03-31T16:48:45.527Z" }, + { url = "https://files.pythonhosted.org/packages/84/24/a022ccab3a46e3d2cdf2e0e260648633640eb396c7e75d5a42818a8d3971/mypy-1.20.0-cp313-cp313-musllinux_1_2_x86_64.whl", hash = "sha256:efe8d70949c3023698c3fca1e94527e7e790a361ab8116f90d11221421cd8726", size = 14932170, upload-time = "2026-03-31T16:49:36.038Z" }, + { url = "https://files.pythonhosted.org/packages/d8/9b/549228d88f574d04117e736f55958bd4908f980f9f5700a07aeb85df005b/mypy-1.20.0-cp313-cp313-win_amd64.whl", hash = "sha256:f49590891d2c2f8a9de15614e32e459a794bcba84693c2394291a2038bbaaa69", size = 10888526, upload-time = "2026-03-31T16:50:59.827Z" }, + { url = "https://files.pythonhosted.org/packages/91/17/15095c0e54a8bc04d22d4ff06b2139d5f142c2e87520b4e39010c4862771/mypy-1.20.0-cp313-cp313-win_arm64.whl", hash = "sha256:76a70bf840495729be47510856b978f1b0ec7d08f257ca38c9d932720bf6b43e", size = 9816456, upload-time = "2026-03-31T16:49:59.537Z" }, + { url = "https://files.pythonhosted.org/packages/4e/0e/6ca4a84cbed9e62384bc0b2974c90395ece5ed672393e553996501625fc5/mypy-1.20.0-cp314-cp314-macosx_10_15_x86_64.whl", hash = "sha256:0f42dfaab7ec1baff3b383ad7af562ab0de573c5f6edb44b2dab016082b89948", size = 14483331, upload-time = "2026-03-31T16:52:57.999Z" }, + { url = "https://files.pythonhosted.org/packages/7d/c5/5fe9d8a729dd9605064691816243ae6c49fde0bd28f6e5e17f6a24203c43/mypy-1.20.0-cp314-cp314-macosx_11_0_arm64.whl", hash = "sha256:31b5dbb55293c1bd27c0fc813a0d2bb5ceef9d65ac5afa2e58f829dab7921fd5", size = 13342047, upload-time = "2026-03-31T16:54:21.555Z" }, + { url = "https://files.pythonhosted.org/packages/4c/33/e18bcfa338ca4e6b2771c85d4c5203e627d0c69d9de5c1a2cf2ba13320ba/mypy-1.20.0-cp314-cp314-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:49d11c6f573a5a08f77fad13faff2139f6d0730ebed2cfa9b3d2702671dd7188", size = 13719585, upload-time = "2026-03-31T16:51:53.89Z" }, + { url = "https://files.pythonhosted.org/packages/6b/8d/93491ff7b79419edc7eabf95cb3b3f7490e2e574b2855c7c7e7394ff933f/mypy-1.20.0-cp314-cp314-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:7d3243c406773185144527f83be0e0aefc7bf4601b0b2b956665608bf7c98a83", size = 14685075, upload-time = "2026-03-31T16:54:04.464Z" }, + { url = "https://files.pythonhosted.org/packages/b5/9d/d924b38a4923f8d164bf2b4ec98bf13beaf6e10a5348b4b137eadae40a6e/mypy-1.20.0-cp314-cp314-musllinux_1_2_x86_64.whl", hash = "sha256:a79c1eba7ac4209f2d850f0edd0a2f8bba88cbfdfefe6fb76a19e9d4fe5e71a2", size = 14919141, upload-time = "2026-03-31T16:54:51.785Z" }, + { url = "https://files.pythonhosted.org/packages/59/98/1da9977016678c0b99d43afe52ed00bb3c1a0c4c995d3e6acca1a6ebb9b4/mypy-1.20.0-cp314-cp314-win_amd64.whl", hash = "sha256:00e047c74d3ec6e71a2eb88e9ea551a2edb90c21f993aefa9e0d2a898e0bb732", size = 11050925, upload-time = "2026-03-31T16:51:30.758Z" }, + { url = "https://files.pythonhosted.org/packages/5e/e3/ba0b7a3143e49a9c4f5967dde6ea4bf8e0b10ecbbcca69af84027160ee89/mypy-1.20.0-cp314-cp314-win_arm64.whl", hash = "sha256:931a7630bba591593dcf6e97224a21ff80fb357e7982628d25e3c618e7f598ef", size = 10001089, upload-time = "2026-03-31T16:49:43.632Z" }, + { url = "https://files.pythonhosted.org/packages/12/28/e617e67b3be9d213cda7277913269c874eb26472489f95d09d89765ce2d8/mypy-1.20.0-cp314-cp314t-macosx_10_15_x86_64.whl", hash = "sha256:26c8b52627b6552f47ff11adb4e1509605f094e29815323e487fc0053ebe93d1", size = 15534710, upload-time = "2026-03-31T16:52:12.506Z" }, + { url = "https://files.pythonhosted.org/packages/6e/0c/3b5f2d3e45dc7169b811adce8451679d9430399d03b168f9b0489f43adaa/mypy-1.20.0-cp314-cp314t-macosx_11_0_arm64.whl", hash = "sha256:39362cdb4ba5f916e7976fccecaab1ba3a83e35f60fa68b64e9a70e221bb2436", size = 14393013, upload-time = "2026-03-31T16:54:41.186Z" }, + { url = "https://files.pythonhosted.org/packages/a3/49/edc8b0aa145cc09c1c74f7ce2858eead9329931dcbbb26e2ad40906daa4e/mypy-1.20.0-cp314-cp314t-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:34506397dbf40c15dc567635d18a21d33827e9ab29014fb83d292a8f4f8953b6", size = 15047240, upload-time = "2026-03-31T16:54:31.955Z" }, + { url = "https://files.pythonhosted.org/packages/42/37/a946bb416e37a57fa752b3100fd5ede0e28df94f92366d1716555d47c454/mypy-1.20.0-cp314-cp314t-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:555493c44a4f5a1b58d611a43333e71a9981c6dbe26270377b6f8174126a0526", size = 15858565, upload-time = "2026-03-31T16:53:36.997Z" }, + { url = "https://files.pythonhosted.org/packages/2f/99/7690b5b5b552db1bd4ff362e4c0eb3107b98d680835e65823fbe888c8b78/mypy-1.20.0-cp314-cp314t-musllinux_1_2_x86_64.whl", hash = "sha256:2721f0ce49cb74a38f00c50da67cb7d36317b5eda38877a49614dc018e91c787", size = 16087874, upload-time = "2026-03-31T16:52:48.313Z" }, + { url = "https://files.pythonhosted.org/packages/aa/76/53e893a498138066acd28192b77495c9357e5a58cc4be753182846b43315/mypy-1.20.0-cp314-cp314t-win_amd64.whl", hash = "sha256:47781555a7aa5fedcc2d16bcd72e0dc83eb272c10dd657f9fb3f9cc08e2e6abb", size = 12572380, upload-time = "2026-03-31T16:49:52.454Z" }, + { url = "https://files.pythonhosted.org/packages/76/9c/6dbdae21f01b7aacddc2c0bbf3c5557aa547827fdf271770fe1e521e7093/mypy-1.20.0-cp314-cp314t-win_arm64.whl", hash = "sha256:c70380fe5d64010f79fb863b9081c7004dd65225d2277333c219d93a10dad4dd", size = 10381174, upload-time = "2026-03-31T16:51:20.179Z" }, + { url = "https://files.pythonhosted.org/packages/21/66/4d734961ce167f0fd8380769b3b7c06dbdd6ff54c2190f3f2ecd22528158/mypy-1.20.0-py3-none-any.whl", hash = "sha256:a6e0641147cbfa7e4e94efdb95c2dab1aff8cfc159ded13e07f308ddccc8c48e", size = 2636365, upload-time = "2026-03-31T16:51:44.911Z" }, ] [[package]] @@ -3942,27 +3969,27 @@ wheels = [ [[package]] name = "ruff" -version = "0.15.8" -source = { registry = "https://pypi.org/simple" } -sdist = { url = "https://files.pythonhosted.org/packages/14/b0/73cf7550861e2b4824950b8b52eebdcc5adc792a00c514406556c5b80817/ruff-0.15.8.tar.gz", hash = "sha256:995f11f63597ee362130d1d5a327a87cb6f3f5eae3094c620bcc632329a4d26e", size = 4610921, upload-time = "2026-03-26T18:39:38.675Z" } -wheels = [ - { url = "https://files.pythonhosted.org/packages/4a/92/c445b0cd6da6e7ae51e954939cb69f97e008dbe750cfca89b8cedc081be7/ruff-0.15.8-py3-none-linux_armv6l.whl", hash = "sha256:cbe05adeba76d58162762d6b239c9056f1a15a55bd4b346cfd21e26cd6ad7bc7", size = 10527394, upload-time = "2026-03-26T18:39:41.566Z" }, - { url = "https://files.pythonhosted.org/packages/eb/92/f1c662784d149ad1414cae450b082cf736430c12ca78367f20f5ed569d65/ruff-0.15.8-py3-none-macosx_10_12_x86_64.whl", hash = "sha256:d3e3d0b6ba8dca1b7ef9ab80a28e840a20070c4b62e56d675c24f366ef330570", size = 10905693, upload-time = "2026-03-26T18:39:30.364Z" }, - { url = "https://files.pythonhosted.org/packages/ca/f2/7a631a8af6d88bcef997eb1bf87cc3da158294c57044aafd3e17030613de/ruff-0.15.8-py3-none-macosx_11_0_arm64.whl", hash = "sha256:6ee3ae5c65a42f273f126686353f2e08ff29927b7b7e203b711514370d500de3", size = 10323044, upload-time = "2026-03-26T18:39:33.37Z" }, - { url = "https://files.pythonhosted.org/packages/67/18/1bf38e20914a05e72ef3b9569b1d5c70a7ef26cd188d69e9ca8ef588d5bf/ruff-0.15.8-py3-none-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:fdce027ada77baa448077ccc6ebb2fa9c3c62fd110d8659d601cf2f475858d94", size = 10629135, upload-time = "2026-03-26T18:39:44.142Z" }, - { url = "https://files.pythonhosted.org/packages/d2/e9/138c150ff9af60556121623d41aba18b7b57d95ac032e177b6a53789d279/ruff-0.15.8-py3-none-manylinux_2_17_armv7l.manylinux2014_armv7l.whl", hash = "sha256:12e617fc01a95e5821648a6df341d80456bd627bfab8a829f7cfc26a14a4b4a3", size = 10348041, upload-time = "2026-03-26T18:39:52.178Z" }, - { url = "https://files.pythonhosted.org/packages/02/f1/5bfb9298d9c323f842c5ddeb85f1f10ef51516ac7a34ba446c9347d898df/ruff-0.15.8-py3-none-manylinux_2_17_i686.manylinux2014_i686.whl", hash = "sha256:432701303b26416d22ba696c39f2c6f12499b89093b61360abc34bcc9bf07762", size = 11121987, upload-time = "2026-03-26T18:39:55.195Z" }, - { url = "https://files.pythonhosted.org/packages/10/11/6da2e538704e753c04e8d86b1fc55712fdbdcc266af1a1ece7a51fff0d10/ruff-0.15.8-py3-none-manylinux_2_17_ppc64le.manylinux2014_ppc64le.whl", hash = "sha256:d910ae974b7a06a33a057cb87d2a10792a3b2b3b35e33d2699fdf63ec8f6b17a", size = 11951057, upload-time = "2026-03-26T18:39:19.18Z" }, - { url = "https://files.pythonhosted.org/packages/83/f0/c9208c5fd5101bf87002fed774ff25a96eea313d305f1e5d5744698dc314/ruff-0.15.8-py3-none-manylinux_2_17_s390x.manylinux2014_s390x.whl", hash = "sha256:2033f963c43949d51e6fdccd3946633c6b37c484f5f98c3035f49c27395a8ab8", size = 11464613, upload-time = "2026-03-26T18:40:06.301Z" }, - { url = "https://files.pythonhosted.org/packages/f8/22/d7f2fabdba4fae9f3b570e5605d5eb4500dcb7b770d3217dca4428484b17/ruff-0.15.8-py3-none-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:0f29b989a55572fb885b77464cf24af05500806ab4edf9a0fd8977f9759d85b1", size = 11257557, upload-time = "2026-03-26T18:39:57.972Z" }, - { url = "https://files.pythonhosted.org/packages/71/8c/382a9620038cf6906446b23ce8632ab8c0811b8f9d3e764f58bedd0c9a6f/ruff-0.15.8-py3-none-manylinux_2_31_riscv64.whl", hash = "sha256:ac51d486bf457cdc985a412fb1801b2dfd1bd8838372fc55de64b1510eff4bec", size = 11169440, upload-time = "2026-03-26T18:39:22.205Z" }, - { url = "https://files.pythonhosted.org/packages/4d/0d/0994c802a7eaaf99380085e4e40c845f8e32a562e20a38ec06174b52ef24/ruff-0.15.8-py3-none-musllinux_1_2_aarch64.whl", hash = "sha256:c9861eb959edab053c10ad62c278835ee69ca527b6dcd72b47d5c1e5648964f6", size = 10605963, upload-time = "2026-03-26T18:39:46.682Z" }, - { url = "https://files.pythonhosted.org/packages/19/aa/d624b86f5b0aad7cef6bbf9cd47a6a02dfdc4f72c92a337d724e39c9d14b/ruff-0.15.8-py3-none-musllinux_1_2_armv7l.whl", hash = "sha256:8d9a5b8ea13f26ae90838afc33f91b547e61b794865374f114f349e9036835fb", size = 10357484, upload-time = "2026-03-26T18:39:49.176Z" }, - { url = "https://files.pythonhosted.org/packages/35/c3/e0b7835d23001f7d999f3895c6b569927c4d39912286897f625736e1fd04/ruff-0.15.8-py3-none-musllinux_1_2_i686.whl", hash = "sha256:c2a33a529fb3cbc23a7124b5c6ff121e4d6228029cba374777bd7649cc8598b8", size = 10830426, upload-time = "2026-03-26T18:40:03.702Z" }, - { url = "https://files.pythonhosted.org/packages/f0/51/ab20b322f637b369383adc341d761eaaa0f0203d6b9a7421cd6e783d81b9/ruff-0.15.8-py3-none-musllinux_1_2_x86_64.whl", hash = "sha256:75e5cd06b1cf3f47a3996cfc999226b19aa92e7cce682dcd62f80d7035f98f49", size = 11345125, upload-time = "2026-03-26T18:39:27.799Z" }, - { url = "https://files.pythonhosted.org/packages/37/e6/90b2b33419f59d0f2c4c8a48a4b74b460709a557e8e0064cf33ad894f983/ruff-0.15.8-py3-none-win32.whl", hash = "sha256:bc1f0a51254ba21767bfa9a8b5013ca8149dcf38092e6a9eb704d876de94dc34", size = 10571959, upload-time = "2026-03-26T18:39:36.117Z" }, - { url = "https://files.pythonhosted.org/packages/1f/a2/ef467cb77099062317154c63f234b8a7baf7cb690b99af760c5b68b9ee7f/ruff-0.15.8-py3-none-win_amd64.whl", hash = "sha256:04f79eff02a72db209d47d665ba7ebcad609d8918a134f86cb13dd132159fc89", size = 11743893, upload-time = "2026-03-26T18:39:25.01Z" }, - { url = "https://files.pythonhosted.org/packages/15/e2/77be4fff062fa78d9b2a4dea85d14785dac5f1d0c1fb58ed52331f0ebe28/ruff-0.15.8-py3-none-win_arm64.whl", hash = "sha256:cf891fa8e3bb430c0e7fac93851a5978fc99c8fa2c053b57b118972866f8e5f2", size = 11048175, upload-time = "2026-03-26T18:40:01.06Z" }, +version = "0.15.9" +source = { registry = "https://pypi.org/simple" } +sdist = { url = "https://files.pythonhosted.org/packages/e6/97/e9f1ca355108ef7194e38c812ef40ba98c7208f47b13ad78d023caa583da/ruff-0.15.9.tar.gz", hash = "sha256:29cbb1255a9797903f6dde5ba0188c707907ff44a9006eb273b5a17bfa0739a2", size = 4617361, upload-time = "2026-04-02T18:17:20.829Z" } +wheels = [ + { url = "https://files.pythonhosted.org/packages/0b/1f/9cdfd0ac4b9d1e5a6cf09bedabdf0b56306ab5e333c85c87281273e7b041/ruff-0.15.9-py3-none-linux_armv6l.whl", hash = "sha256:6efbe303983441c51975c243e26dff328aca11f94b70992f35b093c2e71801e1", size = 10511206, upload-time = "2026-04-02T18:16:41.574Z" }, + { url = "https://files.pythonhosted.org/packages/3d/f6/32bfe3e9c136b35f02e489778d94384118bb80fd92c6d92e7ccd97db12ce/ruff-0.15.9-py3-none-macosx_10_12_x86_64.whl", hash = "sha256:4965bac6ac9ea86772f4e23587746f0b7a395eccabb823eb8bfacc3fa06069f7", size = 10923307, upload-time = "2026-04-02T18:17:08.645Z" }, + { url = "https://files.pythonhosted.org/packages/ca/25/de55f52ab5535d12e7aaba1de37a84be6179fb20bddcbe71ec091b4a3243/ruff-0.15.9-py3-none-macosx_11_0_arm64.whl", hash = "sha256:eaf05aad70ca5b5a0a4b0e080df3a6b699803916d88f006efd1f5b46302daab8", size = 10316722, upload-time = "2026-04-02T18:16:44.206Z" }, + { url = "https://files.pythonhosted.org/packages/48/11/690d75f3fd6278fe55fff7c9eb429c92d207e14b25d1cae4064a32677029/ruff-0.15.9-py3-none-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:9439a342adb8725f32f92732e2bafb6d5246bd7a5021101166b223d312e8fc59", size = 10623674, upload-time = "2026-04-02T18:16:50.951Z" }, + { url = "https://files.pythonhosted.org/packages/bd/ec/176f6987be248fc5404199255522f57af1b4a5a1b57727e942479fec98ad/ruff-0.15.9-py3-none-manylinux_2_17_armv7l.manylinux2014_armv7l.whl", hash = "sha256:9c5e6faf9d97c8edc43877c3f406f47446fc48c40e1442d58cfcdaba2acea745", size = 10351516, upload-time = "2026-04-02T18:16:57.206Z" }, + { url = "https://files.pythonhosted.org/packages/b2/fc/51cffbd2b3f240accc380171d51446a32aa2ea43a40d4a45ada67368fbd2/ruff-0.15.9-py3-none-manylinux_2_17_i686.manylinux2014_i686.whl", hash = "sha256:7b34a9766aeec27a222373d0b055722900fbc0582b24f39661aa96f3fe6ad901", size = 11150202, upload-time = "2026-04-02T18:17:06.452Z" }, + { url = "https://files.pythonhosted.org/packages/d6/d4/25292a6dfc125f6b6528fe6af31f5e996e19bf73ca8e3ce6eb7fa5b95885/ruff-0.15.9-py3-none-manylinux_2_17_ppc64le.manylinux2014_ppc64le.whl", hash = "sha256:89dd695bc72ae76ff484ae54b7e8b0f6b50f49046e198355e44ea656e521fef9", size = 11988891, upload-time = "2026-04-02T18:17:18.575Z" }, + { url = "https://files.pythonhosted.org/packages/13/e1/1eebcb885c10e19f969dcb93d8413dfee8172578709d7ee933640f5e7147/ruff-0.15.9-py3-none-manylinux_2_17_s390x.manylinux2014_s390x.whl", hash = "sha256:ce187224ef1de1bd225bc9a152ac7102a6171107f026e81f317e4257052916d5", size = 11480576, upload-time = "2026-04-02T18:16:52.986Z" }, + { url = "https://files.pythonhosted.org/packages/ff/6b/a1548ac378a78332a4c3dcf4a134c2475a36d2a22ddfa272acd574140b50/ruff-0.15.9-py3-none-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:2b0c7c341f68adb01c488c3b7d4b49aa8ea97409eae6462d860a79cf55f431b6", size = 11254525, upload-time = "2026-04-02T18:17:02.041Z" }, + { url = "https://files.pythonhosted.org/packages/42/aa/4bb3af8e61acd9b1281db2ab77e8b2c3c5e5599bf2a29d4a942f1c62b8d6/ruff-0.15.9-py3-none-manylinux_2_31_riscv64.whl", hash = "sha256:55cc15eee27dc0eebdfcb0d185a6153420efbedc15eb1d38fe5e685657b0f840", size = 11204072, upload-time = "2026-04-02T18:17:13.581Z" }, + { url = "https://files.pythonhosted.org/packages/69/48/d550dc2aa6e423ea0bcc1d0ff0699325ffe8a811e2dba156bd80750b86dc/ruff-0.15.9-py3-none-musllinux_1_2_aarch64.whl", hash = "sha256:a6537f6eed5cda688c81073d46ffdfb962a5f29ecb6f7e770b2dc920598997ed", size = 10594998, upload-time = "2026-04-02T18:16:46.369Z" }, + { url = "https://files.pythonhosted.org/packages/63/47/321167e17f5344ed5ec6b0aa2cff64efef5f9e985af8f5622cfa6536043f/ruff-0.15.9-py3-none-musllinux_1_2_armv7l.whl", hash = "sha256:6d3fcbca7388b066139c523bda744c822258ebdcfbba7d24410c3f454cc9af71", size = 10359769, upload-time = "2026-04-02T18:17:10.994Z" }, + { url = "https://files.pythonhosted.org/packages/67/5e/074f00b9785d1d2c6f8c22a21e023d0c2c1817838cfca4c8243200a1fa87/ruff-0.15.9-py3-none-musllinux_1_2_i686.whl", hash = "sha256:058d8e99e1bfe79d8a0def0b481c56059ee6716214f7e425d8e737e412d69677", size = 10850236, upload-time = "2026-04-02T18:16:48.749Z" }, + { url = "https://files.pythonhosted.org/packages/76/37/804c4135a2a2caf042925d30d5f68181bdbd4461fd0d7739da28305df593/ruff-0.15.9-py3-none-musllinux_1_2_x86_64.whl", hash = "sha256:8e1ddb11dbd61d5983fa2d7d6370ef3eb210951e443cace19594c01c72abab4c", size = 11358343, upload-time = "2026-04-02T18:16:55.068Z" }, + { url = "https://files.pythonhosted.org/packages/88/3d/1364fcde8656962782aa9ea93c92d98682b1ecec2f184e625a965ad3b4a6/ruff-0.15.9-py3-none-win32.whl", hash = "sha256:bde6ff36eaf72b700f32b7196088970bf8fdb2b917b7accd8c371bfc0fd573ec", size = 10583382, upload-time = "2026-04-02T18:17:04.261Z" }, + { url = "https://files.pythonhosted.org/packages/4c/56/5c7084299bd2cacaa07ae63a91c6f4ba66edc08bf28f356b24f6b717c799/ruff-0.15.9-py3-none-win_amd64.whl", hash = "sha256:45a70921b80e1c10cf0b734ef09421f71b5aa11d27404edc89d7e8a69505e43d", size = 11744969, upload-time = "2026-04-02T18:16:59.611Z" }, + { url = "https://files.pythonhosted.org/packages/03/36/76704c4f312257d6dbaae3c959add2a622f63fcca9d864659ce6d8d97d3d/ruff-0.15.9-py3-none-win_arm64.whl", hash = "sha256:0694e601c028fd97dc5c6ee244675bc241aeefced7ef80cd9c6935a871078f53", size = 11005870, upload-time = "2026-04-02T18:17:15.773Z" }, ] [[package]] @@ -4061,7 +4088,7 @@ wheels = [ [[package]] name = "strands-agents" -version = "1.33.0" +version = "1.34.1" source = { registry = "https://pypi.org/simple" } dependencies = [ { name = "boto3" }, @@ -4077,9 +4104,9 @@ dependencies = [ { name = "typing-extensions" }, { name = "watchdog" }, ] -sdist = { url = "https://files.pythonhosted.org/packages/26/af/76200d7fe69417ebfbf9d3b65c898609a7d74d98d288cce82ca4734591d2/strands_agents-1.33.0.tar.gz", hash = "sha256:1707ae217c2e2700caedafd22ed1d4385cefe90d3debffac4de20cce76cfa676", size = 776194, upload-time = "2026-03-24T19:17:42.046Z" } +sdist = { url = "https://files.pythonhosted.org/packages/be/22/f958d52a794e508a31ace8b8cbba0379226a98fac9826f3b757f95912b70/strands_agents-1.34.1.tar.gz", hash = "sha256:d1ff614dc364ce54348c24b011bbef6c466a0dd33e19996bd1a4ec4aab846cb1", size = 796829, upload-time = "2026-04-01T20:37:29.755Z" } wheels = [ - { url = "https://files.pythonhosted.org/packages/13/99/b3056a03c7d6fb04c1d10afb8fa966b6a5fbce836e264faf663d136f69dd/strands_agents-1.33.0-py3-none-any.whl", hash = "sha256:037406bc86416d2ef3274658faacc35cb62fc5cc13b581d7049796b5e2cb6c33", size = 387070, upload-time = "2026-03-24T19:17:40.697Z" }, + { url = "https://files.pythonhosted.org/packages/19/eb/b0db0fb9ae691d3ed0ac9f9604b60f9154671baf4c61853c0b6607e2a91e/strands_agents-1.34.1-py3-none-any.whl", hash = "sha256:edc5ccd4fbc64bf203ced282083ed011953f628cf8f060e1c88e6a2fd8429f3a", size = 393990, upload-time = "2026-04-01T20:37:27.906Z" }, ] [[package]] @@ -4308,16 +4335,16 @@ wheels = [ [[package]] name = "uvicorn" -version = "0.42.0" +version = "0.44.0" source = { registry = "https://pypi.org/simple" } dependencies = [ { name = "click" }, { name = "h11" }, { name = "typing-extensions", marker = "python_full_version < '3.11'" }, ] -sdist = { url = "https://files.pythonhosted.org/packages/e3/ad/4a96c425be6fb67e0621e62d86c402b4a17ab2be7f7c055d9bd2f638b9e2/uvicorn-0.42.0.tar.gz", hash = "sha256:9b1f190ce15a2dd22e7758651d9b6d12df09a13d51ba5bf4fc33c383a48e1775", size = 85393, upload-time = "2026-03-16T06:19:50.077Z" } +sdist = { url = "https://files.pythonhosted.org/packages/5e/da/6eee1ff8b6cbeed47eeb5229749168e81eb4b7b999a1a15a7176e51410c9/uvicorn-0.44.0.tar.gz", hash = "sha256:6c942071b68f07e178264b9152f1f16dfac5da85880c4ce06366a96d70d4f31e", size = 86947, upload-time = "2026-04-06T09:23:22.826Z" } wheels = [ - { url = "https://files.pythonhosted.org/packages/0a/89/f8827ccff89c1586027a105e5630ff6139a64da2515e24dafe860bd9ae4d/uvicorn-0.42.0-py3-none-any.whl", hash = "sha256:96c30f5c7abe6f74ae8900a70e92b85ad6613b745d4879eb9b16ccad15645359", size = 68830, upload-time = "2026-03-16T06:19:48.325Z" }, + { url = "https://files.pythonhosted.org/packages/b7/23/a5bbd9600dd607411fa644c06ff4951bec3a4d82c4b852374024359c19c0/uvicorn-0.44.0-py3-none-any.whl", hash = "sha256:ce937c99a2cc70279556967274414c087888e8cec9f9c94644dfca11bd3ced89", size = 69425, upload-time = "2026-04-06T09:23:21.524Z" }, ] [package.optional-dependencies] diff --git a/codeql-alerts.json b/codeql-alerts.json deleted file mode 100644 index ba235ef4..00000000 --- a/codeql-alerts.json +++ /dev/null @@ -1,3372 +0,0 @@ -[ - { - "number": 522, - "rule": "py/unused-import", - "severity": "note", - "description": "Unused import", - "file": "backend/src/apis/app_api/shares/service.py", - "start_line": 7, - "end_line": 7, - "message": "Import of 'json' is not used." - }, - { - "number": 508, - "rule": "actions/untrusted-checkout/medium", - "severity": "medium", - "description": "Checkout of untrusted code in trusted context", - "file": ".github/workflows/nightly.yml", - "start_line": 599, - "end_line": 604, - "message": "Potential unsafe checkout of untrusted pull request on privileged workflow." - }, - { - "number": 507, - "rule": "actions/untrusted-checkout/medium", - "severity": "medium", - "description": "Checkout of untrusted code in trusted context", - "file": ".github/workflows/nightly.yml", - "start_line": 520, - "end_line": 525, - "message": "Potential unsafe checkout of untrusted pull request on privileged workflow." - }, - { - "number": 506, - "rule": "actions/untrusted-checkout/medium", - "severity": "medium", - "description": "Checkout of untrusted code in trusted context", - "file": ".github/workflows/nightly.yml", - "start_line": 367, - "end_line": 372, - "message": "Potential unsafe checkout of untrusted pull request on privileged workflow." - }, - { - "number": 505, - "rule": "actions/untrusted-checkout/medium", - "severity": "medium", - "description": "Checkout of untrusted code in trusted context", - "file": ".github/workflows/nightly.yml", - "start_line": 324, - "end_line": 329, - "message": "Potential unsafe checkout of untrusted pull request on privileged workflow." - }, - { - "number": 504, - "rule": "actions/untrusted-checkout/medium", - "severity": "medium", - "description": "Checkout of untrusted code in trusted context", - "file": ".github/workflows/nightly.yml", - "start_line": 276, - "end_line": 281, - "message": "Potential unsafe checkout of untrusted pull request on privileged workflow." - }, - { - "number": 503, - "rule": "actions/untrusted-checkout/medium", - "severity": "medium", - "description": "Checkout of untrusted code in trusted context", - "file": ".github/workflows/nightly.yml", - "start_line": 240, - "end_line": 245, - "message": "Potential unsafe checkout of untrusted pull request on privileged workflow." - }, - { - "number": 502, - "rule": "actions/untrusted-checkout/medium", - "severity": "medium", - "description": "Checkout of untrusted code in trusted context", - "file": ".github/workflows/nightly.yml", - "start_line": 198, - "end_line": 203, - "message": "Potential unsafe checkout of untrusted pull request on privileged workflow." - }, - { - "number": 501, - "rule": "actions/untrusted-checkout/medium", - "severity": "medium", - "description": "Checkout of untrusted code in trusted context", - "file": ".github/workflows/nightly-deploy-pipeline.yml", - "start_line": 82, - "end_line": 87, - "message": "Potential unsafe checkout of untrusted pull request on privileged workflow." - }, - { - "number": 500, - "rule": "actions/untrusted-checkout/medium", - "severity": "medium", - "description": "Checkout of untrusted code in trusted context", - "file": ".github/workflows/nightly-deploy-pipeline.yml", - "start_line": 51, - "end_line": 56, - "message": "Potential unsafe checkout of untrusted pull request on privileged workflow." - }, - { - "number": 489, - "rule": "py/unused-global-variable", - "severity": "note", - "description": "Unused global variable", - "file": "backend/src/apis/app_api/documents/ingestion/embeddings/bedrock_embeddings.py", - "start_line": 130, - "end_line": 130, - "message": "The global variable '_validate_and_split_chunks' is not used." - }, - { - "number": 488, - "rule": "py/unused-import", - "severity": "note", - "description": "Unused import", - "file": "backend/src/apis/app_api/documents/ingestion/embeddings/bedrock_embeddings.py", - "start_line": 16, - "end_line": 22, - "message": "Import of 'BEDROCK_EMBEDDING_CONFIG' is not used." - }, - { - "number": 436, - "rule": "js/comparison-between-incompatible-types", - "severity": "warning", - "description": "Comparison between inconvertible types", - "file": "frontend/ai.client/src/app/session/services/session/session.service.ts", - "start_line": 222, - "end_line": 222, - "message": "Variable 'apiResponse' cannot be of type null, but it is compared to an expression of type null." - }, - { - "number": 435, - "rule": "js/unused-local-variable", - "severity": "note", - "description": "Unused variable, import, function or class", - "file": "infrastructure/lib/infrastructure-stack.ts", - "start_line": 244, - "end_line": 244, - "message": "Unused variable httpRedirectListener." - }, - { - "number": 434, - "rule": "js/unused-local-variable", - "severity": "note", - "description": "Unused variable, import, function or class", - "file": "infrastructure/lib/rag-ingestion-stack.ts", - "start_line": 234, - "end_line": 234, - "message": "Unused variable containerImageUri." - }, - { - "number": 433, - "rule": "js/unused-local-variable", - "severity": "note", - "description": "Unused variable, import, function or class", - "file": "infrastructure/lib/rag-ingestion-stack.ts", - "start_line": 72, - "end_line": 72, - "message": "Unused variable vpc." - }, - { - "number": 432, - "rule": "js/unused-local-variable", - "severity": "note", - "description": "Unused variable, import, function or class", - "file": "infrastructure/lib/app-api-stack.ts", - "start_line": 75, - "end_line": 75, - "message": "Unused variable alb." - }, - { - "number": 431, - "rule": "js/unused-local-variable", - "severity": "note", - "description": "Unused variable, import, function or class", - "file": "infrastructure/lib/inference-api-stack.ts", - "start_line": 62, - "end_line": 62, - "message": "Unused variable containerImageUri." - }, - { - "number": 430, - "rule": "js/unused-local-variable", - "severity": "note", - "description": "Unused variable, import, function or class", - "file": "infrastructure/lib/app-api-stack.ts", - "start_line": 11, - "end_line": 11, - "message": "Unused import kms." - }, - { - "number": 429, - "rule": "js/unused-local-variable", - "severity": "note", - "description": "Unused variable, import, function or class", - "file": "infrastructure/lib/app-api-stack.ts", - "start_line": 7, - "end_line": 7, - "message": "Unused import secretsmanager." - }, - { - "number": 427, - "rule": "js/unused-local-variable", - "severity": "note", - "description": "Unused variable, import, function or class", - "file": "infrastructure/lib/frontend-stack.ts", - "start_line": 126, - "end_line": 126, - "message": "Unused variable oac." - }, - { - "number": 426, - "rule": "js/unused-local-variable", - "severity": "note", - "description": "Unused variable, import, function or class", - "file": "frontend/ai.client/src/app/settings/settings.page.ts", - "start_line": 1, - "end_line": 7, - "message": "Unused imports computed, signal." - }, - { - "number": 425, - "rule": "js/unused-local-variable", - "severity": "note", - "description": "Unused variable, import, function or class", - "file": "frontend/ai.client/src/app/settings/oauth-callback/oauth-callback.page.ts", - "start_line": 1, - "end_line": 9, - "message": "Unused import computed." - }, - { - "number": 424, - "rule": "js/unused-local-variable", - "severity": "note", - "description": "Unused variable, import, function or class", - "file": "frontend/ai.client/src/app/settings/connections/services/connections.service.ts", - "start_line": 6, - "end_line": 12, - "message": "Unused import OAuthConnectResponse." - }, - { - "number": 423, - "rule": "js/unused-local-variable", - "severity": "note", - "description": "Unused variable, import, function or class", - "file": "frontend/ai.client/src/app/session/components/message-list/message-list.component.ts", - "start_line": 44, - "end_line": 44, - "message": "Unused variable messageCount." - }, - { - "number": 422, - "rule": "js/unused-local-variable", - "severity": "note", - "description": "Unused variable, import, function or class", - "file": "frontend/ai.client/src/app/memory/memory-dashboard.page.ts", - "start_line": 14, - "end_line": 14, - "message": "Unused import MemoryRecord." - }, - { - "number": 421, - "rule": "js/unused-local-variable", - "severity": "note", - "description": "Unused variable, import, function or class", - "file": "frontend/ai.client/src/app/components/tooltip/tooltip.directive.ts", - "start_line": 21, - "end_line": 21, - "message": "Unused import merge." - }, - { - "number": 420, - "rule": "js/unused-local-variable", - "severity": "note", - "description": "Unused variable, import, function or class", - "file": "frontend/ai.client/src/app/components/tooltip/tooltip.directive.ts", - "start_line": 13, - "end_line": 18, - "message": "Unused import ScrollStrategy." - }, - { - "number": 419, - "rule": "js/unused-local-variable", - "severity": "note", - "description": "Unused variable, import, function or class", - "file": "frontend/ai.client/src/app/components/tooltip/tooltip.directive.ts", - "start_line": 1, - "end_line": 12, - "message": "Unused import effect." - }, - { - "number": 418, - "rule": "js/unused-local-variable", - "severity": "note", - "description": "Unused variable, import, function or class", - "file": "frontend/ai.client/src/app/components/toast/toast.component.ts", - "start_line": 10, - "end_line": 10, - "message": "Unused import ToastMessage." - }, - { - "number": 417, - "rule": "js/unused-local-variable", - "severity": "note", - "description": "Unused variable, import, function or class", - "file": "frontend/ai.client/src/app/components/error-toast/error-toast.component.ts", - "start_line": 2, - "end_line": 2, - "message": "Unused import ErrorMessage." - }, - { - "number": 416, - "rule": "js/unused-local-variable", - "severity": "note", - "description": "Unused variable, import, function or class", - "file": "frontend/ai.client/src/app/assistants/services/assistant.service.ts", - "start_line": 3, - "end_line": 11, - "message": "Unused imports ShareAssistantRequest, UnshareAssistantRequest." - }, - { - "number": 415, - "rule": "js/unused-local-variable", - "severity": "note", - "description": "Unused variable, import, function or class", - "file": "frontend/ai.client/src/app/assistants/assistants.page.ts", - "start_line": 1, - "end_line": 1, - "message": "Unused import signal." - }, - { - "number": 414, - "rule": "js/unused-local-variable", - "severity": "note", - "description": "Unused variable, import, function or class", - "file": "frontend/ai.client/src/app/app.routes.ts", - "start_line": 2, - "end_line": 2, - "message": "Unused import ConversationPage." - }, - { - "number": 413, - "rule": "js/unused-local-variable", - "severity": "note", - "description": "Unused variable, import, function or class", - "file": "frontend/ai.client/src/app/admin/tools/services/admin-tool.service.ts", - "start_line": 6, - "end_line": 15, - "message": "Unused import SetToolRolesRequest." - }, - { - "number": 412, - "rule": "js/unused-local-variable", - "severity": "note", - "description": "Unused variable, import, function or class", - "file": "frontend/ai.client/src/app/admin/tools/pages/tool-form.page.ts", - "start_line": 23, - "end_line": 35, - "message": "Unused imports AdminTool, ToolFormData." - }, - { - "number": 411, - "rule": "js/unused-local-variable", - "severity": "note", - "description": "Unused variable, import, function or class", - "file": "frontend/ai.client/src/app/admin/quota-tiers/services/quota-state.service.ts", - "start_line": 2, - "end_line": 2, - "message": "Unused import toSignal." - }, - { - "number": 410, - "rule": "js/unused-local-variable", - "severity": "note", - "description": "Unused variable, import, function or class", - "file": "frontend/ai.client/src/app/admin/quota-tiers/pages/tier-list/tier-list.component.ts", - "start_line": 6, - "end_line": 6, - "message": "Unused import QuotaTier." - }, - { - "number": 409, - "rule": "js/unused-local-variable", - "severity": "note", - "description": "Unused variable, import, function or class", - "file": "frontend/ai.client/src/app/admin/manage-models/services/managed-models.service.ts", - "start_line": 1, - "end_line": 1, - "message": "Unused import signal." - }, - { - "number": 408, - "rule": "js/unused-local-variable", - "severity": "note", - "description": "Unused variable, import, function or class", - "file": "frontend/ai.client/src/app/admin/costs/admin-costs.page.ts", - "start_line": 17, - "end_line": 20, - "message": "Unused import SummaryCardIcon." - }, - { - "number": 407, - "rule": "js/useless-assignment-to-local", - "severity": "warning", - "description": "Useless assignment to local variable", - "file": "frontend/ai.client/src/index.html", - "start_line": 24, - "end_line": 24, - "message": "The initial value of theme is unused, since it is always overwritten." - }, - { - "number": 406, - "rule": "js/useless-assignment-to-local", - "severity": "warning", - "description": "Useless assignment to local variable", - "file": "frontend/ai.client/src/app/session/services/chat/chat-http.service.ts", - "start_line": 101, - "end_line": 101, - "message": "The value assigned to errorDetail here is unused." - }, - { - "number": 405, - "rule": "js/useless-assignment-to-local", - "severity": "warning", - "description": "Useless assignment to local variable", - "file": "frontend/ai.client/src/app/session/services/chat/chat-http.service.ts", - "start_line": 82, - "end_line": 82, - "message": "The value assigned to errorDetail here is unused." - }, - { - "number": 404, - "rule": "py/commented-out-code", - "severity": "note", - "description": "Commented-out code", - "file": "backend/src/apis/inference_api/chat/models.py", - "start_line": 41, - "end_line": 43, - "message": "This comment appears to contain commented-out code." - }, - { - "number": 403, - "rule": "py/catch-base-exception", - "severity": "note", - "description": "Except block handles 'BaseException'", - "file": "backend/src/agents/local_tools/url_fetcher.py", - "start_line": 118, - "end_line": 118, - "message": "Except block directly handles BaseException." - }, - { - "number": 402, - "rule": "py/catch-base-exception", - "severity": "note", - "description": "Except block handles 'BaseException'", - "file": "backend/src/agents/builtin_tools/code_interpreter_diagram_tool.py", - "start_line": 227, - "end_line": 227, - "message": "Except block directly handles BaseException." - }, - { - "number": 401, - "rule": "py/empty-except", - "severity": "note", - "description": "Empty except", - "file": "backend/src/agents/local_tools/url_fetcher.py", - "start_line": 118, - "end_line": 118, - "message": "'except' clause does nothing but pass and there is no explanatory comment." - }, - { - "number": 400, - "rule": "py/empty-except", - "severity": "note", - "description": "Empty except", - "file": "backend/src/agents/main_agent/streaming/tool_result_processor.py", - "start_line": 94, - "end_line": 94, - "message": "'except' clause does nothing but pass and there is no explanatory comment." - }, - { - "number": 399, - "rule": "py/empty-except", - "severity": "note", - "description": "Empty except", - "file": "backend/src/apis/app_api/admin/users/service.py", - "start_line": 66, - "end_line": 66, - "message": "'except' clause does nothing but pass and there is no explanatory comment." - }, - { - "number": 398, - "rule": "py/empty-except", - "severity": "note", - "description": "Empty except", - "file": "backend/src/agents/main_agent/streaming/event_formatter.py", - "start_line": 43, - "end_line": 43, - "message": "'except' clause does nothing but pass and there is no explanatory comment." - }, - { - "number": 397, - "rule": "py/empty-except", - "severity": "note", - "description": "Empty except", - "file": "backend/src/agents/builtin_tools/code_interpreter_diagram_tool.py", - "start_line": 227, - "end_line": 227, - "message": "'except' clause does nothing but pass and there is no explanatory comment." - }, - { - "number": 396, - "rule": "py/print-during-import", - "severity": "note", - "description": "Use of a print statement at module level", - "file": "backend/src/apis/inference_api/main.py", - "start_line": 24, - "end_line": 24, - "message": "Print statement may execute during import." - }, - { - "number": 395, - "rule": "py/print-during-import", - "severity": "note", - "description": "Use of a print statement at module level", - "file": "backend/src/apis/inference_api/main.py", - "start_line": 22, - "end_line": 22, - "message": "Print statement may execute during import." - }, - { - "number": 394, - "rule": "py/non-iterable-in-for-loop", - "severity": "error", - "description": "Non-iterable used in for loop", - "file": "backend/src/agents/main_agent/quota/repository.py", - "start_line": 309, - "end_line": 309, - "message": "This for-loop may attempt to iterate over a non-iterable instance of class type." - }, - { - "number": 393, - "rule": "py/unreachable-statement", - "severity": "warning", - "description": "Unreachable code", - "file": "backend/src/agents/main_agent/streaming/stream_processor.py", - "start_line": 1294, - "end_line": 1294, - "message": "This statement is unreachable." - }, - { - "number": 392, - "rule": "py/unnecessary-lambda", - "severity": "note", - "description": "Unnecessary lambda", - "file": "backend/src/apis/app_api/fine_tuning/job_repository.py", - "start_line": 221, - "end_line": 221, - "message": "This 'lambda' is just a simple wrapper around a callable object. Use that object directly." - }, - { - "number": 391, - "rule": "py/unnecessary-lambda", - "severity": "note", - "description": "Unnecessary lambda", - "file": "backend/src/apis/app_api/fine_tuning/inference_repository.py", - "start_line": 233, - "end_line": 233, - "message": "This 'lambda' is just a simple wrapper around a callable object. Use that object directly." - }, - { - "number": 389, - "rule": "py/unused-local-variable", - "severity": "note", - "description": "Unused local variable", - "file": "backend/src/agents/main_agent/streaming/tool_result_processor.py", - "start_line": 295, - "end_line": 295, - "message": "Variable matches is not used." - }, - { - "number": 388, - "rule": "py/unused-local-variable", - "severity": "note", - "description": "Unused local variable", - "file": "backend/src/apis/app_api/admin/services/tool_access.py", - "start_line": 95, - "end_line": 95, - "message": "Variable requested_set is not used." - }, - { - "number": 387, - "rule": "py/unused-local-variable", - "severity": "note", - "description": "Unused local variable", - "file": "backend/src/apis/app_api/documents/ingestion/status.py", - "start_line": 121, - "end_line": 121, - "message": "Variable exception_type is not used." - }, - { - "number": 386, - "rule": "py/unused-local-variable", - "severity": "note", - "description": "Unused local variable", - "file": "backend/src/apis/app_api/files/service.py", - "start_line": 288, - "end_line": 288, - "message": "Variable updated is not used." - }, - { - "number": 385, - "rule": "py/unused-local-variable", - "severity": "note", - "description": "Unused local variable", - "file": "backend/src/apis/app_api/admin/quota/service.py", - "start_line": 340, - "end_line": 340, - "message": "Variable limit is not used." - }, - { - "number": 384, - "rule": "py/unused-local-variable", - "severity": "note", - "description": "Unused local variable", - "file": "backend/src/apis/inference_api/chat/routes.py", - "start_line": 480, - "end_line": 480, - "message": "Variable preferences is not used." - }, - { - "number": 383, - "rule": "py/unused-local-variable", - "severity": "note", - "description": "Unused local variable", - "file": "backend/src/agents/builtin_tools/code_interpreter_diagram_tool.py", - "start_line": 170, - "end_line": 170, - "message": "Variable execution_output is not used." - }, - { - "number": 382, - "rule": "py/unused-local-variable", - "severity": "note", - "description": "Unused local variable", - "file": "backend/src/apis/app_api/costs/aggregator.py", - "start_line": 289, - "end_line": 289, - "message": "Variable next_year is not used." - }, - { - "number": 381, - "rule": "py/unused-local-variable", - "severity": "note", - "description": "Unused local variable", - "file": "backend/src/apis/app_api/costs/aggregator.py", - "start_line": 288, - "end_line": 288, - "message": "Variable next_month is not used." - }, - { - "number": 380, - "rule": "py/unused-local-variable", - "severity": "note", - "description": "Unused local variable", - "file": "backend/src/apis/app_api/costs/aggregator.py", - "start_line": 286, - "end_line": 286, - "message": "Variable next_year is not used." - }, - { - "number": 379, - "rule": "py/unused-local-variable", - "severity": "note", - "description": "Unused local variable", - "file": "backend/src/apis/app_api/costs/aggregator.py", - "start_line": 285, - "end_line": 285, - "message": "Variable next_month is not used." - }, - { - "number": 377, - "rule": "py/unused-global-variable", - "severity": "note", - "description": "Unused global variable", - "file": "backend/src/apis/shared/auth/dependencies.py", - "start_line": 64, - "end_line": 64, - "message": "The global variable '_generic_validator_initialized' is not used." - }, - { - "number": 376, - "rule": "py/multiple-definition", - "severity": "warning", - "description": "Variable defined multiple times", - "file": "backend/src/apis/app_api/fine_tuning/routes.py", - "start_line": 723, - "end_line": 723, - "message": "This assignment to 'job' is unnecessary as it is redefined before this value is used." - }, - { - "number": 374, - "rule": "py/unused-import", - "severity": "note", - "description": "Unused import", - "file": "backend/src/agents/local_tools/url_fetcher.py", - "start_line": 8, - "end_line": 8, - "message": "Import of 'Optional' is not used." - }, - { - "number": 373, - "rule": "py/unused-import", - "severity": "note", - "description": "Unused import", - "file": "backend/src/agents/local_tools/url_fetcher.py", - "start_line": 6, - "end_line": 6, - "message": "Import of 'json' is not used." - }, - { - "number": 371, - "rule": "py/unused-import", - "severity": "note", - "description": "Unused import", - "file": "backend/src/agents/main_agent/tools/tool_catalog.py", - "start_line": 7, - "end_line": 7, - "message": "Import of 'field' is not used." - }, - { - "number": 370, - "rule": "py/unused-import", - "severity": "note", - "description": "Unused import", - "file": "backend/src/agents/main_agent/utils/timezone.py", - "start_line": 15, - "end_line": 15, - "message": "Import of 'pytz' is not used." - }, - { - "number": 369, - "rule": "py/unused-import", - "severity": "note", - "description": "Unused import", - "file": "backend/src/apis/app_api/admin/services/tests/test_model_access.py", - "start_line": 9, - "end_line": 9, - "message": "Import of 'MagicMock' is not used." - }, - { - "number": 368, - "rule": "py/unused-import", - "severity": "note", - "description": "Unused import", - "file": "backend/src/agents/main_agent/session/tests/test_compaction_integration.py", - "start_line": 25, - "end_line": 25, - "message": "Import of 'datetime' is not used." - }, - { - "number": 367, - "rule": "py/unused-import", - "severity": "note", - "description": "Unused import", - "file": "backend/src/agents/main_agent/session/tests/test_compaction.py", - "start_line": 11, - "end_line": 11, - "message": "Import of 'TurnBasedSessionManager' is not used." - }, - { - "number": 366, - "rule": "py/unused-import", - "severity": "note", - "description": "Unused import", - "file": "backend/src/apis/app_api/costs/tests/test_calculator.py", - "start_line": 5, - "end_line": 5, - "message": "Import of 'CostBreakdown' is not used." - }, - { - "number": 365, - "rule": "py/unused-import", - "severity": "note", - "description": "Unused import", - "file": "backend/src/apis/app_api/sessions/tests/test_cache_savings.py", - "start_line": 4, - "end_line": 4, - "message": "Import of 'MagicMock' is not used." - }, - { - "number": 364, - "rule": "py/unused-import", - "severity": "note", - "description": "Unused import", - "file": "backend/src/agents/main_agent/streaming/stream_coordinator.py", - "start_line": 13, - "end_line": 13, - "message": "Import of 'ConversationalErrorEvent' is not used." - }, - { - "number": 363, - "rule": "py/unused-import", - "severity": "note", - "description": "Unused import", - "file": "backend/src/apis/app_api/documents/ingestion/status.py", - "start_line": 9, - "end_line": 9, - "message": "Import of 'uuid' is not used." - }, - { - "number": 362, - "rule": "py/unused-import", - "severity": "note", - "description": "Unused import", - "file": "backend/src/agents/main_agent/session/session_factory.py", - "start_line": 21, - "end_line": 21, - "message": "Import of 'AgentCoreMemorySessionManager' is not used." - }, - { - "number": 361, - "rule": "py/unused-import", - "severity": "note", - "description": "Unused import", - "file": "backend/src/apis/app_api/admin/users/service.py", - "start_line": 11, - "end_line": 11, - "message": "Import of 'UserProfile' is not used." - }, - { - "number": 360, - "rule": "py/unused-import", - "severity": "note", - "description": "Unused import", - "file": "backend/src/apis/app_api/tools/service.py", - "start_line": 17, - "end_line": 27, - "message": "Import of 'AdminToolResponse' is not used." - }, - { - "number": 359, - "rule": "py/unused-import", - "severity": "note", - "description": "Unused import", - "file": "backend/src/apis/app_api/tools/service.py", - "start_line": 10, - "end_line": 10, - "message": "Import of 'datetime' is not used." - }, - { - "number": 358, - "rule": "py/unused-import", - "severity": "note", - "description": "Unused import", - "file": "backend/src/apis/app_api/tools/service.py", - "start_line": 9, - "end_line": 9, - "message": "Import of 'Set' is not used." - }, - { - "number": 357, - "rule": "py/unused-import", - "severity": "note", - "description": "Unused import", - "file": "backend/src/apis/shared/oauth/service.py", - "start_line": 20, - "end_line": 26, - "message": "Import of 'compute_scopes_hash' is not used." - }, - { - "number": 356, - "rule": "py/unused-import", - "severity": "note", - "description": "Unused import", - "file": "backend/src/apis/app_api/files/service.py", - "start_line": 17, - "end_line": 29, - "message": "Import of 'UserFileQuota' is not used." - }, - { - "number": 355, - "rule": "py/unused-import", - "severity": "note", - "description": "Unused import", - "file": "backend/src/apis/app_api/files/service.py", - "start_line": 11, - "end_line": 11, - "message": "Import of 'Tuple' is not used." - }, - { - "number": 354, - "rule": "py/unused-import", - "severity": "note", - "description": "Unused import", - "file": "backend/src/apis/inference_api/chat/service.py", - "start_line": 11, - "end_line": 11, - "message": "Import of 'lru_cache' is not used." - }, - { - "number": 353, - "rule": "py/unused-import", - "severity": "note", - "description": "Unused import", - "file": "backend/src/apis/inference_api/chat/service.py", - "start_line": 8, - "end_line": 8, - "message": "Import of 'json' is not used." - }, - { - "number": 352, - "rule": "py/unused-import", - "severity": "note", - "description": "Unused import", - "file": "backend/scripts/seed_auth_provider.py", - "start_line": 53, - "end_line": 53, - "message": "Import of 'Optional' is not used." - }, - { - "number": 351, - "rule": "py/unused-import", - "severity": "note", - "description": "Unused import", - "file": "backend/src/apis/app_api/fine_tuning/routes.py", - "start_line": 20, - "end_line": 29, - "message": "Import of 'AvailableModel' is not used." - }, - { - "number": 350, - "rule": "py/unused-import", - "severity": "note", - "description": "Unused import", - "file": "backend/src/apis/app_api/fine_tuning/s3_service.py", - "start_line": 6, - "end_line": 6, - "message": "Import of 'datetime' is not used." - }, - { - "number": 349, - "rule": "py/unused-import", - "severity": "note", - "description": "Unused import", - "file": "backend/src/apis/inference_api/chat/routes.py", - "start_line": 28, - "end_line": 28, - "message": "Import of 'ResolvedFileContent' is not used." - }, - { - "number": 348, - "rule": "py/unused-import", - "severity": "note", - "description": "Unused import", - "file": "backend/src/apis/inference_api/chat/routes.py", - "start_line": 22, - "end_line": 27, - "message": "Import of 'create_error_response' is not used." - }, - { - "number": 347, - "rule": "py/unused-import", - "severity": "note", - "description": "Unused import", - "file": "backend/src/apis/inference_api/chat/routes.py", - "start_line": 20, - "end_line": 20, - "message": "Import of 'get_current_user' is not used." - }, - { - "number": 346, - "rule": "py/unused-import", - "severity": "note", - "description": "Unused import", - "file": "backend/src/apis/inference_api/chat/routes.py", - "start_line": 13, - "end_line": 13, - "message": "Import of 'datetime' is not used." - }, - { - "number": 345, - "rule": "py/unused-import", - "severity": "note", - "description": "Unused import", - "file": "backend/src/apis/app_api/admin/costs/routes.py", - "start_line": 9, - "end_line": 9, - "message": "Import of 'status' is not used." - }, - { - "number": 344, - "rule": "py/unused-import", - "severity": "note", - "description": "Unused import", - "file": "backend/src/apis/app_api/users/routes.py", - "start_line": 11, - "end_line": 11, - "message": "Import of 'UserProfile' is not used." - }, - { - "number": 343, - "rule": "py/unused-import", - "severity": "note", - "description": "Unused import", - "file": "backend/src/apis/app_api/users/routes.py", - "start_line": 4, - "end_line": 4, - "message": "Import of 'List' is not used." - }, - { - "number": 342, - "rule": "py/unused-import", - "severity": "note", - "description": "Unused import", - "file": "backend/src/apis/app_api/admin/auth_providers/routes.py", - "start_line": 8, - "end_line": 8, - "message": "Import of 'Optional' is not used." - }, - { - "number": 341, - "rule": "py/unused-import", - "severity": "note", - "description": "Unused import", - "file": "backend/src/apis/app_api/admin/routes.py", - "start_line": 43, - "end_line": 46, - "message": "Import of 'ModelAccessService' is not used." - }, - { - "number": 340, - "rule": "py/unused-import", - "severity": "note", - "description": "Unused import", - "file": "backend/src/apis/app_api/admin/routes.py", - "start_line": 35, - "end_line": 35, - "message": "Import of 'get_messages' is not used." - }, - { - "number": 339, - "rule": "py/unused-import", - "severity": "note", - "description": "Unused import", - "file": "backend/src/apis/app_api/admin/routes.py", - "start_line": 34, - "end_line": 34, - "message": "Import of 'list_user_sessions' is not used." - }, - { - "number": 338, - "rule": "py/unused-import", - "severity": "note", - "description": "Unused import", - "file": "backend/src/apis/app_api/admin/routes.py", - "start_line": 33, - "end_line": 33, - "message": "Import of 'require_roles' is not used." - }, - { - "number": 337, - "rule": "py/unused-import", - "severity": "note", - "description": "Unused import", - "file": "backend/src/apis/app_api/admin/routes.py", - "start_line": 15, - "end_line": 27, - "message": "Import of 'UserInfo' is not used." - }, - { - "number": 336, - "rule": "py/unused-import", - "severity": "note", - "description": "Unused import", - "file": "backend/src/apis/app_api/admin/routes.py", - "start_line": 12, - "end_line": 12, - "message": "Import of 'datetime' is not used." - }, - { - "number": 335, - "rule": "py/unused-import", - "severity": "note", - "description": "Unused import", - "file": "backend/src/apis/app_api/admin/tools/routes.py", - "start_line": 9, - "end_line": 9, - "message": "Import of 'ToolCatalogService' is not used." - }, - { - "number": 334, - "rule": "py/unused-import", - "severity": "note", - "description": "Unused import", - "file": "backend/src/apis/app_api/chat/routes.py", - "start_line": 34, - "end_line": 39, - "message": "Import of 'ConversationalErrorEvent' is not used." - }, - { - "number": 333, - "rule": "py/unused-import", - "severity": "note", - "description": "Unused import", - "file": "backend/src/apis/app_api/chat/routes.py", - "start_line": 23, - "end_line": 23, - "message": "Import of 'ResolvedFileContent' is not used." - }, - { - "number": 332, - "rule": "py/unused-import", - "severity": "note", - "description": "Unused import", - "file": "backend/src/apis/app_api/chat/routes.py", - "start_line": 15, - "end_line": 15, - "message": "Import of 'status' is not used." - }, - { - "number": 331, - "rule": "py/unused-import", - "severity": "note", - "description": "Unused import", - "file": "backend/src/apis/app_api/chat/routes.py", - "start_line": 13, - "end_line": 13, - "message": "Import of 'AsyncGenerator' is not used." - }, - { - "number": 330, - "rule": "py/unused-import", - "severity": "note", - "description": "Unused import", - "file": "backend/src/apis/app_api/admin/roles/routes.py", - "start_line": 22, - "end_line": 22, - "message": "Import of 'get_app_role_service' is not used." - }, - { - "number": 329, - "rule": "py/unused-import", - "severity": "note", - "description": "Unused import", - "file": "backend/src/apis/app_api/admin/roles/routes.py", - "start_line": 9, - "end_line": 13, - "message": "Import of 'AppRoleService' is not used." - }, - { - "number": 328, - "rule": "py/unused-import", - "severity": "note", - "description": "Unused import", - "file": "backend/src/apis/app_api/admin/roles/routes.py", - "start_line": 4, - "end_line": 4, - "message": "Import of 'Optional' is not used." - }, - { - "number": 327, - "rule": "py/unused-import", - "severity": "note", - "description": "Unused import", - "file": "backend/src/agents/main_agent/quota/repository.py", - "start_line": 8, - "end_line": 8, - "message": "Import of 'uuid' is not used." - }, - { - "number": 326, - "rule": "py/unused-import", - "severity": "note", - "description": "Unused import", - "file": "backend/src/apis/app_api/auth/api_keys/repository.py", - "start_line": 20, - "end_line": 20, - "message": "Import of 'List' is not used." - }, - { - "number": 325, - "rule": "py/unused-import", - "severity": "note", - "description": "Unused import", - "file": "backend/src/apis/shared/rbac/repository.py", - "start_line": 11, - "end_line": 11, - "message": "Import of 'EffectivePermissions' is not used." - }, - { - "number": 324, - "rule": "py/unused-import", - "severity": "note", - "description": "Unused import", - "file": "backend/src/apis/shared/auth/rbac.py", - "start_line": 3, - "end_line": 3, - "message": "Import of 'List' is not used." - }, - { - "number": 323, - "rule": "py/unused-import", - "severity": "note", - "description": "Unused import", - "file": "backend/src/apis/shared/quota.py", - "start_line": 10, - "end_line": 10, - "message": "Import of 'Decimal' is not used." - }, - { - "number": 322, - "rule": "py/unused-import", - "severity": "note", - "description": "Unused import", - "file": "backend/src/apis/shared/oauth/provider_repository.py", - "start_line": 7, - "end_line": 7, - "message": "Import of 'Dict' is not used." - }, - { - "number": 321, - "rule": "py/unused-import", - "severity": "note", - "description": "Unused import", - "file": "backend/src/agents/main_agent/session/preview_session_manager.py", - "start_line": 13, - "end_line": 13, - "message": "Import of 'Message' is not used." - }, - { - "number": 320, - "rule": "py/unused-import", - "severity": "note", - "description": "Unused import", - "file": "backend/src/agents/main_agent/session/preview_session_manager.py", - "start_line": 12, - "end_line": 12, - "message": "Import of 'Optional' is not used." - }, - { - "number": 319, - "rule": "py/unused-import", - "severity": "note", - "description": "Unused import", - "file": "backend/src/agents/main_agent/tools/oauth_tool_service.py", - "start_line": 37, - "end_line": 37, - "message": "Import of 'urlencode' is not used." - }, - { - "number": 318, - "rule": "py/unused-import", - "severity": "note", - "description": "Unused import", - "file": "backend/src/agents/main_agent/integrations/oauth_auth.py", - "start_line": 9, - "end_line": 9, - "message": "Import of 'Awaitable' is not used." - }, - { - "number": 317, - "rule": "py/unused-import", - "severity": "note", - "description": "Unused import", - "file": "backend/src/agents/main_agent/quota/models.py", - "start_line": 3, - "end_line": 3, - "message": "Import of 'model_serializer' is not used." - }, - { - "number": 316, - "rule": "py/unused-import", - "severity": "note", - "description": "Unused import", - "file": "backend/src/apis/app_api/admin/quota/models.py", - "start_line": 5, - "end_line": 11, - "message": "Import of 'QuotaEvent' is not used." - }, - { - "number": 315, - "rule": "py/unused-import", - "severity": "note", - "description": "Unused import", - "file": "backend/src/apis/shared/rbac/models.py", - "start_line": 5, - "end_line": 5, - "message": "Import of 'datetime' is not used." - }, - { - "number": 314, - "rule": "py/unused-import", - "severity": "note", - "description": "Unused import", - "file": "backend/src/apis/app_api/auth/api_keys/models.py", - "start_line": 4, - "end_line": 4, - "message": "Import of 'List' is not used." - }, - { - "number": 313, - "rule": "py/unused-import", - "severity": "note", - "description": "Unused import", - "file": "backend/src/apis/app_api/auth/api_keys/models.py", - "start_line": 3, - "end_line": 3, - "message": "Import of 'datetime' is not used." - }, - { - "number": 312, - "rule": "py/unused-import", - "severity": "note", - "description": "Unused import", - "file": "backend/src/apis/shared/files/models.py", - "start_line": 11, - "end_line": 11, - "message": "Import of 'time' is not used." - }, - { - "number": 311, - "rule": "py/unused-import", - "severity": "note", - "description": "Unused import", - "file": "backend/src/apis/app_api/costs/models.py", - "start_line": 4, - "end_line": 4, - "message": "Import of 'Optional' is not used." - }, - { - "number": 310, - "rule": "py/unused-import", - "severity": "note", - "description": "Unused import", - "file": "backend/src/agents/main_agent/core/model_config.py", - "start_line": 6, - "end_line": 6, - "message": "Import of 'field' is not used." - }, - { - "number": 309, - "rule": "py/unused-import", - "severity": "note", - "description": "Unused import", - "file": "backend/src/agents/main_agent/core/model_config.py", - "start_line": 5, - "end_line": 5, - "message": "Import of 'Literal' is not used." - }, - { - "number": 308, - "rule": "py/unused-import", - "severity": "note", - "description": "Unused import", - "file": "backend/lambda-functions/runtime-provisioner/lambda_function.py", - "start_line": 15, - "end_line": 15, - "message": "Import of 'List' is not used." - }, - { - "number": 307, - "rule": "py/unused-import", - "severity": "note", - "description": "Unused import", - "file": "backend/src/apis/app_api/fine_tuning/job_repository.py", - "start_line": 5, - "end_line": 5, - "message": "Import of 'uuid' is not used." - }, - { - "number": 306, - "rule": "py/unused-import", - "severity": "note", - "description": "Unused import", - "file": "backend/src/apis/app_api/fine_tuning/sagemaker_scripts/inference.py", - "start_line": 23, - "end_line": 23, - "message": "Import of 'np' is not used." - }, - { - "number": 305, - "rule": "py/unused-import", - "severity": "note", - "description": "Unused import", - "file": "backend/src/apis/shared/files/file_resolver.py", - "start_line": 13, - "end_line": 13, - "message": "Import of 'TYPE_CHECKING' is not used." - }, - { - "number": 304, - "rule": "py/unused-import", - "severity": "note", - "description": "Unused import", - "file": "backend/src/agents/main_agent/integrations/external_mcp_client.py", - "start_line": 27, - "end_line": 31, - "message": "Import of 'OAuthBearerAuth' is not used." - }, - { - "number": 303, - "rule": "py/unused-import", - "severity": "note", - "description": "Unused import", - "file": "backend/src/agents/main_agent/integrations/external_mcp_client.py", - "start_line": 15, - "end_line": 15, - "message": "Import of 'Callable' is not used." - }, - { - "number": 302, - "rule": "py/unused-import", - "severity": "note", - "description": "Unused import", - "file": "backend/src/apis/app_api/documents/ingestion/processors/docling_processor.py", - "start_line": 8, - "end_line": 8, - "message": "Import of 'Union' is not used." - }, - { - "number": 301, - "rule": "py/unused-import", - "severity": "note", - "description": "Unused import", - "file": "backend/src/apis/app_api/documents/ingestion/processors/docling_processor.py", - "start_line": 1, - "end_line": 1, - "message": "Import of 'asyncio' is not used." - }, - { - "number": 300, - "rule": "py/unused-import", - "severity": "note", - "description": "Unused import", - "file": "backend/src/apis/app_api/fine_tuning/dependencies.py", - "start_line": 12, - "end_line": 12, - "message": "Import of 'ScriptPackagingService' is not used." - }, - { - "number": 299, - "rule": "py/unused-import", - "severity": "note", - "description": "Unused import", - "file": "backend/src/apis/app_api/fine_tuning/dependencies.py", - "start_line": 11, - "end_line": 11, - "message": "Import of 'InferenceRepository' is not used." - }, - { - "number": 298, - "rule": "py/unused-import", - "severity": "note", - "description": "Unused import", - "file": "backend/src/apis/app_api/fine_tuning/dependencies.py", - "start_line": 10, - "end_line": 10, - "message": "Import of 'SageMakerService' is not used." - }, - { - "number": 297, - "rule": "py/unused-import", - "severity": "note", - "description": "Unused import", - "file": "backend/src/apis/app_api/fine_tuning/dependencies.py", - "start_line": 9, - "end_line": 9, - "message": "Import of 'FineTuningS3Service' is not used." - }, - { - "number": 296, - "rule": "py/unused-import", - "severity": "note", - "description": "Unused import", - "file": "backend/src/apis/app_api/fine_tuning/dependencies.py", - "start_line": 8, - "end_line": 8, - "message": "Import of 'FineTuningJobsRepository' is not used." - }, - { - "number": 295, - "rule": "py/unused-import", - "severity": "note", - "description": "Unused import", - "file": "backend/src/agents/utils/config.py", - "start_line": 4, - "end_line": 4, - "message": "Import of 'os' is not used." - }, - { - "number": 294, - "rule": "py/unused-import", - "severity": "note", - "description": "Unused import", - "file": "backend/src/agents/main_agent/session/compaction_models.py", - "start_line": 9, - "end_line": 9, - "message": "Import of 'datetime' is not used." - }, - { - "number": 293, - "rule": "py/unused-import", - "severity": "note", - "description": "Unused import", - "file": "backend/src/agents/main_agent/session/compaction_models.py", - "start_line": 8, - "end_line": 8, - "message": "Import of 'field' is not used." - }, - { - "number": 292, - "rule": "py/unused-import", - "severity": "note", - "description": "Unused import", - "file": "backend/src/agents/main_agent/quota/checker.py", - "start_line": 8, - "end_line": 8, - "message": "Import of 'QuotaTier' is not used." - }, - { - "number": 291, - "rule": "py/unused-import", - "severity": "note", - "description": "Unused import", - "file": "backend/src/apis/app_api/costs/calculator.py", - "start_line": 9, - "end_line": 9, - "message": "Import of 'Optional' is not used." - }, - { - "number": 290, - "rule": "py/unused-import", - "severity": "note", - "description": "Unused import", - "file": "backend/src/apis/app_api/costs/aggregator.py", - "start_line": 6, - "end_line": 6, - "message": "Import of 'Decimal' is not used." - }, - { - "number": 289, - "rule": "py/unused-import", - "severity": "note", - "description": "Unused import", - "file": "backend/src/apis/shared/rbac/admin_service.py", - "start_line": 5, - "end_line": 5, - "message": "Import of 'datetime' is not used." - }, - { - "number": 288, - "rule": "py/cyclic-import", - "severity": "note", - "description": "Cyclic import", - "file": "backend/src/apis/app_api/storage/metadata_storage.py", - "start_line": 173, - "end_line": 173, - "message": "Import of module storage.dynamodb_storage begins an import cycle." - }, - { - "number": 287, - "rule": "py/cyclic-import", - "severity": "note", - "description": "Cyclic import", - "file": "backend/src/apis/app_api/storage/dynamodb_storage.py", - "start_line": 42, - "end_line": 42, - "message": "Import of module storage.metadata_storage begins an import cycle." - }, - { - "number": 286, - "rule": "py/log-injection", - "severity": "high", - "description": "Log Injection", - "file": "backend/src/apis/app_api/sessions/services/session_service.py", - "start_line": 290, - "end_line": 290, - "message": "This log entry depends on a user-provided value." - }, - { - "number": 285, - "rule": "py/log-injection", - "severity": "high", - "description": "Log Injection", - "file": "backend/src/apis/app_api/sessions/services/session_service.py", - "start_line": 287, - "end_line": 287, - "message": "This log entry depends on a user-provided value." - }, - { - "number": 284, - "rule": "py/log-injection", - "severity": "high", - "description": "Log Injection", - "file": "backend/src/apis/app_api/sessions/services/session_service.py", - "start_line": 275, - "end_line": 275, - "message": "This log entry depends on a user-provided value." - }, - { - "number": 283, - "rule": "py/log-injection", - "severity": "high", - "description": "Log Injection", - "file": "backend/src/apis/app_api/sessions/services/session_service.py", - "start_line": 231, - "end_line": 231, - "message": "This log entry depends on a user-provided value." - }, - { - "number": 282, - "rule": "py/log-injection", - "severity": "high", - "description": "Log Injection", - "file": "backend/src/apis/app_api/sessions/services/session_service.py", - "start_line": 227, - "end_line": 227, - "message": "This log entry depends on a user-provided value." - }, - { - "number": 281, - "rule": "py/log-injection", - "severity": "high", - "description": "Log Injection", - "file": "backend/src/apis/app_api/sessions/services/session_service.py", - "start_line": 198, - "end_line": 198, - "message": "This log entry depends on a user-provided value." - }, - { - "number": 280, - "rule": "py/log-injection", - "severity": "high", - "description": "Log Injection", - "file": "backend/src/apis/app_api/sessions/services/session_service.py", - "start_line": 188, - "end_line": 188, - "message": "This log entry depends on a user-provided value." - }, - { - "number": 279, - "rule": "py/log-injection", - "severity": "high", - "description": "Log Injection", - "file": "backend/src/apis/app_api/sessions/services/session_service.py", - "start_line": 181, - "end_line": 181, - "message": "This log entry depends on a user-provided value." - }, - { - "number": 278, - "rule": "py/log-injection", - "severity": "high", - "description": "Log Injection", - "file": "backend/src/agents/main_agent/session/session_factory.py", - "start_line": 232, - "end_line": 232, - "message": "This log entry depends on a user-provided value." - }, - { - "number": 277, - "rule": "py/log-injection", - "severity": "high", - "description": "Log Injection", - "file": "backend/src/agents/main_agent/session/session_factory.py", - "start_line": 231, - "end_line": 231, - "message": "This log entry depends on a user-provided value." - }, - { - "number": 276, - "rule": "py/log-injection", - "severity": "high", - "description": "Log Injection", - "file": "backend/src/agents/main_agent/session/session_factory.py", - "start_line": 103, - "end_line": 103, - "message": "This log entry depends on a user-provided value." - }, - { - "number": 275, - "rule": "py/log-injection", - "severity": "high", - "description": "Log Injection", - "file": "backend/src/apis/app_api/admin/costs/service.py", - "start_line": 341, - "end_line": 342, - "message": "This log entry depends on a user-provided value." - }, - { - "number": 274, - "rule": "py/log-injection", - "severity": "high", - "description": "Log Injection", - "file": "backend/src/apis/app_api/admin/costs/service.py", - "start_line": 280, - "end_line": 280, - "message": "This log entry depends on a user-provided value." - }, - { - "number": 273, - "rule": "py/log-injection", - "severity": "high", - "description": "Log Injection", - "file": "backend/src/apis/app_api/admin/costs/service.py", - "start_line": 252, - "end_line": 252, - "message": "This log entry depends on a user-provided value." - }, - { - "number": 272, - "rule": "py/log-injection", - "severity": "high", - "description": "Log Injection", - "file": "backend/src/apis/app_api/admin/costs/service.py", - "start_line": 204, - "end_line": 204, - "message": "This log entry depends on a user-provided value." - }, - { - "number": 271, - "rule": "py/log-injection", - "severity": "high", - "description": "Log Injection", - "file": "backend/src/apis/app_api/admin/costs/service.py", - "start_line": 157, - "end_line": 157, - "message": "This log entry depends on a user-provided value." - }, - { - "number": 270, - "rule": "py/log-injection", - "severity": "high", - "description": "Log Injection", - "file": "backend/src/apis/app_api/admin/costs/service.py", - "start_line": 147, - "end_line": 147, - "message": "This log entry depends on a user-provided value." - }, - { - "number": 269, - "rule": "py/log-injection", - "severity": "high", - "description": "Log Injection", - "file": "backend/src/apis/app_api/admin/costs/service.py", - "start_line": 117, - "end_line": 117, - "message": "This log entry depends on a user-provided value." - }, - { - "number": 268, - "rule": "py/log-injection", - "severity": "high", - "description": "Log Injection", - "file": "backend/src/apis/app_api/admin/costs/service.py", - "start_line": 94, - "end_line": 94, - "message": "This log entry depends on a user-provided value." - }, - { - "number": 267, - "rule": "py/log-injection", - "severity": "high", - "description": "Log Injection", - "file": "backend/src/apis/app_api/files/service.py", - "start_line": 355, - "end_line": 355, - "message": "This log entry depends on a user-provided value." - }, - { - "number": 266, - "rule": "py/log-injection", - "severity": "high", - "description": "Log Injection", - "file": "backend/src/apis/app_api/files/service.py", - "start_line": 345, - "end_line": 345, - "message": "This log entry depends on a user-provided value." - }, - { - "number": 265, - "rule": "py/log-injection", - "severity": "high", - "description": "Log Injection", - "file": "backend/src/apis/app_api/files/service.py", - "start_line": 295, - "end_line": 295, - "message": "This log entry depends on a user-provided value." - }, - { - "number": 264, - "rule": "py/log-injection", - "severity": "high", - "description": "Log Injection", - "file": "backend/src/apis/app_api/auth/api_keys/service.py", - "start_line": 78, - "end_line": 78, - "message": "This log entry depends on a user-provided value." - }, - { - "number": 263, - "rule": "py/log-injection", - "severity": "high", - "description": "Log Injection", - "file": "backend/src/apis/app_api/auth/api_keys/service.py", - "start_line": 76, - "end_line": 76, - "message": "This log entry depends on a user-provided value." - }, - { - "number": 262, - "rule": "py/log-injection", - "severity": "high", - "description": "Log Injection", - "file": "backend/src/apis/app_api/admin/quota/service.py", - "start_line": 452, - "end_line": 452, - "message": "This log entry depends on a user-provided value." - }, - { - "number": 261, - "rule": "py/log-injection", - "severity": "high", - "description": "Log Injection", - "file": "backend/src/apis/app_api/admin/quota/service.py", - "start_line": 436, - "end_line": 436, - "message": "This log entry depends on a user-provided value." - }, - { - "number": 260, - "rule": "py/log-injection", - "severity": "high", - "description": "Log Injection", - "file": "backend/src/apis/app_api/admin/quota/service.py", - "start_line": 396, - "end_line": 396, - "message": "This log entry depends on a user-provided value." - }, - { - "number": 259, - "rule": "py/log-injection", - "severity": "high", - "description": "Log Injection", - "file": "backend/src/apis/app_api/admin/quota/service.py", - "start_line": 282, - "end_line": 282, - "message": "This log entry depends on a user-provided value." - }, - { - "number": 258, - "rule": "py/log-injection", - "severity": "high", - "description": "Log Injection", - "file": "backend/src/apis/app_api/admin/quota/service.py", - "start_line": 259, - "end_line": 259, - "message": "This log entry depends on a user-provided value." - }, - { - "number": 257, - "rule": "py/log-injection", - "severity": "high", - "description": "Log Injection", - "file": "backend/src/apis/app_api/admin/quota/service.py", - "start_line": 140, - "end_line": 140, - "message": "This log entry depends on a user-provided value." - }, - { - "number": 256, - "rule": "py/log-injection", - "severity": "high", - "description": "Log Injection", - "file": "backend/src/apis/app_api/admin/quota/service.py", - "start_line": 110, - "end_line": 110, - "message": "This log entry depends on a user-provided value." - }, - { - "number": 255, - "rule": "py/log-injection", - "severity": "high", - "description": "Log Injection", - "file": "backend/src/apis/inference_api/chat/service.py", - "start_line": 175, - "end_line": 175, - "message": "This log entry depends on a user-provided value." - }, - { - "number": 254, - "rule": "py/log-injection", - "severity": "high", - "description": "Log Injection", - "file": "backend/src/apis/inference_api/chat/service.py", - "start_line": 151, - "end_line": 151, - "message": "This log entry depends on a user-provided value." - }, - { - "number": 253, - "rule": "py/log-injection", - "severity": "high", - "description": "Log Injection", - "file": "backend/src/apis/inference_api/chat/service.py", - "start_line": 147, - "end_line": 147, - "message": "This log entry depends on a user-provided value." - }, - { - "number": 252, - "rule": "py/log-injection", - "severity": "high", - "description": "Log Injection", - "file": "backend/src/apis/app_api/admin/quota/routes.py", - "start_line": 636, - "end_line": 637, - "message": "This log entry depends on a user-provided value." - }, - { - "number": 251, - "rule": "py/log-injection", - "severity": "high", - "description": "Log Injection", - "file": "backend/src/apis/app_api/admin/quota/routes.py", - "start_line": 597, - "end_line": 597, - "message": "This log entry depends on a user-provided value." - }, - { - "number": 250, - "rule": "py/log-injection", - "severity": "high", - "description": "Log Injection", - "file": "backend/src/apis/app_api/admin/quota/routes.py", - "start_line": 566, - "end_line": 566, - "message": "This log entry depends on a user-provided value." - }, - { - "number": 249, - "rule": "py/log-injection", - "severity": "high", - "description": "Log Injection", - "file": "backend/src/apis/app_api/admin/quota/routes.py", - "start_line": 530, - "end_line": 530, - "message": "This log entry depends on a user-provided value." - }, - { - "number": 248, - "rule": "py/log-injection", - "severity": "high", - "description": "Log Injection", - "file": "backend/src/apis/app_api/admin/quota/routes.py", - "start_line": 497, - "end_line": 497, - "message": "This log entry depends on a user-provided value." - }, - { - "number": 247, - "rule": "py/log-injection", - "severity": "high", - "description": "Log Injection", - "file": "backend/src/apis/app_api/admin/quota/routes.py", - "start_line": 466, - "end_line": 466, - "message": "This log entry depends on a user-provided value." - }, - { - "number": 246, - "rule": "py/log-injection", - "severity": "high", - "description": "Log Injection", - "file": "backend/src/apis/app_api/admin/quota/routes.py", - "start_line": 422, - "end_line": 422, - "message": "This log entry depends on a user-provided value." - }, - { - "number": 245, - "rule": "py/log-injection", - "severity": "high", - "description": "Log Injection", - "file": "backend/src/apis/app_api/admin/quota/routes.py", - "start_line": 385, - "end_line": 385, - "message": "This log entry depends on a user-provided value." - }, - { - "number": 244, - "rule": "py/log-injection", - "severity": "high", - "description": "Log Injection", - "file": "backend/src/apis/app_api/admin/quota/routes.py", - "start_line": 353, - "end_line": 353, - "message": "This log entry depends on a user-provided value." - }, - { - "number": 243, - "rule": "py/log-injection", - "severity": "high", - "description": "Log Injection", - "file": "backend/src/apis/app_api/admin/quota/routes.py", - "start_line": 320, - "end_line": 320, - "message": "This log entry depends on a user-provided value." - }, - { - "number": 242, - "rule": "py/log-injection", - "severity": "high", - "description": "Log Injection", - "file": "backend/src/apis/app_api/admin/quota/routes.py", - "start_line": 284, - "end_line": 285, - "message": "This log entry depends on a user-provided value." - }, - { - "number": 241, - "rule": "py/log-injection", - "severity": "high", - "description": "Log Injection", - "file": "backend/src/apis/app_api/admin/quota/routes.py", - "start_line": 250, - "end_line": 251, - "message": "This log entry depends on a user-provided value." - }, - { - "number": 240, - "rule": "py/log-injection", - "severity": "high", - "description": "Log Injection", - "file": "backend/src/apis/app_api/admin/quota/routes.py", - "start_line": 211, - "end_line": 211, - "message": "This log entry depends on a user-provided value." - }, - { - "number": 239, - "rule": "py/log-injection", - "severity": "high", - "description": "Log Injection", - "file": "backend/src/apis/app_api/admin/quota/routes.py", - "start_line": 176, - "end_line": 176, - "message": "This log entry depends on a user-provided value." - }, - { - "number": 238, - "rule": "py/log-injection", - "severity": "high", - "description": "Log Injection", - "file": "backend/src/apis/app_api/admin/quota/routes.py", - "start_line": 144, - "end_line": 144, - "message": "This log entry depends on a user-provided value." - }, - { - "number": 237, - "rule": "py/log-injection", - "severity": "high", - "description": "Log Injection", - "file": "backend/src/apis/app_api/admin/quota/routes.py", - "start_line": 113, - "end_line": 113, - "message": "This log entry depends on a user-provided value." - }, - { - "number": 236, - "rule": "py/log-injection", - "severity": "high", - "description": "Log Injection", - "file": "backend/src/apis/app_api/admin/quota/routes.py", - "start_line": 84, - "end_line": 84, - "message": "This log entry depends on a user-provided value." - }, - { - "number": 235, - "rule": "py/log-injection", - "severity": "high", - "description": "Log Injection", - "file": "backend/src/apis/inference_api/chat/routes.py", - "start_line": 520, - "end_line": 520, - "message": "This log entry depends on a user-provided value." - }, - { - "number": 234, - "rule": "py/log-injection", - "severity": "high", - "description": "Log Injection", - "file": "backend/src/apis/inference_api/chat/routes.py", - "start_line": 507, - "end_line": 507, - "message": "This log entry depends on a user-provided value." - }, - { - "number": 233, - "rule": "py/log-injection", - "severity": "high", - "description": "Log Injection", - "file": "backend/src/apis/inference_api/chat/routes.py", - "start_line": 468, - "end_line": 468, - "message": "This log entry depends on a user-provided value." - }, - { - "number": 232, - "rule": "py/log-injection", - "severity": "high", - "description": "Log Injection", - "file": "backend/src/apis/inference_api/chat/routes.py", - "start_line": 461, - "end_line": 461, - "message": "This log entry depends on a user-provided value." - }, - { - "number": 231, - "rule": "py/log-injection", - "severity": "high", - "description": "Log Injection", - "file": "backend/src/apis/inference_api/chat/routes.py", - "start_line": 458, - "end_line": 458, - "message": "This log entry depends on a user-provided value." - }, - { - "number": 230, - "rule": "py/log-injection", - "severity": "high", - "description": "Log Injection", - "file": "backend/src/apis/inference_api/chat/routes.py", - "start_line": 427, - "end_line": 427, - "message": "This log entry depends on a user-provided value." - }, - { - "number": 229, - "rule": "py/log-injection", - "severity": "high", - "description": "Log Injection", - "file": "backend/src/apis/inference_api/chat/routes.py", - "start_line": 409, - "end_line": 409, - "message": "This log entry depends on a user-provided value." - }, - { - "number": 228, - "rule": "py/log-injection", - "severity": "high", - "description": "Log Injection", - "file": "backend/src/apis/inference_api/chat/routes.py", - "start_line": 407, - "end_line": 407, - "message": "This log entry depends on a user-provided value." - }, - { - "number": 227, - "rule": "py/log-injection", - "severity": "high", - "description": "Log Injection", - "file": "backend/src/apis/inference_api/chat/routes.py", - "start_line": 389, - "end_line": 389, - "message": "This log entry depends on a user-provided value." - }, - { - "number": 226, - "rule": "py/log-injection", - "severity": "high", - "description": "Log Injection", - "file": "backend/src/apis/inference_api/chat/routes.py", - "start_line": 386, - "end_line": 386, - "message": "This log entry depends on a user-provided value." - }, - { - "number": 225, - "rule": "py/log-injection", - "severity": "high", - "description": "Log Injection", - "file": "backend/src/apis/inference_api/chat/routes.py", - "start_line": 379, - "end_line": 379, - "message": "This log entry depends on a user-provided value." - }, - { - "number": 224, - "rule": "py/log-injection", - "severity": "high", - "description": "Log Injection", - "file": "backend/src/apis/inference_api/chat/routes.py", - "start_line": 375, - "end_line": 375, - "message": "This log entry depends on a user-provided value." - }, - { - "number": 223, - "rule": "py/log-injection", - "severity": "high", - "description": "Log Injection", - "file": "backend/src/apis/inference_api/chat/routes.py", - "start_line": 361, - "end_line": 361, - "message": "This log entry depends on a user-provided value." - }, - { - "number": 222, - "rule": "py/log-injection", - "severity": "high", - "description": "Log Injection", - "file": "backend/src/apis/inference_api/chat/routes.py", - "start_line": 351, - "end_line": 351, - "message": "This log entry depends on a user-provided value." - }, - { - "number": 221, - "rule": "py/log-injection", - "severity": "high", - "description": "Log Injection", - "file": "backend/src/apis/inference_api/chat/routes.py", - "start_line": 345, - "end_line": 345, - "message": "This log entry depends on a user-provided value." - }, - { - "number": 220, - "rule": "py/log-injection", - "severity": "high", - "description": "Log Injection", - "file": "backend/src/apis/inference_api/chat/routes.py", - "start_line": 329, - "end_line": 329, - "message": "This log entry depends on a user-provided value." - }, - { - "number": 219, - "rule": "py/log-injection", - "severity": "high", - "description": "Log Injection", - "file": "backend/src/apis/inference_api/chat/routes.py", - "start_line": 306, - "end_line": 306, - "message": "This log entry depends on a user-provided value." - }, - { - "number": 218, - "rule": "py/log-injection", - "severity": "high", - "description": "Log Injection", - "file": "backend/src/apis/inference_api/chat/routes.py", - "start_line": 218, - "end_line": 218, - "message": "This log entry depends on a user-provided value." - }, - { - "number": 217, - "rule": "py/log-injection", - "severity": "high", - "description": "Log Injection", - "file": "backend/src/apis/inference_api/chat/routes.py", - "start_line": 215, - "end_line": 215, - "message": "This log entry depends on a user-provided value." - }, - { - "number": 216, - "rule": "py/log-injection", - "severity": "high", - "description": "Log Injection", - "file": "backend/src/apis/inference_api/chat/routes.py", - "start_line": 214, - "end_line": 214, - "message": "This log entry depends on a user-provided value." - }, - { - "number": 215, - "rule": "py/log-injection", - "severity": "high", - "description": "Log Injection", - "file": "backend/src/apis/inference_api/chat/routes.py", - "start_line": 180, - "end_line": 180, - "message": "This log entry depends on a user-provided value." - }, - { - "number": 214, - "rule": "py/log-injection", - "severity": "high", - "description": "Log Injection", - "file": "backend/src/apis/inference_api/chat/routes.py", - "start_line": 157, - "end_line": 157, - "message": "This log entry depends on a user-provided value." - }, - { - "number": 213, - "rule": "py/log-injection", - "severity": "high", - "description": "Log Injection", - "file": "backend/src/apis/inference_api/chat/routes.py", - "start_line": 103, - "end_line": 103, - "message": "This log entry depends on a user-provided value." - }, - { - "number": 212, - "rule": "py/log-injection", - "severity": "high", - "description": "Log Injection", - "file": "backend/src/apis/inference_api/chat/routes.py", - "start_line": 99, - "end_line": 99, - "message": "This log entry depends on a user-provided value." - }, - { - "number": 211, - "rule": "py/log-injection", - "severity": "high", - "description": "Log Injection", - "file": "backend/src/apis/inference_api/chat/routes.py", - "start_line": 95, - "end_line": 95, - "message": "This log entry depends on a user-provided value." - }, - { - "number": 210, - "rule": "py/log-injection", - "severity": "high", - "description": "Log Injection", - "file": "backend/src/apis/app_api/costs/routes.py", - "start_line": 105, - "end_line": 105, - "message": "This log entry depends on a user-provided value." - }, - { - "number": 209, - "rule": "py/log-injection", - "severity": "high", - "description": "Log Injection", - "file": "backend/src/apis/app_api/costs/routes.py", - "start_line": 62, - "end_line": 62, - "message": "This log entry depends on a user-provided value." - }, - { - "number": 208, - "rule": "py/log-injection", - "severity": "high", - "description": "Log Injection", - "file": "backend/src/apis/app_api/costs/routes.py", - "start_line": 52, - "end_line": 52, - "message": "This log entry depends on a user-provided value." - }, - { - "number": 207, - "rule": "py/log-injection", - "severity": "high", - "description": "Log Injection", - "file": "backend/src/apis/app_api/admin/users/routes.py", - "start_line": 166, - "end_line": 166, - "message": "This log entry depends on a user-provided value." - }, - { - "number": 206, - "rule": "py/log-injection", - "severity": "high", - "description": "Log Injection", - "file": "backend/src/apis/app_api/admin/users/routes.py", - "start_line": 114, - "end_line": 114, - "message": "This log entry depends on a user-provided value." - }, - { - "number": 205, - "rule": "py/log-injection", - "severity": "high", - "description": "Log Injection", - "file": "backend/src/apis/app_api/admin/users/routes.py", - "start_line": 85, - "end_line": 85, - "message": "This log entry depends on a user-provided value." - }, - { - "number": 204, - "rule": "py/log-injection", - "severity": "high", - "description": "Log Injection", - "file": "backend/src/apis/app_api/admin/costs/routes.py", - "start_line": 416, - "end_line": 416, - "message": "This log entry depends on a user-provided value." - }, - { - "number": 203, - "rule": "py/log-injection", - "severity": "high", - "description": "Log Injection", - "file": "backend/src/apis/app_api/admin/costs/routes.py", - "start_line": 360, - "end_line": 361, - "message": "This log entry depends on a user-provided value." - }, - { - "number": 202, - "rule": "py/log-injection", - "severity": "high", - "description": "Log Injection", - "file": "backend/src/apis/app_api/admin/costs/routes.py", - "start_line": 307, - "end_line": 307, - "message": "This log entry depends on a user-provided value." - }, - { - "number": 201, - "rule": "py/log-injection", - "severity": "high", - "description": "Log Injection", - "file": "backend/src/apis/app_api/admin/costs/routes.py", - "start_line": 263, - "end_line": 263, - "message": "This log entry depends on a user-provided value." - }, - { - "number": 200, - "rule": "py/log-injection", - "severity": "high", - "description": "Log Injection", - "file": "backend/src/apis/app_api/admin/costs/routes.py", - "start_line": 214, - "end_line": 215, - "message": "This log entry depends on a user-provided value." - }, - { - "number": 199, - "rule": "py/log-injection", - "severity": "high", - "description": "Log Injection", - "file": "backend/src/apis/app_api/admin/costs/routes.py", - "start_line": 158, - "end_line": 159, - "message": "This log entry depends on a user-provided value." - }, - { - "number": 198, - "rule": "py/log-injection", - "severity": "high", - "description": "Log Injection", - "file": "backend/src/apis/app_api/admin/costs/routes.py", - "start_line": 93, - "end_line": 93, - "message": "This log entry depends on a user-provided value." - }, - { - "number": 197, - "rule": "py/log-injection", - "severity": "high", - "description": "Log Injection", - "file": "backend/src/apis/app_api/admin/fine_tuning/routes.py", - "start_line": 191, - "end_line": 191, - "message": "This log entry depends on a user-provided value." - }, - { - "number": 196, - "rule": "py/log-injection", - "severity": "high", - "description": "Log Injection", - "file": "backend/src/apis/app_api/admin/fine_tuning/routes.py", - "start_line": 169, - "end_line": 169, - "message": "This log entry depends on a user-provided value." - }, - { - "number": 195, - "rule": "py/log-injection", - "severity": "high", - "description": "Log Injection", - "file": "backend/src/apis/app_api/admin/fine_tuning/routes.py", - "start_line": 144, - "end_line": 144, - "message": "This log entry depends on a user-provided value." - }, - { - "number": 194, - "rule": "py/log-injection", - "severity": "high", - "description": "Log Injection", - "file": "backend/src/apis/app_api/admin/fine_tuning/routes.py", - "start_line": 118, - "end_line": 119, - "message": "This log entry depends on a user-provided value." - }, - { - "number": 193, - "rule": "py/log-injection", - "severity": "high", - "description": "Log Injection", - "file": "backend/src/apis/app_api/admin/fine_tuning/routes.py", - "start_line": 98, - "end_line": 98, - "message": "This log entry depends on a user-provided value." - }, - { - "number": 192, - "rule": "py/log-injection", - "severity": "high", - "description": "Log Injection", - "file": "backend/src/apis/app_api/admin/fine_tuning/routes.py", - "start_line": 75, - "end_line": 75, - "message": "This log entry depends on a user-provided value." - }, - { - "number": 191, - "rule": "py/log-injection", - "severity": "high", - "description": "Log Injection", - "file": "backend/src/apis/app_api/sessions/routes.py", - "start_line": 528, - "end_line": 528, - "message": "This log entry depends on a user-provided value." - }, - { - "number": 190, - "rule": "py/log-injection", - "severity": "high", - "description": "Log Injection", - "file": "backend/src/apis/app_api/sessions/routes.py", - "start_line": 517, - "end_line": 517, - "message": "This log entry depends on a user-provided value." - }, - { - "number": 189, - "rule": "py/log-injection", - "severity": "high", - "description": "Log Injection", - "file": "backend/src/apis/app_api/sessions/routes.py", - "start_line": 506, - "end_line": 506, - "message": "This log entry depends on a user-provided value." - }, - { - "number": 188, - "rule": "py/log-injection", - "severity": "high", - "description": "Log Injection", - "file": "backend/src/apis/app_api/sessions/routes.py", - "start_line": 355, - "end_line": 355, - "message": "This log entry depends on a user-provided value." - }, - { - "number": 187, - "rule": "py/log-injection", - "severity": "high", - "description": "Log Injection", - "file": "backend/src/apis/app_api/sessions/routes.py", - "start_line": 324, - "end_line": 324, - "message": "This log entry depends on a user-provided value." - }, - { - "number": 186, - "rule": "py/log-injection", - "severity": "high", - "description": "Log Injection", - "file": "backend/src/apis/app_api/sessions/routes.py", - "start_line": 173, - "end_line": 173, - "message": "This log entry depends on a user-provided value." - }, - { - "number": 185, - "rule": "py/log-injection", - "severity": "high", - "description": "Log Injection", - "file": "backend/src/apis/app_api/sessions/routes.py", - "start_line": 115, - "end_line": 115, - "message": "This log entry depends on a user-provided value." - }, - { - "number": 184, - "rule": "py/log-injection", - "severity": "high", - "description": "Log Injection", - "file": "backend/src/apis/app_api/admin/routes.py", - "start_line": 689, - "end_line": 689, - "message": "This log entry depends on a user-provided value." - }, - { - "number": 183, - "rule": "py/log-injection", - "severity": "high", - "description": "Log Injection", - "file": "backend/src/apis/app_api/sessions/routes.py", - "start_line": 59, - "end_line": 59, - "message": "This log entry depends on a user-provided value." - }, - { - "number": 182, - "rule": "py/log-injection", - "severity": "high", - "description": "Log Injection", - "file": "backend/src/apis/app_api/admin/routes.py", - "start_line": 649, - "end_line": 649, - "message": "This log entry depends on a user-provided value." - }, - { - "number": 181, - "rule": "py/log-injection", - "severity": "high", - "description": "Log Injection", - "file": "backend/src/apis/app_api/admin/routes.py", - "start_line": 598, - "end_line": 598, - "message": "This log entry depends on a user-provided value." - }, - { - "number": 180, - "rule": "py/log-injection", - "severity": "high", - "description": "Log Injection", - "file": "backend/src/apis/app_api/admin/routes.py", - "start_line": 547, - "end_line": 547, - "message": "This log entry depends on a user-provided value." - }, - { - "number": 179, - "rule": "py/log-injection", - "severity": "high", - "description": "Log Injection", - "file": "backend/src/apis/app_api/admin/routes.py", - "start_line": 497, - "end_line": 497, - "message": "This log entry depends on a user-provided value." - }, - { - "number": 178, - "rule": "py/log-injection", - "severity": "high", - "description": "Log Injection", - "file": "backend/src/apis/app_api/admin/routes.py", - "start_line": 361, - "end_line": 361, - "message": "This log entry depends on a user-provided value." - }, - { - "number": 177, - "rule": "py/log-injection", - "severity": "high", - "description": "Log Injection", - "file": "backend/src/apis/app_api/users/routes.py", - "start_line": 169, - "end_line": 169, - "message": "This log entry depends on a user-provided value." - }, - { - "number": 176, - "rule": "py/log-injection", - "severity": "high", - "description": "Log Injection", - "file": "backend/src/apis/app_api/users/routes.py", - "start_line": 84, - "end_line": 84, - "message": "This log entry depends on a user-provided value." - }, - { - "number": 175, - "rule": "py/log-injection", - "severity": "high", - "description": "Log Injection", - "file": "backend/src/apis/app_api/auth/api_keys/routes.py", - "start_line": 98, - "end_line": 98, - "message": "This log entry depends on a user-provided value." - }, - { - "number": 174, - "rule": "py/log-injection", - "severity": "high", - "description": "Log Injection", - "file": "backend/src/apis/app_api/admin/routes.py", - "start_line": 268, - "end_line": 268, - "message": "This log entry depends on a user-provided value." - }, - { - "number": 173, - "rule": "py/log-injection", - "severity": "high", - "description": "Log Injection", - "file": "backend/src/apis/app_api/admin/routes.py", - "start_line": 123, - "end_line": 123, - "message": "This log entry depends on a user-provided value." - }, - { - "number": 172, - "rule": "py/log-injection", - "severity": "high", - "description": "Log Injection", - "file": "backend/src/apis/app_api/admin/auth_providers/routes.py", - "start_line": 258, - "end_line": 258, - "message": "This log entry depends on a user-provided value." - }, - { - "number": 171, - "rule": "py/log-injection", - "severity": "high", - "description": "Log Injection", - "file": "backend/src/apis/app_api/admin/auth_providers/routes.py", - "start_line": 213, - "end_line": 213, - "message": "This log entry depends on a user-provided value." - }, - { - "number": 170, - "rule": "py/log-injection", - "severity": "high", - "description": "Log Injection", - "file": "backend/src/apis/app_api/admin/auth_providers/routes.py", - "start_line": 183, - "end_line": 183, - "message": "This log entry depends on a user-provided value." - }, - { - "number": 169, - "rule": "py/log-injection", - "severity": "high", - "description": "Log Injection", - "file": "backend/src/apis/app_api/admin/auth_providers/routes.py", - "start_line": 124, - "end_line": 124, - "message": "This log entry depends on a user-provided value." - }, - { - "number": 168, - "rule": "py/log-injection", - "severity": "high", - "description": "Log Injection", - "file": "backend/src/apis/app_api/admin/auth_providers/routes.py", - "start_line": 39, - "end_line": 39, - "message": "This log entry depends on a user-provided value." - }, - { - "number": 167, - "rule": "py/log-injection", - "severity": "high", - "description": "Log Injection", - "file": "backend/src/apis/app_api/admin/tools/routes.py", - "start_line": 372, - "end_line": 372, - "message": "This log entry depends on a user-provided value." - }, - { - "number": 166, - "rule": "py/log-injection", - "severity": "high", - "description": "Log Injection", - "file": "backend/src/apis/app_api/admin/tools/routes.py", - "start_line": 335, - "end_line": 335, - "message": "This log entry depends on a user-provided value." - }, - { - "number": 165, - "rule": "py/log-injection", - "severity": "high", - "description": "Log Injection", - "file": "backend/src/apis/app_api/admin/tools/routes.py", - "start_line": 305, - "end_line": 305, - "message": "This log entry depends on a user-provided value." - }, - { - "number": 164, - "rule": "py/log-injection", - "severity": "high", - "description": "Log Injection", - "file": "backend/src/apis/app_api/admin/tools/routes.py", - "start_line": 275, - "end_line": 275, - "message": "This log entry depends on a user-provided value." - }, - { - "number": 163, - "rule": "py/log-injection", - "severity": "high", - "description": "Log Injection", - "file": "backend/src/apis/app_api/admin/tools/routes.py", - "start_line": 239, - "end_line": 239, - "message": "This log entry depends on a user-provided value." - }, - { - "number": 162, - "rule": "py/log-injection", - "severity": "high", - "description": "Log Injection", - "file": "backend/src/apis/app_api/admin/tools/routes.py", - "start_line": 205, - "end_line": 205, - "message": "This log entry depends on a user-provided value." - }, - { - "number": 161, - "rule": "py/log-injection", - "severity": "high", - "description": "Log Injection", - "file": "backend/src/apis/app_api/admin/tools/routes.py", - "start_line": 160, - "end_line": 160, - "message": "This log entry depends on a user-provided value." - }, - { - "number": 160, - "rule": "py/log-injection", - "severity": "high", - "description": "Log Injection", - "file": "backend/src/apis/app_api/admin/tools/routes.py", - "start_line": 72, - "end_line": 72, - "message": "This log entry depends on a user-provided value." - }, - { - "number": 159, - "rule": "py/log-injection", - "severity": "high", - "description": "Log Injection", - "file": "backend/src/apis/app_api/auth/routes.py", - "start_line": 244, - "end_line": 244, - "message": "This log entry depends on a user-provided value." - }, - { - "number": 158, - "rule": "py/log-injection", - "severity": "high", - "description": "Log Injection", - "file": "backend/src/apis/app_api/auth/routes.py", - "start_line": 112, - "end_line": 112, - "message": "This log entry depends on a user-provided value." - }, - { - "number": 157, - "rule": "py/log-injection", - "severity": "high", - "description": "Log Injection", - "file": "backend/src/apis/app_api/files/routes.py", - "start_line": 209, - "end_line": 209, - "message": "This log entry depends on a user-provided value." - }, - { - "number": 156, - "rule": "py/log-injection", - "severity": "high", - "description": "Log Injection", - "file": "backend/src/apis/app_api/files/routes.py", - "start_line": 180, - "end_line": 182, - "message": "This log entry depends on a user-provided value." - }, - { - "number": 155, - "rule": "py/log-injection", - "severity": "high", - "description": "Log Injection", - "file": "backend/src/apis/app_api/files/routes.py", - "start_line": 132, - "end_line": 132, - "message": "This log entry depends on a user-provided value." - }, - { - "number": 154, - "rule": "py/log-injection", - "severity": "high", - "description": "Log Injection", - "file": "backend/src/apis/app_api/files/routes.py", - "start_line": 119, - "end_line": 119, - "message": "This log entry depends on a user-provided value." - }, - { - "number": 153, - "rule": "py/log-injection", - "severity": "high", - "description": "Log Injection", - "file": "backend/src/apis/app_api/memory/routes.py", - "start_line": 482, - "end_line": 482, - "message": "This log entry depends on a user-provided value." - }, - { - "number": 152, - "rule": "py/log-injection", - "severity": "high", - "description": "Log Injection", - "file": "backend/src/apis/app_api/assistants/routes.py", - "start_line": 693, - "end_line": 693, - "message": "This log entry depends on a user-provided value." - }, - { - "number": 151, - "rule": "py/log-injection", - "severity": "high", - "description": "Log Injection", - "file": "backend/src/apis/app_api/assistants/routes.py", - "start_line": 650, - "end_line": 650, - "message": "This log entry depends on a user-provided value." - }, - { - "number": 150, - "rule": "py/log-injection", - "severity": "high", - "description": "Log Injection", - "file": "backend/src/apis/app_api/assistants/routes.py", - "start_line": 606, - "end_line": 606, - "message": "This log entry depends on a user-provided value." - }, - { - "number": 149, - "rule": "py/log-injection", - "severity": "high", - "description": "Log Injection", - "file": "backend/src/apis/app_api/assistants/routes.py", - "start_line": 476, - "end_line": 476, - "message": "This log entry depends on a user-provided value." - }, - { - "number": 148, - "rule": "py/log-injection", - "severity": "high", - "description": "Log Injection", - "file": "backend/src/apis/app_api/assistants/routes.py", - "start_line": 427, - "end_line": 427, - "message": "This log entry depends on a user-provided value." - }, - { - "number": 147, - "rule": "py/log-injection", - "severity": "high", - "description": "Log Injection", - "file": "backend/src/apis/app_api/assistants/routes.py", - "start_line": 382, - "end_line": 382, - "message": "This log entry depends on a user-provided value." - }, - { - "number": 146, - "rule": "py/log-injection", - "severity": "high", - "description": "Log Injection", - "file": "backend/src/apis/app_api/assistants/routes.py", - "start_line": 324, - "end_line": 324, - "message": "This log entry depends on a user-provided value." - }, - { - "number": 145, - "rule": "py/log-injection", - "severity": "high", - "description": "Log Injection", - "file": "backend/src/apis/app_api/assistants/routes.py", - "start_line": 269, - "end_line": 269, - "message": "This log entry depends on a user-provided value." - }, - { - "number": 144, - "rule": "py/log-injection", - "severity": "high", - "description": "Log Injection", - "file": "backend/src/apis/app_api/assistants/routes.py", - "start_line": 186, - "end_line": 187, - "message": "This log entry depends on a user-provided value." - }, - { - "number": 143, - "rule": "py/log-injection", - "severity": "high", - "description": "Log Injection", - "file": "backend/src/apis/app_api/memory/routes.py", - "start_line": 358, - "end_line": 358, - "message": "This log entry depends on a user-provided value." - }, - { - "number": 142, - "rule": "py/log-injection", - "severity": "high", - "description": "Log Injection", - "file": "backend/src/apis/app_api/memory/routes.py", - "start_line": 280, - "end_line": 280, - "message": "This log entry depends on a user-provided value." - }, - { - "number": 141, - "rule": "py/log-injection", - "severity": "high", - "description": "Log Injection", - "file": "backend/src/apis/app_api/memory/routes.py", - "start_line": 220, - "end_line": 220, - "message": "This log entry depends on a user-provided value." - }, - { - "number": 140, - "rule": "py/log-injection", - "severity": "high", - "description": "Log Injection", - "file": "backend/src/apis/app_api/memory/routes.py", - "start_line": 149, - "end_line": 149, - "message": "This log entry depends on a user-provided value." - }, - { - "number": 139, - "rule": "py/log-injection", - "severity": "high", - "description": "Log Injection", - "file": "backend/src/apis/app_api/admin/oauth/routes.py", - "start_line": 280, - "end_line": 280, - "message": "This log entry depends on a user-provided value." - }, - { - "number": 138, - "rule": "py/log-injection", - "severity": "high", - "description": "Log Injection", - "file": "backend/src/apis/app_api/admin/oauth/routes.py", - "start_line": 235, - "end_line": 235, - "message": "This log entry depends on a user-provided value." - }, - { - "number": 137, - "rule": "py/log-injection", - "severity": "high", - "description": "Log Injection", - "file": "backend/src/apis/app_api/admin/oauth/routes.py", - "start_line": 218, - "end_line": 218, - "message": "This log entry depends on a user-provided value." - }, - { - "number": 136, - "rule": "py/log-injection", - "severity": "high", - "description": "Log Injection", - "file": "backend/src/apis/app_api/admin/oauth/routes.py", - "start_line": 182, - "end_line": 183, - "message": "This log entry depends on a user-provided value." - }, - { - "number": 135, - "rule": "py/log-injection", - "severity": "high", - "description": "Log Injection", - "file": "backend/src/apis/app_api/admin/oauth/routes.py", - "start_line": 159, - "end_line": 159, - "message": "This log entry depends on a user-provided value." - }, - { - "number": 134, - "rule": "py/log-injection", - "severity": "high", - "description": "Log Injection", - "file": "backend/src/apis/app_api/admin/oauth/routes.py", - "start_line": 83, - "end_line": 83, - "message": "This log entry depends on a user-provided value." - }, - { - "number": 133, - "rule": "py/log-injection", - "severity": "high", - "description": "Log Injection", - "file": "backend/src/apis/app_api/memory/routes.py", - "start_line": 84, - "end_line": 84, - "message": "This log entry depends on a user-provided value." - }, - { - "number": 132, - "rule": "py/log-injection", - "severity": "high", - "description": "Log Injection", - "file": "backend/src/apis/app_api/documents/routes.py", - "start_line": 238, - "end_line": 238, - "message": "This log entry depends on a user-provided value." - }, - { - "number": 131, - "rule": "py/log-injection", - "severity": "high", - "description": "Log Injection", - "file": "backend/src/apis/app_api/documents/routes.py", - "start_line": 235, - "end_line": 235, - "message": "This log entry depends on a user-provided value." - }, - { - "number": 130, - "rule": "py/log-injection", - "severity": "high", - "description": "Log Injection", - "file": "backend/src/apis/shared/oauth/routes.py", - "start_line": 255, - "end_line": 255, - "message": "This log entry depends on a user-provided value." - }, - { - "number": 129, - "rule": "py/log-injection", - "severity": "high", - "description": "Log Injection", - "file": "backend/src/apis/shared/oauth/routes.py", - "start_line": 183, - "end_line": 183, - "message": "This log entry depends on a user-provided value." - }, - { - "number": 128, - "rule": "py/log-injection", - "severity": "high", - "description": "Log Injection", - "file": "backend/src/apis/shared/oauth/routes.py", - "start_line": 137, - "end_line": 137, - "message": "This log entry depends on a user-provided value." - }, - { - "number": 127, - "rule": "py/log-injection", - "severity": "high", - "description": "Log Injection", - "file": "backend/src/apis/app_api/admin/roles/routes.py", - "start_line": 239, - "end_line": 239, - "message": "This log entry depends on a user-provided value." - }, - { - "number": 126, - "rule": "py/log-injection", - "severity": "high", - "description": "Log Injection", - "file": "backend/src/apis/app_api/admin/roles/routes.py", - "start_line": 197, - "end_line": 197, - "message": "This log entry depends on a user-provided value." - }, - { - "number": 125, - "rule": "py/log-injection", - "severity": "high", - "description": "Log Injection", - "file": "backend/src/apis/app_api/admin/roles/routes.py", - "start_line": 155, - "end_line": 155, - "message": "This log entry depends on a user-provided value." - }, - { - "number": 124, - "rule": "py/log-injection", - "severity": "high", - "description": "Log Injection", - "file": "backend/src/apis/app_api/admin/roles/routes.py", - "start_line": 81, - "end_line": 81, - "message": "This log entry depends on a user-provided value." - }, - { - "number": 123, - "rule": "py/log-injection", - "severity": "high", - "description": "Log Injection", - "file": "backend/src/agents/main_agent/session/preview_session_manager.py", - "start_line": 58, - "end_line": 58, - "message": "This log entry depends on a user-provided value." - }, - { - "number": 122, - "rule": "py/log-injection", - "severity": "high", - "description": "Log Injection", - "file": "backend/src/apis/app_api/memory/services/memory_service.py", - "start_line": 472, - "end_line": 472, - "message": "This log entry depends on a user-provided value." - }, - { - "number": 121, - "rule": "py/log-injection", - "severity": "high", - "description": "Log Injection", - "file": "backend/src/apis/app_api/memory/services/memory_service.py", - "start_line": 468, - "end_line": 468, - "message": "This log entry depends on a user-provided value." - }, - { - "number": 120, - "rule": "py/log-injection", - "severity": "high", - "description": "Log Injection", - "file": "backend/src/apis/app_api/memory/services/memory_service.py", - "start_line": 465, - "end_line": 465, - "message": "This log entry depends on a user-provided value." - }, - { - "number": 119, - "rule": "py/log-injection", - "severity": "high", - "description": "Log Injection", - "file": "backend/src/apis/app_api/memory/services/memory_service.py", - "start_line": 461, - "end_line": 461, - "message": "This log entry depends on a user-provided value." - }, - { - "number": 118, - "rule": "py/log-injection", - "severity": "high", - "description": "Log Injection", - "file": "backend/src/apis/app_api/memory/services/memory_service.py", - "start_line": 448, - "end_line": 448, - "message": "This log entry depends on a user-provided value." - }, - { - "number": 117, - "rule": "py/log-injection", - "severity": "high", - "description": "Log Injection", - "file": "backend/src/apis/app_api/memory/services/memory_service.py", - "start_line": 298, - "end_line": 298, - "message": "This log entry depends on a user-provided value." - }, - { - "number": 116, - "rule": "py/log-injection", - "severity": "high", - "description": "Log Injection", - "file": "backend/src/apis/app_api/memory/services/memory_service.py", - "start_line": 247, - "end_line": 247, - "message": "This log entry depends on a user-provided value." - }, - { - "number": 115, - "rule": "py/log-injection", - "severity": "high", - "description": "Log Injection", - "file": "backend/src/apis/app_api/fine_tuning/job_repository.py", - "start_line": 128, - "end_line": 128, - "message": "This log entry depends on a user-provided value." - }, - { - "number": 114, - "rule": "py/log-injection", - "severity": "high", - "description": "Log Injection", - "file": "backend/src/apis/app_api/fine_tuning/inference_repository.py", - "start_line": 128, - "end_line": 128, - "message": "This log entry depends on a user-provided value." - }, - { - "number": 113, - "rule": "py/log-injection", - "severity": "high", - "description": "Log Injection", - "file": "backend/src/agents/main_agent/integrations/external_mcp_client.py", - "start_line": 332, - "end_line": 333, - "message": "This log entry depends on a user-provided value." - }, - { - "number": 112, - "rule": "py/log-injection", - "severity": "high", - "description": "Log Injection", - "file": "backend/src/agents/main_agent/integrations/external_mcp_client.py", - "start_line": 246, - "end_line": 246, - "message": "This log entry depends on a user-provided value." - }, - { - "number": 111, - "rule": "py/log-injection", - "severity": "high", - "description": "Log Injection", - "file": "backend/src/apis/inference_api/chat/converse_routes.py", - "start_line": 340, - "end_line": 342, - "message": "This log entry depends on a user-provided value." - }, - { - "number": 110, - "rule": "py/log-injection", - "severity": "high", - "description": "Log Injection", - "file": "backend/src/apis/inference_api/chat/converse_routes.py", - "start_line": 128, - "end_line": 128, - "message": "This log entry depends on a user-provided value." - }, - { - "number": 109, - "rule": "py/log-injection", - "severity": "high", - "description": "Log Injection", - "file": "backend/src/apis/inference_api/chat/converse_routes.py", - "start_line": 87, - "end_line": 87, - "message": "This log entry depends on a user-provided value." - }, - { - "number": 108, - "rule": "py/log-injection", - "severity": "high", - "description": "Log Injection", - "file": "backend/src/apis/app_api/costs/aggregator.py", - "start_line": 48, - "end_line": 48, - "message": "This log entry depends on a user-provided value." - }, - { - "number": 107, - "rule": "py/log-injection", - "severity": "high", - "description": "Log Injection", - "file": "backend/src/apis/app_api/costs/aggregator.py", - "start_line": 37, - "end_line": 37, - "message": "This log entry depends on a user-provided value." - } -] \ No newline at end of file diff --git a/docs/ADMIN_COST_DASHBOARD_SPEC.md b/docs/ADMIN_COST_DASHBOARD_SPEC.md deleted file mode 100644 index 1c21c245..00000000 --- a/docs/ADMIN_COST_DASHBOARD_SPEC.md +++ /dev/null @@ -1,1148 +0,0 @@ -# Admin Aggregate User Cost Dashboard Specification - -## Executive Summary - -This specification outlines a performant admin dashboard for viewing aggregate user costs across 10,000+ users. The design avoids table scans by leveraging new GSIs and pre-aggregated data structures, ensuring sub-second response times even at scale. - -**Target Performance:** -- Dashboard load: <500ms for 10,000+ users -- Top N queries: <200ms -- Time-series aggregations: <300ms -- Zero table scans - -**Prerequisites:** User cost tracking and quota management (already implemented) - ---- - -## Table of Contents - -1. [Current State Analysis](#current-state-analysis) -2. [Performance Challenge](#performance-challenge) -3. [Solution Architecture](#solution-architecture) -4. [New Infrastructure Requirements](#new-infrastructure-requirements) -5. [Data Models](#data-models) -6. [API Design](#api-design) -7. [Frontend Design](#frontend-design) -8. [Implementation Plan](#implementation-plan) -9. [Appendix: DynamoDB Schema Updates](#appendix-dynamodb-schema-updates) - ---- - -## Current State Analysis - -### What We Have - -| Component | Status | Notes | -|-----------|--------|-------| -| **SessionsMetadata Table** | Implemented | Message-level cost tracking | -| **UserCostSummary Table** | Implemented | Pre-aggregated monthly costs per user | -| **Cost Aggregator Service** | Implemented | 30-second cache, single-user queries | -| **Quota System** | Implemented | Tier management, enforcement | -| **Admin Quota API** | Implemented | CRUD for tiers, assignments, overrides | -| **User Cost Endpoints** | Implemented | `/costs/summary`, `/costs/detailed-report` | - -### Current Table Schemas - -**UserCostSummary Table:** -``` -PK: USER# -SK: PERIOD# - -Attributes: -- totalCost, totalRequests, totalInputTokens, totalOutputTokens -- totalCacheReadTokens, totalCacheWriteTokens, cacheSavings -- modelBreakdown: { model_id: { cost, requests, tokens... } } -- lastUpdated, periodStart, periodEnd -``` - -**Key Limitation:** No way to query "all users sorted by cost" without a table scan. - ---- - -## Performance Challenge - -### The Problem - -Querying "top 100 users by cost this month" requires: - -1. **With current schema:** Table scan of all user records (O(n) - 10,000+ items) -2. **At scale:** 10,000 users × ~1KB per record = 10MB scan -3. **Performance:** 5-10 seconds, expensive, doesn't scale - -### DynamoDB Anti-Patterns to Avoid - -| Anti-Pattern | Why It's Bad | Our Solution | -|--------------|--------------|--------------| -| Table scan | O(n), slow, expensive | GSI with sorted partition | -| Filter expressions | Scans first, filters after | Query on sort key | -| Large result sets | Memory/network overhead | Pre-aggregated rollups | -| Single hot partition | Throughput limits | Time-bucketed partitions | - ---- - -## Solution Architecture - -### Strategy: Pre-Aggregated Rollups + Sorted GSIs - -We introduce two new data structures: - -1. **PeriodCostIndex GSI** - Enables "top N users by cost for period" -2. **SystemCostRollup Table** - Pre-aggregated system-wide metrics - -### Architecture Diagram - -``` - ┌─────────────────────────────┐ - │ Admin Dashboard API │ - └─────────────┬───────────────┘ - │ - ┌──────────────────────────────┼──────────────────────────────┐ - │ │ │ - ▼ ▼ ▼ - ┌────────────────────┐ ┌────────────────────┐ ┌────────────────────┐ - │ PeriodCostIndex │ │ SystemCostRollup │ │ UserCostSummary │ - │ (GSI) │ │ (Table) │ │ (existing) │ - └────────────────────┘ └────────────────────┘ └────────────────────┘ - │ │ │ - │ │ │ - ▼ ▼ ▼ - ┌────────────────────┐ ┌────────────────────┐ ┌────────────────────┐ - │ Top N users by │ │ System totals: │ │ Individual user │ - │ cost (sorted) │ │ - Total cost │ │ cost details │ - │ │ │ - Total users │ │ │ - │ O(1) query │ │ - Model breakdown │ │ O(1) query │ - └────────────────────┘ └────────────────────┘ └────────────────────┘ -``` - ---- - -## New Infrastructure Requirements - -### 1. PeriodCostIndex (GSI on UserCostSummary) - -**Purpose:** Query top users by cost for a given period - -**GSI Schema:** -``` -GSI Name: PeriodCostIndex -PK: PERIOD# (all users in this period) -SK: COST# (sorted by cost descending) - -Projected Attributes: userId, totalCost, totalRequests, lastUpdated -``` - -**Key Design:** -- **Sort key format:** `COST#<15-digit-zero-padded>` -- Example: $125.50 → `COST#000000000012550` (cents, 15 digits) -- **Descending sort:** Use `ScanIndexForward=False` -- **Limit support:** `Limit=100` for top 100 - -**Query Patterns:** -```python -# Top 100 users by cost this month -response = table.query( - IndexName="PeriodCostIndex", - KeyConditionExpression="GSI2PK = :period", - ExpressionAttributeValues={":period": "PERIOD#2025-01"}, - ScanIndexForward=False, # Descending (highest cost first) - Limit=100 -) - -# Users with cost > $50 this month -response = table.query( - IndexName="PeriodCostIndex", - KeyConditionExpression="GSI2PK = :period AND GSI2SK >= :min_cost", - ExpressionAttributeValues={ - ":period": "PERIOD#2025-01", - ":min_cost": "COST#000000000005000" # $50.00 in cents - }, - ScanIndexForward=False -) -``` - -### 2. SystemCostRollup Table - -**Purpose:** Pre-aggregated system-wide metrics (no per-user queries needed) - -**Schema:** -``` -Table: SystemCostRollup - -PK: ROLLUP# (DAILY, MONTHLY, MODEL, TIER) -SK: (date, model_id, tier_id) - -Attributes (vary by type): -- totalCost, totalRequests, totalUsers -- totalInputTokens, totalOutputTokens -- totalCacheSavings -- modelBreakdown (for period rollups) -- lastUpdated -``` - -**Item Types:** - -```python -# Daily rollup -{ - "PK": "ROLLUP#DAILY", - "SK": "2025-01-15", - "totalCost": Decimal("1250.50"), - "totalRequests": 45000, - "activeUsers": 850, - "newUsers": 12, - "totalInputTokens": 50000000, - "totalOutputTokens": 25000000, - "totalCacheSavings": Decimal("125.00"), - "lastUpdated": "2025-01-15T23:59:59Z" -} - -# Monthly rollup -{ - "PK": "ROLLUP#MONTHLY", - "SK": "2025-01", - "totalCost": Decimal("15250.75"), - "totalRequests": 450000, - "activeUsers": 2500, - "totalUsers": 5000, # All users with any historical activity - "modelBreakdown": { - "claude_sonnet_4": {"cost": 10000, "requests": 300000}, - "claude_opus_4": {"cost": 5000, "requests": 50000} - }, - "topModels": ["claude_sonnet_4", "claude_opus_4", "claude_haiku"], - "lastUpdated": "2025-01-31T23:59:59Z" -} - -# Per-model rollup (for model analytics) -{ - "PK": "ROLLUP#MODEL", - "SK": "2025-01#claude_sonnet_4", - "totalCost": Decimal("10000.00"), - "totalRequests": 300000, - "uniqueUsers": 2000, - "avgCostPerRequest": Decimal("0.033"), - "totalInputTokens": 30000000, - "totalOutputTokens": 15000000, - "lastUpdated": "2025-01-31T23:59:59Z" -} - -# Per-tier rollup (for quota tier analytics) -{ - "PK": "ROLLUP#TIER", - "SK": "2025-01#basic", - "tierId": "basic", - "tierName": "Basic", - "totalCost": Decimal("5000.00"), - "totalUsers": 3000, - "usersAtLimit": 150, - "usersWarned": 500, - "avgUtilization": Decimal("0.45"), # 45% of quota used on average - "lastUpdated": "2025-01-31T23:59:59Z" -} -``` - -### 3. Update Trigger for Rollups - -**When a user's cost is updated:** -1. Update `UserCostSummary` (existing behavior) -2. Update `PeriodCostIndex` GSI attributes (automatic with GSI) -3. Update `SystemCostRollup` (async, can be slightly delayed) - -**Implementation Options:** - -| Option | Pros | Cons | -|--------|------|------| -| **A) Synchronous update** | Always consistent | Adds latency to every request | -| **B) DynamoDB Streams + Lambda** | Decoupled, scalable | Additional infrastructure | -| **C) Async task (in-process)** | Simple, no extra infra | Slight delay in rollup accuracy | -| **D) Scheduled batch job** | Very simple | Stale data between runs | - -**Recommendation:** Option C (Async in-process) for Phase 1, Option B for Phase 2. - -```python -# In stream_coordinator.py after storing message metadata -async def _update_system_rollups( - self, - user_id: str, - cost: float, - usage: Dict[str, int], - model_id: str, - timestamp: str -): - """Update system-wide rollups asynchronously""" - # Fire and forget - don't block the response - asyncio.create_task( - self._do_rollup_update(user_id, cost, usage, model_id, timestamp) - ) -``` - ---- - -## Data Models - -### Backend Models - -**File:** `backend/src/apis/app_api/admin/costs/models.py` - -```python -from pydantic import BaseModel, Field, ConfigDict -from typing import Optional, List, Dict -from decimal import Decimal - - -class TopUserCost(BaseModel): - """User cost summary for admin dashboard""" - model_config = ConfigDict(populate_by_name=True) - - user_id: str = Field(..., alias="userId") - total_cost: float = Field(..., alias="totalCost") - total_requests: int = Field(..., alias="totalRequests") - last_updated: str = Field(..., alias="lastUpdated") - - # Optional enrichment - email: Optional[str] = None - tier_name: Optional[str] = Field(None, alias="tierName") - quota_limit: Optional[float] = Field(None, alias="quotaLimit") - quota_percentage: Optional[float] = Field(None, alias="quotaPercentage") - - -class SystemCostSummary(BaseModel): - """System-wide cost summary""" - model_config = ConfigDict(populate_by_name=True) - - period: str # "2025-01" or "2025-01-15" - period_type: str = Field(..., alias="periodType") # "daily" or "monthly" - - total_cost: float = Field(..., alias="totalCost") - total_requests: int = Field(..., alias="totalRequests") - active_users: int = Field(..., alias="activeUsers") - - total_input_tokens: int = Field(..., alias="totalInputTokens") - total_output_tokens: int = Field(..., alias="totalOutputTokens") - total_cache_savings: float = Field(..., alias="totalCacheSavings") - - model_breakdown: Optional[Dict[str, Dict]] = Field(None, alias="modelBreakdown") - last_updated: str = Field(..., alias="lastUpdated") - - -class ModelUsageSummary(BaseModel): - """Per-model usage summary""" - model_config = ConfigDict(populate_by_name=True) - - model_id: str = Field(..., alias="modelId") - model_name: str = Field(..., alias="modelName") - provider: str - - total_cost: float = Field(..., alias="totalCost") - total_requests: int = Field(..., alias="totalRequests") - unique_users: int = Field(..., alias="uniqueUsers") - avg_cost_per_request: float = Field(..., alias="avgCostPerRequest") - - total_input_tokens: int = Field(..., alias="totalInputTokens") - total_output_tokens: int = Field(..., alias="totalOutputTokens") - - -class TierUsageSummary(BaseModel): - """Per-tier usage summary""" - model_config = ConfigDict(populate_by_name=True) - - tier_id: str = Field(..., alias="tierId") - tier_name: str = Field(..., alias="tierName") - - total_cost: float = Field(..., alias="totalCost") - total_users: int = Field(..., alias="totalUsers") - users_at_limit: int = Field(..., alias="usersAtLimit") - users_warned: int = Field(..., alias="usersWarned") - avg_utilization: float = Field(..., alias="avgUtilization") - - -class CostTrend(BaseModel): - """Cost trend data point""" - model_config = ConfigDict(populate_by_name=True) - - date: str - total_cost: float = Field(..., alias="totalCost") - total_requests: int = Field(..., alias="totalRequests") - active_users: int = Field(..., alias="activeUsers") - - -class AdminCostDashboard(BaseModel): - """Complete admin cost dashboard response""" - model_config = ConfigDict(populate_by_name=True) - - # Current period summary - current_period: SystemCostSummary = Field(..., alias="currentPeriod") - - # Top users (configurable limit) - top_users: List[TopUserCost] = Field(..., alias="topUsers") - - # Model breakdown - model_usage: List[ModelUsageSummary] = Field(..., alias="modelUsage") - - # Tier breakdown (if quota system enabled) - tier_usage: Optional[List[TierUsageSummary]] = Field(None, alias="tierUsage") - - # Historical trends - daily_trends: Optional[List[CostTrend]] = Field(None, alias="dailyTrends") -``` - ---- - -## API Design - -### Admin Cost Endpoints - -**File:** `backend/src/apis/app_api/admin/costs/routes.py` - -```python -from fastapi import APIRouter, Depends, Query, HTTPException -from typing import Optional, List -from datetime import datetime - -from apis.shared.auth.dependencies import get_current_user, require_admin -from apis.shared.auth.models import User -from .models import ( - TopUserCost, SystemCostSummary, ModelUsageSummary, - TierUsageSummary, AdminCostDashboard, CostTrend -) -from .service import AdminCostService - -router = APIRouter(prefix="/admin/costs", tags=["admin-costs"]) - - -@router.get("/dashboard", response_model=AdminCostDashboard) -async def get_cost_dashboard( - period: Optional[str] = Query( - None, - description="Period (YYYY-MM), defaults to current month" - ), - top_users_limit: int = Query( - 100, - ge=1, - le=1000, - alias="topUsersLimit", - description="Number of top users to return" - ), - include_trends: bool = Query( - True, - alias="includeTrends", - description="Include daily trends for the period" - ), - current_user: User = Depends(require_admin) -): - """ - Get comprehensive admin cost dashboard - - Returns: - - System-wide cost summary for the period - - Top N users by cost (sorted descending) - - Model usage breakdown - - Tier usage breakdown (if quota system enabled) - - Daily trends (optional) - - Performance: <500ms for 10,000+ users (no table scans) - """ - service = AdminCostService() - return await service.get_dashboard( - period=period, - top_users_limit=top_users_limit, - include_trends=include_trends - ) - - -@router.get("/top-users", response_model=List[TopUserCost]) -async def get_top_users( - period: Optional[str] = Query(None, description="Period (YYYY-MM)"), - limit: int = Query(100, ge=1, le=1000), - min_cost: Optional[float] = Query( - None, - alias="minCost", - description="Minimum cost threshold" - ), - tier_id: Optional[str] = Query( - None, - alias="tierId", - description="Filter by quota tier" - ), - current_user: User = Depends(require_admin) -): - """ - Get top users by cost for a period - - Supports: - - Pagination via limit - - Minimum cost threshold - - Filter by quota tier - - Performance: <200ms via GSI query - """ - service = AdminCostService() - return await service.get_top_users( - period=period, - limit=limit, - min_cost=min_cost, - tier_id=tier_id - ) - - -@router.get("/system-summary", response_model=SystemCostSummary) -async def get_system_summary( - period: Optional[str] = Query(None, description="Period (YYYY-MM or YYYY-MM-DD)"), - period_type: str = Query("monthly", enum=["daily", "monthly"]), - current_user: User = Depends(require_admin) -): - """ - Get system-wide cost summary - - Uses pre-aggregated rollups for <50ms response. - """ - service = AdminCostService() - return await service.get_system_summary( - period=period, - period_type=period_type - ) - - -@router.get("/by-model", response_model=List[ModelUsageSummary]) -async def get_usage_by_model( - period: Optional[str] = Query(None, description="Period (YYYY-MM)"), - current_user: User = Depends(require_admin) -): - """ - Get cost breakdown by model - - Returns all models with usage in the period, sorted by cost descending. - """ - service = AdminCostService() - return await service.get_usage_by_model(period=period) - - -@router.get("/by-tier", response_model=List[TierUsageSummary]) -async def get_usage_by_tier( - period: Optional[str] = Query(None, description="Period (YYYY-MM)"), - current_user: User = Depends(require_admin) -): - """ - Get cost breakdown by quota tier - - Returns usage statistics per tier, including users at limit. - """ - service = AdminCostService() - return await service.get_usage_by_tier(period=period) - - -@router.get("/trends", response_model=List[CostTrend]) -async def get_cost_trends( - start_date: str = Query(..., alias="startDate", description="Start date (YYYY-MM-DD)"), - end_date: str = Query(..., alias="endDate", description="End date (YYYY-MM-DD)"), - current_user: User = Depends(require_admin) -): - """ - Get daily cost trends for a date range - - Returns daily aggregates for charting. - Max range: 90 days. - """ - service = AdminCostService() - return await service.get_trends( - start_date=start_date, - end_date=end_date - ) - - -@router.get("/export", response_class=StreamingResponse) -async def export_cost_data( - period: Optional[str] = Query(None, description="Period (YYYY-MM)"), - format: str = Query("csv", enum=["csv", "json"]), - current_user: User = Depends(require_admin) -): - """ - Export cost data for a period - - Returns all user costs for the period as CSV or JSON. - Uses streaming to handle large datasets efficiently. - """ - service = AdminCostService() - return await service.export_data(period=period, format=format) -``` - ---- - -## Frontend Design - -### Dashboard Components - -#### 1. Main Dashboard Page - -**File:** `frontend/ai.client/src/app/admin/costs/admin-costs.page.ts` - -```typescript -import { Component, ChangeDetectionStrategy, inject, signal, computed, OnInit } from '@angular/core'; -import { CommonModule } from '@angular/common'; -import { FormsModule } from '@angular/forms'; -import { AdminCostService } from './services/admin-cost.service'; -import { TopUsersTableComponent } from './components/top-users-table.component'; -import { CostTrendsChartComponent } from './components/cost-trends-chart.component'; -import { ModelBreakdownComponent } from './components/model-breakdown.component'; -import { TierBreakdownComponent } from './components/tier-breakdown.component'; -import { SystemSummaryCardComponent } from './components/system-summary-card.component'; -import { PeriodSelectorComponent } from './components/period-selector.component'; - -@Component({ - selector: 'app-admin-costs', - changeDetection: ChangeDetectionStrategy.OnPush, - imports: [ - CommonModule, - FormsModule, - TopUsersTableComponent, - CostTrendsChartComponent, - ModelBreakdownComponent, - TierBreakdownComponent, - SystemSummaryCardComponent, - PeriodSelectorComponent - ], - template: ` -
- -
-

- Cost Analytics Dashboard -

- -
- - - @if (loading()) { -
-
-
- } @else if (error()) { -
-

{{ error() }}

-
- } @else { - -
- - - - -
- - -
- - -
- - - - - - @if (dashboard()?.tierUsage?.length) { - - } - } -
- ` -}) -export class AdminCostsPage implements OnInit { - private costService = inject(AdminCostService); - - // State - selectedPeriod = signal(this.getCurrentPeriod()); - dashboard = signal(null); - loading = signal(true); - loadingMore = signal(false); - error = signal(null); - - // Computed trends (compare to previous period) - costTrend = computed(() => this.calculateTrend('cost')); - requestsTrend = computed(() => this.calculateTrend('requests')); - usersTrend = computed(() => this.calculateTrend('users')); - - ngOnInit() { - this.loadDashboard(); - } - - async loadDashboard() { - this.loading.set(true); - this.error.set(null); - - try { - const data = await this.costService.getDashboard({ - period: this.selectedPeriod(), - topUsersLimit: 100, - includeTrends: true - }); - this.dashboard.set(data); - } catch (err) { - this.error.set('Failed to load dashboard data'); - console.error(err); - } finally { - this.loading.set(false); - } - } - - onPeriodChange(period: string) { - this.selectedPeriod.set(period); - this.loadDashboard(); - } - - async onLoadMore() { - // Load more users via pagination - this.loadingMore.set(true); - // Implementation details... - this.loadingMore.set(false); - } - - onUserClick(userId: string) { - // Navigate to user detail view - } - - formatCurrency(value: number | undefined): string { - return value !== undefined - ? new Intl.NumberFormat('en-US', { style: 'currency', currency: 'USD' }).format(value) - : '$0.00'; - } - - formatNumber(value: number | undefined): string { - return value !== undefined - ? new Intl.NumberFormat('en-US').format(value) - : '0'; - } - - private getCurrentPeriod(): string { - const now = new Date(); - return `${now.getFullYear()}-${String(now.getMonth() + 1).padStart(2, '0')}`; - } - - private calculateTrend(metric: string): number | null { - // Compare current period to previous period - // Return percentage change - return null; // Placeholder - } -} -``` - -#### 2. Top Users Table Component - -```typescript -@Component({ - selector: 'app-top-users-table', - changeDetection: ChangeDetectionStrategy.OnPush, - template: ` -
-
-

- Top Users by Cost -

-
- -
- - - - - - - - - - - - - - @for (user of users(); track user.userId; let i = $index) { - - - - - - - - - - } - -
- Rank - - User - - Total Cost - - Requests - - Avg/Request - - Tier - - Quota Used -
- {{ i + 1 }} - -
-
- - {{ user.email?.charAt(0)?.toUpperCase() || user.userId.charAt(0).toUpperCase() }} - -
-
-

- {{ user.email || user.userId }} -

- @if (user.email) { -

- {{ user.userId }} -

- } -
-
- 		- {{ formatCurrency(user.totalCost) }} - - {{ formatNumber(user.totalRequests) }} - - {{ formatCurrency(user.totalCost / (user.totalRequests || 1)) }} - - @if (user.tierName) { - - {{ user.tierName }} - - } - - @if (user.quotaPercentage !== null && user.quotaPercentage !== undefined) { -
-
-
-
- - {{ user.quotaPercentage | number:'1.0-0' }}% - -
- } -
-
- - @if (loading()) { -
- Loading more... -
- } @else { -
- -
- } -
- ` -}) -export class TopUsersTableComponent { - users = input.required(); - loading = input(false); - - userClick = output(); - loadMore = output(); - - Math = Math; - - formatCurrency(value: number): string { - return new Intl.NumberFormat('en-US', { - style: 'currency', - currency: 'USD' - }).format(value); - } - - formatNumber(value: number): string { - return new Intl.NumberFormat('en-US').format(value); - } - - getQuotaBarClass(percentage: number): string { - if (percentage >= 100) return 'bg-red-500'; - if (percentage >= 80) return 'bg-yellow-500'; - return 'bg-green-500'; - } -} -``` - -### Dashboard Metrics Beyond Cost - -The dashboard supports multiple metric types: - -| Metric | Description | Use Case | -|--------|-------------|----------| -| **Total Cost** | Sum of all user costs | Budget tracking | -| **Total Requests** | Count of inference requests | Usage volume | -| **Active Users** | Users with activity in period | Adoption tracking | -| **Cache Savings** | Money saved via caching | Optimization ROI | -| **Avg Cost/Request** | Cost efficiency metric | Model selection | -| **Tokens Processed** | Input + output tokens | Capacity planning | -| **Quota Utilization** | % of quota used per tier | Tier pricing | -| **Users at Limit** | Users blocked by quota | Upsell opportunities | - ---- - -## Implementation Plan - -### Phase 1: Infrastructure (Week 1) - -1. **Add PeriodCostIndex GSI to UserCostSummary table** - - Create GSI with PK=`PERIOD#`, SK=`COST#` - - Update cost aggregator to maintain GSI attributes - - Test query performance - -2. **Create SystemCostRollup table** - - Define table schema via CDK - - Implement rollup update logic - - Add async update to stream coordinator - -3. **Backfill existing data** (if needed) - - Script to populate GSI attributes for existing records - - Script to generate initial rollup data - -### Phase 2: Backend API (Week 2) - -1. **Create admin costs service** - - Implement `get_dashboard()` method - - Implement `get_top_users()` with GSI query - - Implement `get_system_summary()` from rollups - - Implement `get_usage_by_model()` and `get_usage_by_tier()` - -2. **Create admin costs routes** - - Add endpoints to FastAPI router - - Add admin authentication middleware - - Add request validation - -3. **Testing** - - Unit tests for service methods - - Integration tests for API endpoints - - Performance tests (verify <500ms at scale) - -### Phase 3: Frontend (Week 3) - -1. **Create dashboard page** - - Main page layout with period selector - - Summary cards with trend indicators - - Loading and error states - -2. **Create visualization components** - - Top users table with sorting - - Cost trends chart (line chart) - - Model breakdown (pie/bar chart) - - Tier usage table - -3. **Create admin cost service** - - HTTP service for API calls - - Response caching for performance - - Error handling - -### Phase 4: Polish & Optimization (Week 4) - -1. **Performance tuning** - - Verify no table scans in CloudWatch - - Optimize GSI projections if needed - - Add server-side caching for rollups - -2. **Export functionality** - - CSV export for compliance/reporting - - Streaming response for large datasets - -3. **Documentation** - - API documentation - - Admin user guide - - Runbook for common operations - ---- - -## Appendix: DynamoDB Schema Updates - -### GSI Addition: PeriodCostIndex - -**CDK Update for UserCostSummary table:** - -```typescript -// In cdk/lib/stacks/cost-tracking-stack.ts - -const userCostSummaryTable = new dynamodb.Table(this, 'UserCostSummary', { - tableName: `UserCostSummary-${stage}`, - partitionKey: { name: 'PK', type: dynamodb.AttributeType.STRING }, - sortKey: { name: 'SK', type: dynamodb.AttributeType.STRING }, - billingMode: dynamodb.BillingMode.PAY_PER_REQUEST, - pointInTimeRecovery: true, -}); - -// Add GSI for period-based queries (top users by cost) -userCostSummaryTable.addGlobalSecondaryIndex({ - indexName: 'PeriodCostIndex', - partitionKey: { name: 'GSI2PK', type: dynamodb.AttributeType.STRING }, - sortKey: { name: 'GSI2SK', type: dynamodb.AttributeType.STRING }, - projectionType: dynamodb.ProjectionType.INCLUDE, - nonKeyAttributes: ['userId', 'totalCost', 'totalRequests', 'lastUpdated'], -}); -``` - -### Update to DynamoDB Storage - -**Update `dynamodb_storage.py` to maintain GSI attributes:** - -```python -async def update_user_cost_summary( - self, - user_id: str, - period: str, - cost_delta: float, - usage_delta: Dict[str, int], - timestamp: str, - model_id: Optional[str] = None, - model_name: Optional[str] = None, - cache_savings_delta: float = 0.0 -) -> None: - """Update pre-aggregated cost summary with GSI attributes""" - - # First, get current total to calculate new GSI sort key - current = await self.get_user_cost_summary(user_id, period) - current_cost = float(current.get("totalCost", 0)) if current else 0 - new_total_cost = current_cost + cost_delta - - # Format cost for GSI sort key (zero-padded cents for proper sorting) - # Convert to cents and pad to 15 digits for costs up to $999,999,999,999.99 - cost_cents = int(new_total_cost * 100) - gsi2_sk = f"COST#{cost_cents:015d}" - - # Update with GSI attributes - update_expression = """ - ADD totalCost :cost, - totalRequests :one, - totalInputTokens :input, - totalOutputTokens :output, - totalCacheReadTokens :cacheRead, - totalCacheWriteTokens :cacheWrite, - cacheSavings :savings - SET lastUpdated = :now, - periodStart = if_not_exists(periodStart, :periodStart), - periodEnd = if_not_exists(periodEnd, :periodEnd), - userId = :userId, - GSI2PK = :gsi2pk, - GSI2SK = :gsi2sk - """ - - expression_values = { - ":cost": Decimal(str(cost_delta)), - ":one": 1, - ":input": usage_delta.get("inputTokens", 0), - ":output": usage_delta.get("outputTokens", 0), - ":cacheRead": usage_delta.get("cacheReadInputTokens", 0), - ":cacheWrite": usage_delta.get("cacheWriteInputTokens", 0), - ":savings": Decimal(str(cache_savings_delta)), - ":now": timestamp, - ":periodStart": f"{period}-01T00:00:00Z", - ":periodEnd": f"{period}-31T23:59:59Z", - ":userId": user_id, - ":gsi2pk": f"PERIOD#{period}", - ":gsi2sk": gsi2_sk - } - - self.cost_summary_table.update_item( - Key={ - "PK": f"USER#{user_id}", - "SK": f"PERIOD#{period}" - }, - UpdateExpression=update_expression, - ExpressionAttributeValues=expression_values - ) -``` - -### SystemCostRollup Table - -**CDK definition:** - -```typescript -const systemCostRollupTable = new dynamodb.Table(this, 'SystemCostRollup', { - tableName: `SystemCostRollup-${stage}`, - partitionKey: { name: 'PK', type: dynamodb.AttributeType.STRING }, - sortKey: { name: 'SK', type: dynamodb.AttributeType.STRING }, - billingMode: dynamodb.BillingMode.PAY_PER_REQUEST, - pointInTimeRecovery: true, -}); - -// GSI for time-range queries on rollups -systemCostRollupTable.addGlobalSecondaryIndex({ - indexName: 'DateRangeIndex', - partitionKey: { name: 'GSI1PK', type: dynamodb.AttributeType.STRING }, - sortKey: { name: 'GSI1SK', type: dynamodb.AttributeType.STRING }, - projectionType: dynamodb.ProjectionType.ALL, -}); -``` - ---- - -## Success Criteria - -| Criterion | Target | Measurement | -|-----------|--------|-------------| -| Dashboard load time | <500ms | P95 latency | -| Top N users query | <200ms | P95 latency | -| Table scans | 0 | CloudWatch ConsumedReadCapacity | -| User scale | 10,000+ | Load test | -| Cache hit rate | >80% | Custom metric | -| Rollup freshness | <1 minute | LastUpdated delta | - ---- - -## Conclusion - -This specification provides a scalable, performant admin cost dashboard that: - -1. **Avoids table scans** via GSI-based queries and pre-aggregated rollups -2. **Scales to 10,000+ users** with consistent sub-second response times -3. **Provides rich analytics** beyond just cost (requests, users, models, tiers) -4. **Builds on existing infrastructure** (UserCostSummary table, quota system) -5. **Follows established patterns** (Pydantic models, FastAPI routes, Angular components) - -The phased implementation approach allows incremental delivery while maintaining the performance and scalability requirements from day one. diff --git a/docs/ARCHITECTURE_DEBT.md b/docs/ARCHITECTURE_DEBT.md deleted file mode 100644 index 6b228ce5..00000000 --- a/docs/ARCHITECTURE_DEBT.md +++ /dev/null @@ -1,152 +0,0 @@ -# Architecture Debt & Technical Issues - -This document tracks architectural issues, technical debt, and areas requiring refactoring. - -## Cross-Service Dependencies - -### Issue: Inference API depends on App API modules - -**Status**: 🔴 Active Issue -**Severity**: High -**Date Identified**: 2025-01-28 - -#### Problem - -The Inference API (AgentCore Runtime) has direct Python imports from the App API codebase: - -```python -# In backend/src/apis/inference_api/chat/service.py -from apis.app_api.sessions.models import SessionMetadata -from apis.app_api.sessions.services.metadata import store_session_metadata - -# In backend/src/apis/inference_api/chat/routes.py -from apis.app_api.admin.services.managed_models import list_managed_models -from apis.app_api.files.file_resolver import get_file_resolver -from apis.app_api.assistants.services.assistant_service import get_assistant_with_access_check -from apis.app_api.assistants.services.rag_service import search_assistant_knowledgebase_with_formatting -from apis.app_api.sessions.services.metadata import get_session_metadata, store_session_metadata -from apis.app_api.sessions.models import SessionMetadata, SessionPreferences -from apis.app_api.sessions.services.messages import get_messages -``` - -#### Impact - -1. **Tight Coupling**: Inference API cannot be deployed independently of App API code -2. **Log Namespace Pollution**: App API logs (`apis.app_api.*`) appear in AgentCore Runtime CloudWatch logs -3. **Deployment Complexity**: Docker image for inference API must include app_api code -4. **Maintenance Burden**: Changes to app_api modules can break inference API -5. **Testing Difficulty**: Cannot test inference API in isolation - -#### Root Cause - -The services were initially developed as a monolith and later split into separate deployment targets (ECS for App API, AgentCore Runtime for Inference API) without properly separating the codebases. - -#### Affected Modules - -| App API Module | Used By Inference API For | -|----------------|---------------------------| -| `apis.app_api.sessions.models` | Session metadata models | -| `apis.app_api.sessions.services.metadata` | Storing/retrieving session metadata | -| `apis.app_api.sessions.services.messages` | Retrieving conversation history | -| `apis.app_api.admin.services.managed_models` | Looking up model capabilities (e.g., `supports_caching`) | -| `apis.app_api.files.file_resolver` | Resolving file references in chat | -| `apis.app_api.assistants.services.assistant_service` | Assistant access control | -| `apis.app_api.assistants.services.rag_service` | RAG knowledge base search | - -#### Recommended Solutions - -**Option 1: Move Shared Code to `apis.shared` (Preferred)** -- Move session models and services to `apis.shared.sessions` -- Move file resolver to `apis.shared.files` -- Both services import from shared module -- Pros: Clean separation, single source of truth -- Cons: Requires refactoring both services - -**Option 2: Service-to-Service API Calls** -- Inference API calls App API via HTTP for managed models, file resolution, etc. -- Pros: True service independence -- Cons: Network latency, requires authentication between services - -**Option 3: Pass Data Through Request Payload** -- Client includes necessary metadata in inference API requests -- Pros: No cross-service dependencies -- Cons: Larger payloads, client complexity - -**Option 4: Duplicate Code** -- Copy necessary modules to inference API -- Pros: Quick fix, complete independence -- Cons: Code duplication, maintenance nightmare - -#### Action Items - -- [ ] Decide on refactoring approach (recommend Option 1) -- [ ] Create `apis.shared.sessions` module -- [ ] Create `apis.shared.files` module -- [ ] Refactor inference API to use shared modules -- [ ] Refactor app API to use shared modules -- [ ] Update Docker builds to ensure shared modules are included -- [ ] Add integration tests to verify separation -- [ ] Document new architecture in README - -#### Workarounds - -**Current State**: Both services share the same codebase in Docker images, so the cross-imports work but create the issues listed above. - -**Temporary Mitigation**: None - this requires architectural refactoring to properly resolve. - ---- - -## Other Known Issues - -### Issue: DynamoDB GSI Permissions Not Granted by `grantReadWriteData()` - -**Status**: ✅ Fixed -**Date Fixed**: 2025-01-28 - -#### Problem -CDK's `table.grantReadWriteData()` method doesn't automatically grant permissions to query Global Secondary Indexes (GSIs). This caused `AccessDeniedException` errors when querying the `OwnerStatusIndex` GSI on the assistants table. - -#### Solution -Added explicit IAM policy statements to grant `dynamodb:Query` and `dynamodb:Scan` permissions on `table-arn/index/*` pattern. - -```typescript -taskDefinition.taskRole.addToPrincipalPolicy( - new iam.PolicyStatement({ - effect: iam.Effect.ALLOW, - actions: ['dynamodb:Query', 'dynamodb:Scan'], - resources: [`${assistantsTable.tableArn}/index/*`], - }) -); -``` - ---- - -### Issue: Silent Failures in Assistant Service - -**Status**: ✅ Fixed -**Date Fixed**: 2025-01-28 - -#### Problem -The `_list_user_assistants_cloud()` function caught all exceptions and returned empty arrays `([], None)` instead of propagating errors. This caused API endpoints to return `200 OK` with empty results even when DynamoDB operations failed. - -#### Solution -Modified exception handlers to re-raise exceptions so they propagate to the endpoint, which returns appropriate HTTP error codes (500). - -```python -except ClientError as e: - error_code = e.response.get('Error', {}).get('Code', 'Unknown') - error_message = e.response.get('Error', {}).get('Message', str(e)) - logger.error(f"Failed to list user assistants from DynamoDB: {error_code} - {error_message}") - raise Exception(f"DynamoDB error ({error_code}): {error_message}") from e -``` - ---- - -## Contributing - -When you identify new architectural issues or technical debt: - -1. Add a new section to this document -2. Include: Status, Severity, Date, Problem, Impact, Root Cause, Solutions, Action Items -3. Update status as work progresses -4. Move to "Fixed" section when resolved diff --git a/docs/ASSISTANT_EMAIL_SHARING_PLAN.md b/docs/ASSISTANT_EMAIL_SHARING_PLAN.md deleted file mode 100644 index 2ae57e2c..00000000 --- a/docs/ASSISTANT_EMAIL_SHARING_PLAN.md +++ /dev/null @@ -1,275 +0,0 @@ -# Assistant Email Sharing Implementation Plan - -## Overview - -This plan implements email-based sharing for assistants with `SHARED` visibility. The feature allows assistant owners to share assistants with specific users by email address, even before those users have logged into the system for the first time. This is possible because OIDC authentication guarantees that all users will have an email claim. - -## Context: Assistant Visibility Model - -The system has three visibility levels: - -| Visibility | Access Control | Share Records | Use Case | -|------------|----------------|---------------|----------| -| **PRIVATE** | Owner only | None needed | Personal assistants | -| **PUBLIC** | Anyone with link | None needed (no tracking) | Classroom assistants with non-sensitive content (syllabus, grading guidelines, examples) | -| **SHARED** | Owner + explicitly shared emails | Yes - owner can see list | Proprietary/sensitive content requiring controlled access | - -**Key Design Decision:** Share records and tracking only apply to `SHARED` visibility assistants. `PUBLIC` assistants are open access with no tracking, suitable for trusted organizational environments (state/local government, universities). - -## Data Model - -### DynamoDB Single-Table Design - -Add share records to the existing assistants DynamoDB table: - -**Primary Key Structure:** -``` -PK: AST#{assistant_id} -SK: SHARE#{email} -``` - -**New Global Secondary Index (SharedWithIndex):** -``` -GSI3_PK: SHARE#{email} -GSI3_SK: AST#{assistant_id} -``` - -### Access Patterns - -1. **"Who is this assistant shared with?"** - - Query: `PK = AST#{assistant_id}` with `begins_with(SK, 'SHARE#')` - - Returns all share records for a specific assistant - -2. **"What assistants are shared with me?"** - - Query GSI3: `GSI3_PK = SHARE#{user_email}` - - Returns all assistants shared with a specific email - -3. **"Does user X have access to this assistant?"** - - Check: `is_owner OR visibility=PUBLIC OR share_record_exists(assistant_id, user_email)` - -## Backend Implementation - -### 1. Models (`backend/src/apis/app_api/assistants/models.py`) - -Add new Pydantic models: - -```python -class ShareAssistantRequest(BaseModel): - emails: List[str] = Field(..., min_length=1, description="Email addresses to share with") - -class UnshareAssistantRequest(BaseModel): - emails: List[str] = Field(..., min_length=1, description="Email addresses to remove") - -class AssistantSharesResponse(BaseModel): - assistant_id: str - shared_with: List[str] # List of emails -``` - -### 2. Service Layer (`backend/src/apis/app_api/assistants/services/assistant_service.py`) - -Add new functions: - -- `share_assistant(assistant_id: str, owner_id: str, emails: List[str])` - Create share records for specified emails -- `unshare_assistant(assistant_id: str, owner_id: str, emails: List[str])` - Delete share records -- `list_assistant_shares(assistant_id: str, owner_id: str) -> List[str]` - Get all emails this assistant is shared with -- `list_shared_with_user(user_email: str) -> List[Assistant]` - Get all assistants shared with this email -- `check_share_access(assistant_id: str, user_email: str) -> bool` - Check if share record exists - -**Modify Access Control:** - -Update `get_assistant_with_access_check()` to enforce share records for `SHARED` visibility: - -```python -if assistant.visibility == 'SHARED': - if assistant.owner_id != user_id: - # Check if share record exists for user's email - has_share = await check_share_access(assistant_id, user_email) - if not has_share: - return None # Access denied -``` - -### 3. User Search Endpoint - -**Location:** `backend/src/apis/app_api/users/routes.py` (new file) or add to existing user routes - -Create a new user search endpoint for the sharing modal: - -- `GET /users/search` - Search for users by email or name (partial match) - - Query parameter: `q` (search query string, required) - - Query parameter: `limit` (max results, default 20, max 50) - - Returns: List of users matching the search (email, name, userId) - - Access: Available to all authenticated users (not admin-only) - - Purpose: Allow users to search for existing users in the system to share with - -**Implementation Details:** - -**Service Layer** (`backend/src/apis/app_api/users/service.py` or add to existing): -- `search_users(query: str, limit: int = 20) -> List[UserSearchResult]` -- Search logic: - - Query EmailIndex for email prefix matches (case-insensitive) - - Query StatusLoginIndex for active users and filter by name contains - - Combine and deduplicate results - - Limit results and return top matches -- Only return users with status='active' - -**Response Model:** -```python -class UserSearchResult(BaseModel): - user_id: str - email: str - name: str - -class UserSearchResponse(BaseModel): - users: List[UserSearchResult] -``` - -**Implementation Notes:** -- Search should match against email (prefix/contains) and name (contains) -- Results should be limited and paginated -- Only return active users -- Return minimal user info: email, name, userId (for display purposes) -- Use debouncing on frontend to avoid excessive API calls - -### 4. API Routes (`backend/src/apis/app_api/assistants/routes.py`) - -Add new endpoints: - -- `POST /assistants/{id}/shares` - Share assistant with emails (owner only, requires ownership verification) -- `DELETE /assistants/{id}/shares` - Remove shares from emails (owner only) -- `GET /assistants/{id}/shares` - List all emails this assistant is shared with (owner only) - -**Modify existing endpoint:** - -- `GET /assistants` - Optionally include assistants shared with the current user (query GSI3 by user email) - -### 5. Infrastructure (`infrastructure/lib/app-api-stack.ts`) - -Add new Global Secondary Index to the assistants DynamoDB table: - -```typescript -assistantsTable.addGlobalSecondaryIndex({ - indexName: 'SharedWithIndex', - partitionKey: { name: 'GSI3_PK', type: AttributeType.STRING }, - sortKey: { name: 'GSI3_SK', type: AttributeType.STRING }, - projectionType: ProjectionType.ALL, -}); -``` - -## Frontend Implementation - -### 1. Models - -**Assistant Models** (`frontend/ai.client/src/app/assistants/models/assistant.model.ts`): - -Add TypeScript interfaces: - -```typescript -export interface ShareAssistantRequest { - emails: string[]; -} - -export interface UnshareAssistantRequest { - emails: string[]; -} - -export interface AssistantSharesResponse { - assistantId: string; - sharedWith: string[]; -} -``` - -**User Search Models** (create new or add to existing user models): - -```typescript -export interface UserSearchResult { - userId: string; - email: string; - name: string; -} - -export interface UserSearchResponse { - users: UserSearchResult[]; -} -``` - -### 2. Services - -**Assistant Service** (`frontend/ai.client/src/app/assistants/services/assistant.service.ts`): - -Add methods: -- `shareAssistant(id: string, emails: string[]): Promise` -- `unshareAssistant(id: string, emails: string[]): Promise` -- `getAssistantShares(id: string): Promise` - -**User Service** (create new or add to existing user service): - -Add method: -- `searchUsers(query: string, limit?: number): Promise` - Search for users by email/name - -### 3. Share Dialog Component (`frontend/ai.client/src/app/assistants/components/share-assistant-dialog.component.ts`) - -Update/create share dialog with **two modes**: - -**Mode 1: Search for Existing Users** -- Search input field that queries the user search endpoint as user types (debounced) -- Display search results with user name and email -- Allow selecting users from search results -- Selected users are added to the share list - -**Mode 2: Add Emails Directly** -- Fallback option: "Add email addresses manually" -- Text input for email addresses (comma-delimited) -- Parse and validate email format -- Add to share list - -**Common Features:** -- Display list of currently shared emails/users -- Remove button for each shared email/user -- Email format validation -- Only show/share for assistants with `SHARED` visibility -- Show user name if available, email if not found in system - -### 4. Assistant List (`frontend/ai.client/src/app/assistants/components/assistant-list.component.ts`) - -Update assistant list to: - -- Show assistants shared with the current user (query via new service method) -- Display "Shared with me" indicator or separate section -- Include shared assistants in the main list view - -## Implementation Tasks - -1. **Backend Models** - Add ShareAssistantRequest, UnshareAssistantRequest, AssistantSharesResponse models -2. **Backend User Search** - Create user search endpoint (GET /users/search) with partial matching on email/name -3. **Backend Service** - Implement share/unshare/list functions and modify access check logic -4. **Backend Routes** - Add POST/DELETE/GET /assistants/{id}/shares endpoints -5. **CDK GSI** - Add SharedWithIndex GSI to assistants table in CDK infrastructure -6. **Frontend Models** - Add TypeScript interfaces for share requests/responses and user search results -7. **Frontend User Service** - Add searchUsers method to user service -8. **Frontend Assistant Service** - Add share/unshare/getShares methods to assistant service -9. **Frontend Dialog** - Update share dialog with user search and manual email input (two modes) -10. **Frontend List** - Update assistant list to show shared-with-me assistants - -## Migration Considerations - -**Important:** Existing assistants with `SHARED` visibility will have no share records after deployment. This means: - -- Only the owner can access them (safe default) -- Owners must explicitly add shares after deployment to grant access -- This is intentional - it prevents accidental exposure of previously "SHARED" assistants that may have been misconfigured - -## Security Considerations - -1. **Email Normalization:** All emails should be lowercased before storage/querying (consistent with existing user email handling) -2. **Ownership Verification:** All share endpoints must verify the requester is the assistant owner -3. **Access Control:** Share records are only checked for `SHARED` visibility assistants -4. **Email Validation:** Frontend should validate email format before sending to backend - -## Testing Considerations - -1. Test sharing with emails that don't have user accounts yet -2. Test that shared assistants appear in user's list after they log in -3. Test that unsharing removes access immediately -4. Test that PUBLIC assistants don't require share records -5. Test that PRIVATE assistants can't be shared -6. Test email case insensitivity (lowercase normalization) diff --git a/docs/AWS_PROFILE_GUIDE.md b/docs/AWS_PROFILE_GUIDE.md deleted file mode 100644 index b31f5e08..00000000 --- a/docs/AWS_PROFILE_GUIDE.md +++ /dev/null @@ -1,375 +0,0 @@ -# AWS Profile Configuration Guide - -This guide explains how to configure AWS credentials for the AgentCore Public Stack using AWS profiles. - -## Overview - -The application supports multiple ways to provide AWS credentials with automatic fallback: - -1. **AWS Profile** (recommended for local development) -2. **Environment Variables** -3. **Default AWS Credentials** - -## AWS Profile Priority Order - -The scripts check for AWS credentials in this order: - -1. `AWS_PROFILE` **environment variable** (highest priority) -2. `AWS_PROFILE` in **backend/src/.env** file -3. **"default"** profile fallback -4. AWS SDK default credential chain (env vars, credentials file, IAM role) - -## Setup Methods - -### Method 1: Using AWS Profiles (Recommended) - -#### Step 1: Configure AWS CLI Profiles - -```bash -# Configure your default profile -aws configure -# Enter: Access Key ID, Secret Access Key, Region, Output format - -# Or configure a named profile -aws configure --profile dev -aws configure --profile production -``` - -This creates/updates `~/.aws/credentials`: - -```ini -[default] -aws_access_key_id = AKIA... -aws_secret_access_key = ... - -[dev] -aws_access_key_id = AKIA... -aws_secret_access_key = ... - -[production] -aws_access_key_id = AKIA... -aws_secret_access_key = ... -``` - -#### Step 2: Configure in .env File - -Edit `backend/src/.env`: - -```bash -AWS_REGION=us-west-2 -AWS_PROFILE=dev # Use the 'dev' profile -``` - -#### Step 3: Run Setup and Start - -```bash -./setup.sh # Validates AWS profile during setup -./start.sh # Uses configured profile -``` - -### Method 2: Override with Environment Variable - -You can override the `.env` file setting: - -```bash -# Use a specific profile for this session -AWS_PROFILE=production ./setup.sh -AWS_PROFILE=production ./start.sh - -# Or export it for multiple commands -export AWS_PROFILE=production -./setup.sh -./start.sh -``` - -### Method 3: Use Default Credentials - -Set `AWS_PROFILE=default` or omit it entirely: - -```bash -# In backend/src/.env -AWS_PROFILE=default - -# Or don't set AWS_PROFILE at all - will use default -``` - -This falls back to the AWS SDK credential chain: -1. `AWS_ACCESS_KEY_ID` and `AWS_SECRET_ACCESS_KEY` environment variables -2. `~/.aws/credentials` default profile -3. IAM role (when running on AWS EC2/ECS/Lambda) - -## What the Scripts Do - -### setup.sh - -During setup, the script: - -1. ✅ Checks if AWS CLI is installed -2. ✅ Reads `AWS_PROFILE` from environment or `.env` file -3. ✅ Validates the profile exists using `aws configure list` -4. ✅ Warns if profile is missing (but continues) -5. ✅ Displays which profile/credentials will be used - -Example output: - -``` -🔍 Checking AWS configuration... -✅ AWS CLI found -Using AWS profile: dev -✅ AWS profile 'dev' is configured -``` - -### start.sh - -When starting services, the script: - -1. ✅ Loads environment variables from `.env` -2. ✅ Configures AWS profile (env var > .env > default) -3. ✅ Validates credentials with `aws sts get-caller-identity` -4. ✅ Displays AWS account ID if credentials are valid -5. ✅ Exports `AWS_PROFILE` for child processes (APIs) - -Example output: - -``` -🔍 Configuring AWS credentials... -Using AWS profile: dev -✅ AWS profile 'dev' is valid -✅ AWS credentials valid (Account: 123456789012) -``` - -## Common Scenarios - -### Scenario 1: Multiple AWS Accounts (Work/Personal) - -```bash -# Configure profiles -aws configure --profile work -aws configure --profile personal - -# Use in .env -AWS_PROFILE=work - -# Or switch on the fly -AWS_PROFILE=personal ./start.sh -``` - -### Scenario 2: Team Development (Shared Profile Names) - -Your team agrees on profile names: - -```bash -# Everyone configures the same profile names -aws configure --profile agentcore-dev -aws configure --profile agentcore-staging -aws configure --profile agentcore-prod - -# In .env (committed to repo) -AWS_PROFILE=agentcore-dev - -# Each developer has their own credentials under the same profile name -``` - -### Scenario 3: SSO (AWS IAM Identity Center) - -```bash -# Configure SSO profile -aws configure sso --profile my-sso-profile - -# Login before using -aws sso login --profile my-sso-profile - -# Use in .env -AWS_PROFILE=my-sso-profile - -# The scripts will use SSO credentials -./start.sh -``` - -### Scenario 4: CI/CD (No Profile) - -In GitHub Actions, AWS CodeBuild, etc.: - -```bash -# Don't set AWS_PROFILE (use IAM role or environment variables) -# The AWS SDK will automatically use: -# - GitHub OIDC credentials -# - CodeBuild service role -# - ECS task role -# - etc. - -# In .env or leave unset -AWS_PROFILE=default -# Or omit the line entirely -``` - -### Scenario 5: Docker/Container Development - -```bash -# Mount AWS credentials into container -docker run -v ~/.aws:/root/.aws:ro \ - -e AWS_PROFILE=dev \ - myapp - -# Or use environment variables -docker run \ - -e AWS_ACCESS_KEY_ID=... \ - -e AWS_SECRET_ACCESS_KEY=... \ - -e AWS_REGION=us-west-2 \ - myapp -``` - -## Troubleshooting - -### Profile Not Found - -``` -⚠️ AWS profile 'dev' not found, will use default credentials -``` - -**Solution:** -```bash -# List configured profiles -aws configure list-profiles - -# Configure the missing profile -aws configure --profile dev -``` - -### Could Not Verify Credentials - -``` -⚠️ Could not verify AWS credentials - Some features may not work. Run 'aws configure' to set up. -``` - -**Solutions:** - -1. **Check profile exists:** - ```bash - aws configure list --profile your-profile - ``` - -2. **Test credentials manually:** - ```bash - aws sts get-caller-identity --profile your-profile - ``` - -3. **For SSO, login first:** - ```bash - aws sso login --profile your-sso-profile - ``` - -4. **Check ~/.aws/credentials file:** - ```bash - cat ~/.aws/credentials - ``` - -### AWS CLI Not Installed - -``` -⚠️ AWS CLI not found - some features may require AWS credentials - Install from: https://aws.amazon.com/cli/ -``` - -**Solution:** - -Install AWS CLI: -- **macOS:** `brew install awscli` -- **Linux:** Download from [AWS CLI install guide](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html) -- **Windows:** Download MSI installer from AWS - -### SSO Session Expired - -``` -Error loading SSO Token: Token for ... does not exist -``` - -**Solution:** -```bash -aws sso login --profile your-sso-profile -./start.sh -``` - -## Security Best Practices - -1. **Never commit credentials to git** - - ✅ `.env` is in `.gitignore` - - ✅ Use `.env.example` as template - - ❌ Don't put real credentials in `.env.example` - -2. **Use IAM roles when possible** - - For EC2/ECS/Lambda: Use instance/task roles - - For local development: Use profiles - -3. **Rotate credentials regularly** - ```bash - aws iam create-access-key - aws configure --profile your-profile - # Update credentials, then: - aws iam delete-access-key --access-key-id OLD_KEY - ``` - -4. **Use least-privilege IAM policies** - - Only grant permissions needed for AgentCore/Bedrock - - Example services: Bedrock, S3, DynamoDB, CloudWatch - -5. **Enable MFA for production profiles** - ```bash - # Add MFA device in IAM console - # Use temporary credentials with MFA - aws sts get-session-token --serial-number arn:aws:iam::123456789012:mfa/user --token-code 123456 - ``` - -## Environment Variables Reference - -| Variable | Source | Priority | Default | -|----------|--------|----------|---------| -| `AWS_PROFILE` | CLI export | 1 (highest) | - | -| `AWS_PROFILE` | .env file | 2 | `default` | -| `AWS_ACCESS_KEY_ID` | Environment | 3 | - | -| `AWS_SECRET_ACCESS_KEY` | Environment | 3 | - | -| `AWS_SESSION_TOKEN` | Environment | 3 | - | -| `AWS_REGION` | .env file | - | `us-west-2` | - -## Quick Reference Commands - -```bash -# List all configured profiles -aws configure list-profiles - -# View current profile configuration -aws configure list - -# Test credentials -aws sts get-caller-identity - -# See which profile is active -echo $AWS_PROFILE - -# Use specific profile for one command -AWS_PROFILE=dev aws s3 ls - -# Set profile for session -export AWS_PROFILE=dev - -# Unset profile (use default) -unset AWS_PROFILE - -# SSO login -aws sso login --profile my-sso-profile - -# View credentials file -cat ~/.aws/credentials - -# View config file -cat ~/.aws/config -``` - -## Additional Resources - -- [AWS CLI Configuration Guide](https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-files.html) -- [Named Profiles](https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-profiles.html) -- [AWS IAM Identity Center (SSO)](https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-sso.html) -- [Environment Variables](https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-envvars.html) -- [Credential Provider Chain](https://docs.aws.amazon.com/sdkref/latest/guide/standardized-credentials.html) diff --git a/docs/CONFIG_INVENTORY.md b/docs/CONFIG_INVENTORY.md deleted file mode 100644 index b481abab..00000000 --- a/docs/CONFIG_INVENTORY.md +++ /dev/null @@ -1,158 +0,0 @@ -# Configuration Variable Inventory - -Complete inventory of all configuration variables across the AgentCore Public Stack, organized by layer. - -## 1. Backend Environment Variables (`backend/src/.env.example`) - -| Variable | Required | Default | Consuming Module(s) | -|----------|----------|---------|---------------------| -| AWS_REGION | Yes | `us-west-2` | All AWS SDK calls | -| AWS_PROFILE | No | `default` | AWS credential chain | -| AGENTCORE_MEMORY_TYPE | No | `file` | `agents/main_agent/session/` | -| AGENTCORE_MEMORY_ID | Conditional | — | `agents/main_agent/session/` (required when MEMORY_TYPE=dynamodb) | -| AGENTCORE_MEMORY_RELEVANCE_SCORE | No | `0.7` | `agents/main_agent/session/session_factory.py` | -| AGENTCORE_MEMORY_TOP_K | No | `10` | `agents/main_agent/session/session_factory.py` | -| AGENTCORE_MEMORY_COMPACTION_ENABLED | No | `false` | `agents/main_agent/session/` | -| AGENTCORE_MEMORY_COMPACTION_TOKEN_THRESHOLD | No | `100000` | `agents/main_agent/session/` | -| AGENTCORE_MEMORY_COMPACTION_PROTECTED_TURNS | No | `2` | `agents/main_agent/session/` | -| AGENTCORE_MEMORY_COMPACTION_MAX_TOOL_CONTENT_LENGTH | No | `500` | `agents/main_agent/session/` | -| AGENTCORE_GATEWAY_MCP_ENABLED | No | `true` | `agents/main_agent/integrations/external_mcp_client.py` | -| AGENTCORE_CODE_INTERPRETER_ID | No | — | `agents/builtin_tools/code_interpreter_diagram_tool.py` | -| ENABLE_QUOTA_ENFORCEMENT | No | `true` | `agents/main_agent/quota/` | -| UPLOAD_DIR | No | `uploads` | `apis/inference_api/` (local-dev-only) | -| OUTPUT_DIR | No | `output` | `apis/inference_api/` (local-dev-only) | -| GENERATED_IMAGES_DIR | No | `generated_images` | `apis/inference_api/` (local-dev-only) | -| DYNAMODB_MANAGED_MODELS_TABLE_NAME | No | — | `apis/app_api/` model management | -| DYNAMODB_SESSIONS_METADATA_TABLE_NAME | No | — | `apis/app_api/messages/`, cost tracking | -| DYNAMODB_COST_SUMMARY_TABLE_NAME | No | — | `apis/app_api/costs/` | -| DYNAMODB_SYSTEM_ROLLUP_TABLE_NAME | No | — | `apis/app_api/costs/` admin dashboard | -| DYNAMODB_OIDC_STATE_TABLE_NAME | No | — | `apis/shared/auth/` | -| DYNAMODB_QUOTA_TABLE | No | — | `agents/main_agent/quota/` | -| DYNAMODB_QUOTA_EVENTS_TABLE | No | — | `agents/main_agent/quota/` | -| DYNAMODB_USERS_TABLE_NAME | No | — | `apis/app_api/users/` | -| DYNAMODB_APP_ROLES_TABLE_NAME | No | — | `apis/shared/rbac/` | -| DYNAMODB_USER_FILES_TABLE_NAME | No | — | `apis/app_api/files/` | -| DYNAMODB_AUTH_PROVIDERS_TABLE_NAME | No | — | `apis/shared/auth/` | -| DYNAMODB_ASSISTANTS_TABLE_NAME | No | — | `apis/app_api/assistants/` | -| DYNAMODB_USER_SETTINGS_TABLE_NAME | No | — | `apis/shared/user_settings/` | -| DYNAMODB_OAUTH_PROVIDERS_TABLE_NAME | No | — | `apis/app_api/` OAuth management | -| DYNAMODB_OAUTH_USER_TOKENS_TABLE_NAME | No | — | `apis/app_api/` OAuth tokens | -| AUTH_PROVIDER_SECRETS_ARN | No | — | `apis/shared/auth/` | -| OAUTH_TOKEN_ENCRYPTION_KEY_ARN | No | — | `apis/app_api/` OAuth encryption | -| OAUTH_CLIENT_SECRETS_ARN | No | — | `apis/app_api/` OAuth secrets | -| ADMIN_JWT_ROLES | No | `["DotNetDevelopers"]` | `apis/shared/rbac/` | -| FRONTEND_URL | No | `http://localhost:4200` | CORS configuration | -| CORS_ORIGINS | No | localhost list | `apis/app_api/main.py`, `apis/inference_api/main.py` | -| S3_USER_FILES_BUCKET_NAME | No | — | `apis/app_api/files/` | -| FILE_UPLOAD_MAX_SIZE_BYTES | No | `4194304` | `apis/app_api/files/` | -| FILE_UPLOAD_MAX_FILES_PER_MESSAGE | No | `5` | `apis/app_api/files/` | -| FILE_UPLOAD_USER_QUOTA_BYTES | No | `1073741824` | `apis/app_api/files/` | -| S3_ASSISTANTS_DOCUMENTS_BUCKET_NAME | No | — | `apis/app_api/assistants/` | -| S3_ASSISTANTS_VECTOR_STORE_BUCKET_NAME | No | — | `apis/app_api/assistants/` | -| S3_ASSISTANTS_VECTOR_STORE_INDEX_NAME | No | — | `apis/app_api/assistants/` | -| APP_ROLE_USER_CACHE_TTL_MINUTES | No | `5` | `apis/shared/rbac/` | -| APP_ROLE_ROLE_CACHE_TTL_MINUTES | No | `10` | `apis/shared/rbac/` | -| APP_ROLE_MAPPING_CACHE_TTL_MINUTES | No | `10` | `apis/shared/rbac/` | -| OPENAI_API_KEY | No | — | `agents/main_agent/core/model_config.py` | -| GOOGLE_GEMINI_API_KEY | No | — | `agents/main_agent/core/model_config.py` | - -## 2. CDK Context Keys (`infrastructure/cdk.context.json` → `config.ts`) - -| Context Key | Env Var Override | Type | Default | Config Field | -|-------------|-----------------|------|---------|-------------| -| `production` | `CDK_PRODUCTION` | boolean | `true` | `config.production` | -| `retainDataOnDelete` | `CDK_RETAIN_DATA_ON_DELETE` | boolean | `false` | `config.retainDataOnDelete` | -| `projectPrefix` | `CDK_PROJECT_PREFIX` | string | `agentcore` | `config.projectPrefix` | -| `awsAccount` | `CDK_AWS_ACCOUNT` | string | — (required) | `config.awsAccount` | -| `awsRegion` | `CDK_AWS_REGION` | string | `us-west-2` | `config.awsRegion` | -| `vpcCidr` | — | string | `10.0.0.0/16` | `config.vpcCidr` | -| `corsOrigins` | `CDK_CORS_ORIGINS` | string | `http://localhost:4200,http://localhost:8000` | `config.corsOrigins` | -| `domainName` | `CDK_DOMAIN_NAME` | string | `""` | `config.domainName` | -| `infrastructureHostedZoneDomain` | `CDK_HOSTED_ZONE_DOMAIN` | string | `""` | `config.infrastructureHostedZoneDomain` | -| `albSubdomain` | `CDK_ALB_SUBDOMAIN` | string | `""` | `config.albSubdomain` | -| `certificateArn` | `CDK_CERTIFICATE_ARN` | string | `""` | `config.certificateArn` | -| `imageTag` | — | string | `""` | `config.appApi.imageTag`, `config.inferenceApi.imageTag` | -| `frontend.certificateArn` | `CDK_FRONTEND_CERTIFICATE_ARN` | string | `""` | `config.frontend.certificateArn` | -| `frontend.enabled` | `CDK_FRONTEND_ENABLED` | boolean | `true` | `config.frontend.enabled` | -| `frontend.bucketName` | `CDK_FRONTEND_BUCKET_NAME` | string | `""` | `config.frontend.bucketName` | -| `frontend.cloudFrontPriceClass` | `CDK_FRONTEND_CLOUDFRONT_PRICE_CLASS` | string | `PriceClass_100` | `config.frontend.cloudFrontPriceClass` | -| `appApi.enabled` | `CDK_APP_API_ENABLED` | boolean | `true` | `config.appApi.enabled` | -| `appApi.cpu` | `CDK_APP_API_CPU` | number | `512` | `config.appApi.cpu` | -| `appApi.memory` | `CDK_APP_API_MEMORY` | number | `1024` | `config.appApi.memory` | -| `appApi.desiredCount` | `CDK_APP_API_DESIRED_COUNT` | number | `1` | `config.appApi.desiredCount` | -| `appApi.maxCapacity` | `CDK_APP_API_MAX_CAPACITY` | number | `10` | `config.appApi.maxCapacity` | -| `inferenceApi.enabled` | `CDK_INFERENCE_API_ENABLED` | boolean | `true` | `config.inferenceApi.enabled` | -| `inferenceApi.cpu` | `CDK_INFERENCE_API_CPU` | number | `1024` | `config.inferenceApi.cpu` | -| `inferenceApi.memory` | `CDK_INFERENCE_API_MEMORY` | number | `2048` | `config.inferenceApi.memory` | -| `inferenceApi.desiredCount` | `CDK_INFERENCE_API_DESIRED_COUNT` | number | `1` | `config.inferenceApi.desiredCount` | -| `inferenceApi.maxCapacity` | `CDK_INFERENCE_API_MAX_CAPACITY` | number | `5` | `config.inferenceApi.maxCapacity` | -| `inferenceApi.logLevel` | `ENV_INFERENCE_API_LOG_LEVEL` | string | `INFO` | `config.inferenceApi.logLevel` | -| `inferenceApi.corsOrigins` | `ENV_INFERENCE_API_CORS_ORIGINS` | string | `""` | `config.inferenceApi.corsOrigins` | -| `gateway.enabled` | `CDK_GATEWAY_ENABLED` | boolean | `true` | `config.gateway.enabled` | -| `gateway.apiType` | `CDK_GATEWAY_API_TYPE` | `REST`\|`HTTP` | `HTTP` | `config.gateway.apiType` | -| `gateway.throttleRateLimit` | `CDK_GATEWAY_THROTTLE_RATE_LIMIT` | number | `10000` | `config.gateway.throttleRateLimit` | -| `gateway.throttleBurstLimit` | `CDK_GATEWAY_THROTTLE_BURST_LIMIT` | number | `5000` | `config.gateway.throttleBurstLimit` | -| `gateway.enableWaf` | `CDK_GATEWAY_ENABLE_WAF` | boolean | `false` | `config.gateway.enableWaf` | -| `gateway.logLevel` | `CDK_GATEWAY_LOG_LEVEL` | string | `INFO` | `config.gateway.logLevel` | -| `fileUpload.enabled` | `CDK_FILE_UPLOAD_ENABLED` | boolean | `true` | `config.fileUpload.enabled` | -| `fileUpload.maxFileSizeBytes` | `CDK_FILE_UPLOAD_MAX_FILE_SIZE` | number | `4194304` | `config.fileUpload.maxFileSizeBytes` | -| `fileUpload.maxFilesPerMessage` | `CDK_FILE_UPLOAD_MAX_FILES_PER_MESSAGE` | number | `5` | `config.fileUpload.maxFilesPerMessage` | -| `fileUpload.userQuotaBytes` | `CDK_FILE_UPLOAD_USER_QUOTA` | number | `1073741824` | `config.fileUpload.userQuotaBytes` | -| `fileUpload.retentionDays` | `CDK_FILE_UPLOAD_RETENTION_DAYS` | number | `365` | `config.fileUpload.retentionDays` | -| `fileUpload.corsOrigins` | `CDK_FILE_UPLOAD_CORS_ORIGINS` | string | (falls back to `corsOrigins`) | `config.fileUpload.corsOrigins` | -| `assistants.enabled` | `CDK_ASSISTANTS_ENABLED` | boolean | `true` | `config.assistants.enabled` | -| `assistants.corsOrigins` | `CDK_ASSISTANTS_CORS_ORIGINS` | string | (falls back to `corsOrigins`) | `config.assistants.corsOrigins` | -| `ragIngestion.enabled` | `CDK_RAG_ENABLED` | boolean | `true` | `config.ragIngestion.enabled` | -| `ragIngestion.corsOrigins` | `CDK_RAG_CORS_ORIGINS` | string | (falls back to `corsOrigins`) | `config.ragIngestion.corsOrigins` | -| `ragIngestion.lambdaMemorySize` | `CDK_RAG_LAMBDA_MEMORY` | number | `10240` | `config.ragIngestion.lambdaMemorySize` | -| `ragIngestion.lambdaTimeout` | `CDK_RAG_LAMBDA_TIMEOUT` | number | `900` | `config.ragIngestion.lambdaTimeout` | -| `ragIngestion.embeddingModel` | `CDK_RAG_EMBEDDING_MODEL` | string | `amazon.titan-embed-text-v2` | `config.ragIngestion.embeddingModel` | -| `ragIngestion.vectorDimension` | `CDK_RAG_VECTOR_DIMENSION` | number | `1024` | `config.ragIngestion.vectorDimension` | -| `ragIngestion.vectorDistanceMetric` | `CDK_RAG_DISTANCE_METRIC` | string | `cosine` | `config.ragIngestion.vectorDistanceMetric` | -| `tags` | — | object | `{ ManagedBy: "CDK" }` | `config.tags` (+ `Project` injected dynamically) | - -## 3. Frontend Environment (`frontend/ai.client/src/environments/`) - -| Field | File | Default | Consuming Service | -|-------|------|---------|-------------------| -| `production` | `environment.ts` | `false` | `ConfigService` (fallback only) | -| `appApiUrl` | `environment.ts` | `http://localhost:8000` | `ConfigService` (fallback only) | -| `production` | `environment.production.ts` | `true` | `ConfigService` (fallback only) | -| `appApiUrl` | `environment.production.ts` | `""` | `ConfigService` (fallback only) | - -In production, the frontend loads runtime configuration from `/config.json` (generated by CDK FrontendStack). The `environment.ts` values are fallbacks only. - -### Runtime Config (`/config.json`) - -| Field | Source | Consuming Service | -|-------|--------|-------------------| -| `appApiUrl` | SSM `/{projectPrefix}/app-api/url` | `ConfigService.appApiUrl()` | -| `environment` | CDK `production` flag | `ConfigService.environment()` | - -## 4. Configuration Precedence - -``` -Environment Variable → CDK Context (cdk.context.json) → Not Set (validation error or undefined) -``` - -- Required fields (`projectPrefix`, `awsAccount`, `awsRegion`) throw errors if missing from both sources. -- Optional fields return `undefined` if not set, and stacks handle the absence gracefully. -- CORS origins cascade: section-level → top-level `corsOrigins` → empty string. -- Tags: `ManagedBy` from context, `Project` injected dynamically from `projectPrefix`. - -## 5. Removed Variables (Config Cleanup Audit) - -The following variables were removed as dead configuration: - -| Variable | Reason | -|----------|--------| -| `ENABLE_AUTHENTICATION` / `enableAuthentication` | Auth is always enabled; toggle removed | -| `inferenceApiUrl` | Frontend resolves inference endpoint dynamically at runtime | -| `enableRoute53` | Route53 derived from `domainName` presence | -| `enableGpu` | GPU support removed from inference API config | -| `enableRds` / `rdsInstanceClass` / `rdsEngine` / `rdsDatabaseName` | RDS never implemented | -| `databaseType` | Single database type (DynamoDB) | -| `uploadDir` / `outputDir` / `generatedImagesDir` (CDK) | Local-dev-only; removed from CDK config | -| `oauthCallbackUrl` (CDK InferenceApiConfig) | Derived from `domainName` in infrastructure stack | -| `apiUrl` / `frontendUrl` (CDK InferenceApiConfig) | Dead fields, never consumed by stacks | -| `entraClientId` / `entraTenantId` | Replaced by generic OIDC provider system | diff --git a/docs/QUOTA_MANAGEMENT_PHASE1_SPEC.md b/docs/QUOTA_MANAGEMENT_PHASE1_SPEC.md deleted file mode 100644 index 356ed1e4..00000000 --- a/docs/QUOTA_MANAGEMENT_PHASE1_SPEC.md +++ /dev/null @@ -1,1911 +0,0 @@ -# Quota Management System - Phase 1 Implementation Specification - -**Phase:** 1 (MVP - Core Infrastructure) -**Created:** 2025-12-17 -**Status:** Ready for Implementation - ---- - -## Table of Contents - -1. [Overview](#overview) -2. [Phase 1 Scope](#phase-1-scope) -3. [Architecture](#architecture) -4. [Database Schema](#database-schema) -5. [Backend Implementation](#backend-implementation) -6. [CDK Infrastructure](#cdk-infrastructure) -7. [Testing Strategy](#testing-strategy) -8. [Validation Criteria](#validation-criteria) - ---- - -## Overview - -### Objectives - -Implement the foundational quota management system with: -- Scalable DynamoDB schema supporting 100,000+ users -- Core quota resolution with intelligent caching -- Basic quota assignments (direct user, JWT role, default tier) -- Admin CRUD APIs for tiers and assignments -- Hard limit blocking enforcement -- CDK infrastructure for all resources - -### Success Criteria - -- ✅ All DynamoDB queries use targeted GSI queries (ZERO table scans) -- ✅ Quota resolution completes in <100ms with cache -- ✅ 90% cache hit rate reduces DynamoDB costs -- ✅ Admin APIs follow existing patterns in `backend/src/apis/app_api/admin/` -- ✅ CDK creates all tables with proper GSIs -- ✅ Hard limits block requests when exceeded -- ✅ System scales to 100,000+ users without performance degradation - ---- - -## Phase 1 Scope - -### ✅ Included in Phase 1 - -**Database:** -- DynamoDB tables: `UserQuotas`, `QuotaEvents` -- All GSIs for scalable queries -- CDK infrastructure - -**Backend:** -- Core models (Pydantic) -- Repository layer (DynamoDB access) -- QuotaResolver with cache -- QuotaChecker (hard limit enforcement) -- Admin CRUD APIs for tiers and assignments - -**Features:** -- Quota tier management -- Direct user assignments -- JWT role assignments -- Default tier fallback -- Hard limit blocking -- Basic event recording (blocks only) - -### ❌ Deferred to Phase 2 - -- Quota overrides (temporary exceptions) -- Soft limit warnings (80%, 90%) -- Email domain matching -- Event viewer UI -- Quota inspector UI -- Enhanced analytics -- Frontend implementation - ---- - -## Architecture - -### System Components (Phase 1) - -``` -┌─────────────────────────────────────────────────────────────┐ -│ Backend API │ -│ ┌──────────────────────────────────────────────────────┐ │ -│ │ Admin API Routes │ │ -│ │ /api/admin/quota/tiers/* │ │ -│ │ /api/admin/quota/assignments/* │ │ -│ └──────────────────────────────────────────────────────┘ │ -│ ┌──────────────────────────────────────────────────────┐ │ -│ │ Quota Resolution Service │ │ -│ │ - QuotaResolver (with 5min cache) │ │ -│ │ - QuotaChecker (hard limits only) │ │ -│ │ - QuotaEventRecorder (blocks only) │ │ -│ └──────────────────────────────────────────────────────┘ │ -└────────────┬────────────────────────────────────────────────┘ - │ boto3 - ▼ -┌─────────────────────────────────────────────────────────────┐ -│ DynamoDB │ -│ ┌──────────────┐ ┌──────────────┐ │ -│ │ UserQuotas │ │ QuotaEvents │ │ -│ │ Table │ │ Table │ │ -│ │ (3 GSIs) │ │ (1 GSI) │ │ -│ └──────────────┘ └──────────────┘ │ -└─────────────────────────────────────────────────────────────┘ -``` - -### Data Flow (Phase 1) - -``` -1. Admin Request → Admin API - ├─ Create/Update/Delete Tier - ├─ Create/Update/Delete Assignment - └─ QuotaAdminService → Repository → DynamoDB - -2. User Request → QuotaChecker.check_quota(user) - ├─ QuotaResolver.resolve_user_quota(user) - │ ├─ Check cache (5min TTL) - │ ├─ If miss: Query DynamoDB - │ │ ├─ Check direct user (GSI2: UserAssignmentIndex) - │ │ ├─ Check JWT roles (GSI3: RoleAssignmentIndex) - │ │ └─ Fall back to default tier - │ └─ Cache result - ├─ Get current usage from CostAggregator - ├─ Check hard limit (100% → block) - └─ Record block event if exceeded - -3. Allow/Block request -``` - ---- - -## Database Schema - -### Tables Overview - -| Table Name | Purpose | Primary Key | GSIs | Expected Size | -|------------|---------|-------------|------|---------------| -| `UserQuotas` | Tiers & assignments | PK, SK | 3 GSIs | ~10K items | -| `QuotaEvents` | Event tracking | PK, SK | 1 GSI | ~1M items/month | - -### UserQuotas Table - -**Purpose:** Single-table design for quota tiers and assignments (Phase 1: no overrides) - -**Primary Key:** -- **PK** (String): Entity type identifier -- **SK** (String): Metadata or sort key - -**Attributes:** -- All entity fields (camelCase for consistency with API) -- GSI key attributes (GSI1PK, GSI1SK, GSI2PK, etc.) - -**Capacity:** -- Billing Mode: **PAY_PER_REQUEST** (on-demand) -- Rationale: Admin operations are infrequent; read patterns favor caching - -#### Entity Types - -##### 1. Quota Tier - -```json -{ - "PK": "QUOTA_TIER#", - "SK": "METADATA", - "tierId": "premium", - "tierName": "Premium Tier", - "description": "For premium users with higher usage needs", - "monthlyCostLimit": 500.00, - "dailyCostLimit": 20.00, - "periodType": "monthly", - "actionOnLimit": "block", - "enabled": true, - "createdAt": "2025-12-17T00:00:00Z", - "updatedAt": "2025-12-17T00:00:00Z", - "createdBy": "admin123" -} -``` - -**Query Pattern:** -- Get tier by ID: `PK = "QUOTA_TIER#" AND SK = "METADATA"` -- List all tiers: Query with `begins_with(PK, "QUOTA_TIER#")` - -##### 2. Quota Assignment - -```json -{ - "PK": "ASSIGNMENT#", - "SK": "METADATA", - "GSI1PK": "ASSIGNMENT_TYPE#jwt_role", - "GSI1SK": "PRIORITY#200#", - "GSI2PK": "USER#", - "GSI2SK": "ASSIGNMENT#", - "GSI3PK": "ROLE#Faculty", - "GSI3SK": "PRIORITY#200", - "assignmentId": "abc123", - "tierId": "premium", - "assignmentType": "jwt_role", - "jwtRole": "Faculty", - "priority": 200, - "enabled": true, - "createdAt": "2025-12-17T00:00:00Z", - "updatedAt": "2025-12-17T00:00:00Z", - "createdBy": "admin123" -} -``` - -**Assignment Types (Phase 1):** -- `direct_user` - Specific user assignment -- `jwt_role` - Role-based assignment -- `default_tier` - Default for all users - -**Priority System:** -- Higher number = higher priority (evaluated first) -- Typical values: - - Direct user: 300 - - JWT role: 200 - - Default tier: 100 - -**Query Patterns:** -- Get assignment by ID: `PK = "ASSIGNMENT#" AND SK = "METADATA"` -- Get user's assignment: GSI2 query `GSI2PK = "USER#"` -- Get role assignments: GSI3 query `GSI3PK = "ROLE#"` (sorted by priority) -- List by type: GSI1 query `GSI1PK = "ASSIGNMENT_TYPE#"` - -#### Global Secondary Indexes (Phase 1) - -| GSI Name | PK | SK | Projection | Use Case | -|----------|----|----|------------|----------| -| **AssignmentTypeIndex** (GSI1) | `ASSIGNMENT_TYPE#` | `PRIORITY##` | ALL | List assignments by type, sorted by priority | -| **UserAssignmentIndex** (GSI2) | `USER#` | `ASSIGNMENT#` | ALL | Find direct user assignment (O(1) lookup) | -| **RoleAssignmentIndex** (GSI3) | `ROLE#` | `PRIORITY#` | ALL | Find role assignments, sorted by priority | - -**Important:** All GSIs use **PAY_PER_REQUEST** billing to match base table. - -### QuotaEvents Table - -**Purpose:** Track quota enforcement events (Phase 1: blocks only) - -**Primary Key:** -- **PK** (String): `USER#` -- **SK** (String): `EVENT##` - -**Attributes:** -```json -{ - "PK": "USER#test123", - "SK": "EVENT#2025-12-17T12:00:00.123Z#evt123", - "GSI5PK": "TIER#premium", - "GSI5SK": "TIMESTAMP#2025-12-17T12:00:00.123Z", - "eventId": "evt123", - "userId": "test123", - "tierId": "premium", - "eventType": "block", - "currentUsage": 505.00, - "quotaLimit": 500.00, - "percentageUsed": 101.0, - "timestamp": "2025-12-17T12:00:00.123Z", - "metadata": { - "tierName": "Premium Tier", - "sessionId": "session_xyz", - "assignmentId": "abc123" - } -} -``` - -**Event Types (Phase 1):** -- `block` - Hard limit exceeded, request blocked - -**Query Patterns:** -- Get user events: `PK = "USER#"` (sorted by timestamp DESC) -- Get recent event: `PK = "USER#" AND SK >= "EVENT#"` -- Get tier events: GSI5 query `GSI5PK = "TIER#"` - -**Global Secondary Index:** - -| GSI Name | PK | SK | Projection | Use Case | -|----------|----|----|------------|----------| -| **TierEventIndex** (GSI5) | `TIER#` | `TIMESTAMP#` | ALL | Analytics on tier usage (Phase 2) | - -**Capacity:** PAY_PER_REQUEST (high write volume, infrequent reads) - -**TTL:** Consider adding TTL attribute to auto-delete events >90 days (Phase 2 optimization) - ---- - -## Backend Implementation - -### Directory Structure - -``` -backend/src/ -├── apis/ -│ └── app_api/ -│ └── admin/ -│ └── quota/ # ← NEW: Quota admin API -│ ├── __init__.py -│ ├── routes.py # FastAPI routes -│ ├── service.py # Business logic -│ └── models.py # Request/response models -├── agentcore/ -│ └── quota/ # ← NEW: Core quota logic -│ ├── __init__.py -│ ├── models.py # Pydantic domain models -│ ├── repository.py # DynamoDB access layer -│ ├── resolver.py # QuotaResolver with cache -│ ├── checker.py # QuotaChecker (enforcement) -│ └── event_recorder.py # QuotaEventRecorder -└── middleware/ - └── quota_middleware.py # ← NEW: Request-level quota checking -``` - -### Core Models - -**File:** `backend/src/agentcore/quota/models.py` - -```python -from pydantic import BaseModel, Field, ConfigDict, field_validator -from typing import Optional, Literal, Dict, Any, List -from enum import Enum -from datetime import datetime - -class QuotaAssignmentType(str, Enum): - """How a quota is assigned to users (Phase 1)""" - DIRECT_USER = "direct_user" - JWT_ROLE = "jwt_role" - DEFAULT_TIER = "default_tier" - -class QuotaTier(BaseModel): - """A quota tier configuration""" - model_config = ConfigDict(populate_by_name=True) - - tier_id: str = Field(..., alias="tierId") - tier_name: str = Field(..., alias="tierName") - description: Optional[str] = None - - # Quota limits - monthly_cost_limit: float = Field(..., alias="monthlyCostLimit", gt=0) - daily_cost_limit: Optional[float] = Field(None, alias="dailyCostLimit", gt=0) - period_type: Literal["daily", "monthly"] = Field(default="monthly", alias="periodType") - - # Hard limit behavior (Phase 1: block only) - action_on_limit: Literal["block"] = Field( - default="block", - alias="actionOnLimit" - ) - - # Metadata - enabled: bool = Field(default=True) - created_at: str = Field(..., alias="createdAt") - updated_at: str = Field(..., alias="updatedAt") - created_by: str = Field(..., alias="createdBy") - -class QuotaAssignment(BaseModel): - """Assignment of a quota tier to users""" - model_config = ConfigDict(populate_by_name=True) - - assignment_id: str = Field(..., alias="assignmentId") - tier_id: str = Field(..., alias="tierId") - assignment_type: QuotaAssignmentType = Field(..., alias="assignmentType") - - # Assignment criteria (one populated based on type) - user_id: Optional[str] = Field(None, alias="userId") - jwt_role: Optional[str] = Field(None, alias="jwtRole") - - # Priority (higher = more specific, evaluated first) - priority: int = Field( - default=100, - description="Higher priority overrides lower", - ge=0 - ) - - # Metadata - enabled: bool = Field(default=True) - created_at: str = Field(..., alias="createdAt") - updated_at: str = Field(..., alias="updatedAt") - created_by: str = Field(..., alias="createdBy") - - @field_validator('user_id', 'jwt_role') - @classmethod - def validate_criteria_match(cls, v, info): - """Ensure criteria matches assignment type""" - assignment_type = info.data.get('assignment_type') - field_name = info.field_name - - if assignment_type == QuotaAssignmentType.DIRECT_USER and field_name == 'user_id': - if not v: - raise ValueError("user_id required for direct_user assignment") - elif assignment_type == QuotaAssignmentType.JWT_ROLE and field_name == 'jwt_role': - if not v: - raise ValueError("jwt_role required for jwt_role assignment") - - return v - -class QuotaEvent(BaseModel): - """Track quota enforcement events (Phase 1: blocks only)""" - model_config = ConfigDict(populate_by_name=True) - - event_id: str = Field(..., alias="eventId") - user_id: str = Field(..., alias="userId") - tier_id: str = Field(..., alias="tierId") - event_type: Literal["block"] = Field(..., alias="eventType") # Phase 1: blocks only - - # Context - current_usage: float = Field(..., alias="currentUsage") - quota_limit: float = Field(..., alias="quotaLimit") - percentage_used: float = Field(..., alias="percentageUsed") - - timestamp: str - metadata: Optional[Dict[str, Any]] = None - -class QuotaCheckResult(BaseModel): - """Result of quota check""" - allowed: bool - message: str - tier: Optional[QuotaTier] = None - current_usage: float = Field(default=0.0, alias="currentUsage") - quota_limit: Optional[float] = Field(None, alias="quotaLimit") - percentage_used: float = Field(default=0.0, alias="percentageUsed") - remaining: Optional[float] = None - -class ResolvedQuota(BaseModel): - """Resolved quota information for a user""" - user_id: str = Field(..., alias="userId") - tier: QuotaTier - matched_by: str = Field( - ..., - alias="matchedBy", - description="How quota was resolved (e.g., 'direct_user', 'jwt_role:Faculty')" - ) - assignment: QuotaAssignment -``` - -### Repository Layer (Partial - Key Methods) - -**File:** `backend/src/agentcore/quota/repository.py` - -```python -from typing import Optional, List -from datetime import datetime -import boto3 -from botocore.exceptions import ClientError -import logging -from .models import QuotaTier, QuotaAssignment, QuotaEvent - -logger = logging.getLogger(__name__) - -class QuotaRepository: - """DynamoDB repository for quota management (Phase 1)""" - - def __init__( - self, - table_name: str = "UserQuotas", - events_table_name: str = "QuotaEvents" - ): - self.dynamodb = boto3.resource('dynamodb') - self.table = self.dynamodb.Table(table_name) - self.events_table = self.dynamodb.Table(events_table_name) - - # ========== Quota Tiers ========== - - async def get_tier(self, tier_id: str) -> Optional[QuotaTier]: - """Get quota tier by ID (targeted query)""" - try: - response = self.table.get_item( - Key={ - "PK": f"QUOTA_TIER#{tier_id}", - "SK": "METADATA" - } - ) - - if 'Item' not in response: - return None - - item = response['Item'] - # Remove DynamoDB keys - item.pop('PK', None) - item.pop('SK', None) - - return QuotaTier(**item) - except ClientError as e: - logger.error(f"Error getting tier {tier_id}: {e}") - return None - - async def list_tiers(self, enabled_only: bool = False) -> List[QuotaTier]: - """List all quota tiers (query with begins_with)""" - try: - # Use Query on PK prefix instead of Scan - response = self.table.query( - KeyConditionExpression="begins_with(PK, :prefix)", - ExpressionAttributeValues={ - ":prefix": "QUOTA_TIER#" - } - ) - - tiers = [] - for item in response.get('Items', []): - item.pop('PK', None) - item.pop('SK', None) - tier = QuotaTier(**item) - - if enabled_only and not tier.enabled: - continue - - tiers.append(tier) - - return tiers - except ClientError as e: - logger.error(f"Error listing tiers: {e}") - return [] - - # ========== Quota Assignments ========== - - async def query_user_assignment(self, user_id: str) -> Optional[QuotaAssignment]: - """ - Query direct user assignment using GSI2 (UserAssignmentIndex). - O(1) lookup - no scan. - """ - try: - response = self.table.query( - IndexName="UserAssignmentIndex", - KeyConditionExpression="GSI2PK = :pk", - ExpressionAttributeValues={ - ":pk": f"USER#{user_id}" - }, - Limit=1 - ) - - items = response.get('Items', []) - if not items: - return None - - item = items[0] - # Clean GSI keys - for key in ['PK', 'SK', 'GSI1PK', 'GSI1SK', 'GSI2PK', 'GSI2SK', 'GSI3PK', 'GSI3SK']: - item.pop(key, None) - - return QuotaAssignment(**item) - except ClientError as e: - logger.error(f"Error querying user assignment for {user_id}: {e}") - return None - - async def query_role_assignments(self, role: str) -> List[QuotaAssignment]: - """ - Query role-based assignments using GSI3 (RoleAssignmentIndex). - Returns assignments sorted by priority (descending). - O(log n) lookup - no scan. - """ - try: - response = self.table.query( - IndexName="RoleAssignmentIndex", - KeyConditionExpression="GSI3PK = :pk", - ExpressionAttributeValues={ - ":pk": f"ROLE#{role}" - }, - ScanIndexForward=False # Descending order (highest priority first) - ) - - assignments = [] - for item in response.get('Items', []): - for key in ['PK', 'SK', 'GSI1PK', 'GSI1SK', 'GSI2PK', 'GSI2SK', 'GSI3PK', 'GSI3SK']: - item.pop(key, None) - assignments.append(QuotaAssignment(**item)) - - return assignments - except ClientError as e: - logger.error(f"Error querying role assignments for {role}: {e}") - return [] - - async def list_assignments_by_type( - self, - assignment_type: str, - enabled_only: bool = False - ) -> List[QuotaAssignment]: - """ - List assignments by type using GSI1 (AssignmentTypeIndex). - Sorted by priority (descending). O(log n) - no scan. - """ - try: - response = self.table.query( - IndexName="AssignmentTypeIndex", - KeyConditionExpression="GSI1PK = :pk", - ExpressionAttributeValues={ - ":pk": f"ASSIGNMENT_TYPE#{assignment_type}" - }, - ScanIndexForward=False # Highest priority first - ) - - assignments = [] - for item in response.get('Items', []): - for key in ['PK', 'SK', 'GSI1PK', 'GSI1SK', 'GSI2PK', 'GSI2SK', 'GSI3PK', 'GSI3SK']: - item.pop(key, None) - - assignment = QuotaAssignment(**item) - - if enabled_only and not assignment.enabled: - continue - - assignments.append(assignment) - - return assignments - except ClientError as e: - logger.error(f"Error listing assignments for type {assignment_type}: {e}") - return [] - - # ========== Quota Events ========== - - async def record_event(self, event: QuotaEvent) -> QuotaEvent: - """Record a quota event (Phase 1: blocks only)""" - item = { - "PK": f"USER#{event.user_id}", - "SK": f"EVENT#{event.timestamp}#{event.event_id}", - "GSI5PK": f"TIER#{event.tier_id}", - "GSI5SK": f"TIMESTAMP#{event.timestamp}", - **event.model_dump(by_alias=True, exclude_none=True) - } - - try: - self.events_table.put_item(Item=item) - return event - except ClientError as e: - logger.error(f"Error recording event: {e}") - raise - - async def get_user_events( - self, - user_id: str, - limit: int = 50, - start_time: Optional[str] = None - ) -> List[QuotaEvent]: - """Get quota events for a user (targeted query by PK)""" - try: - key_condition = "PK = :pk" - expr_values = {":pk": f"USER#{user_id}"} - - if start_time: - key_condition += " AND SK >= :start" - expr_values[":start"] = f"EVENT#{start_time}" - - response = self.events_table.query( - KeyConditionExpression=key_condition, - ExpressionAttributeValues=expr_values, - ScanIndexForward=False, # Latest first - Limit=limit - ) - - events = [] - for item in response.get('Items', []): - for key in ['PK', 'SK', 'GSI5PK', 'GSI5SK']: - item.pop(key, None) - events.append(QuotaEvent(**item)) - - return events - except ClientError as e: - logger.error(f"Error getting events for user {user_id}: {e}") - return [] -``` - -**Note:** See full repository implementation in `docs/QUOTA_MANAGEMENT_PHASE1_FULL.md` for all CRUD methods. - -### Quota Resolver (with Cache) - -**File:** `backend/src/agentcore/quota/resolver.py` - -```python -from typing import Optional, Dict, Tuple -from datetime import datetime, timedelta -import logging -from apis.shared.auth.models import User -from .models import QuotaTier, QuotaAssignment, ResolvedQuota -from .repository import QuotaRepository - -logger = logging.getLogger(__name__) - -class QuotaResolver: - """ - Resolves user quota tier with intelligent caching. - - Phase 1: Supports direct user, JWT role, and default tier assignments. - Cache TTL: 5 minutes (reduces DynamoDB calls by ~90%) - """ - - def __init__( - self, - repository: QuotaRepository, - cache_ttl_seconds: int = 300 # 5 minutes - ): - self.repository = repository - self.cache_ttl = cache_ttl_seconds - self._cache: Dict[str, Tuple[Optional[ResolvedQuota], datetime]] = {} - - async def resolve_user_quota(self, user: User) -> Optional[ResolvedQuota]: - """ - Resolve quota tier for a user using priority-based matching with caching. - - Priority order (highest to lowest): - 1. Direct user assignment (priority ~300) - 2. JWT role assignment (priority ~200) - 3. Default tier (priority ~100) - """ - cache_key = self._get_cache_key(user) - - # Check cache - if cache_key in self._cache: - resolved, cached_at = self._cache[cache_key] - if datetime.utcnow() - cached_at < timedelta(seconds=self.cache_ttl): - logger.debug(f"Cache hit for user {user.user_id}") - return resolved - - # Cache miss - resolve from database - logger.debug(f"Cache miss for user {user.user_id}, resolving...") - resolved = await self._resolve_from_db(user) - - # Cache result - self._cache[cache_key] = (resolved, datetime.utcnow()) - - return resolved - - async def _resolve_from_db(self, user: User) -> Optional[ResolvedQuota]: - """ - Resolve quota from database using targeted GSI queries. - ZERO table scans. - """ - - # 1. Check for direct user assignment (GSI2: UserAssignmentIndex) - user_assignment = await self.repository.query_user_assignment(user.user_id) - if user_assignment and user_assignment.enabled: - tier = await self.repository.get_tier(user_assignment.tier_id) - if tier and tier.enabled: - return ResolvedQuota( - user_id=user.user_id, - tier=tier, - matched_by="direct_user", - assignment=user_assignment - ) - - # 2. Check JWT role assignments (GSI3: RoleAssignmentIndex) - if user.roles: - role_assignments = [] - for role in user.roles: - # Targeted query per role (O(log n) per role) - assignments = await self.repository.query_role_assignments(role) - role_assignments.extend(assignments) - - if role_assignments: - # Sort by priority (descending) and take highest enabled - role_assignments.sort(key=lambda a: a.priority, reverse=True) - for assignment in role_assignments: - if assignment.enabled: - tier = await self.repository.get_tier(assignment.tier_id) - if tier and tier.enabled: - return ResolvedQuota( - user_id=user.user_id, - tier=tier, - matched_by=f"jwt_role:{assignment.jwt_role}", - assignment=assignment - ) - - # 3. Fall back to default tier (GSI1: AssignmentTypeIndex) - default_assignments = await self.repository.list_assignments_by_type( - assignment_type="default_tier", - enabled_only=True - ) - if default_assignments: - # Take highest priority default - default_assignment = default_assignments[0] - tier = await self.repository.get_tier(default_assignment.tier_id) - if tier and tier.enabled: - return ResolvedQuota( - user_id=user.user_id, - tier=tier, - matched_by="default_tier", - assignment=default_assignment - ) - - # No quota configured - logger.warning(f"No quota configured for user {user.user_id}") - return None - - def _get_cache_key(self, user: User) -> str: - """ - Generate cache key from user attributes. - - Includes user_id and roles hash to auto-invalidate when these change. - """ - roles_hash = hash(frozenset(user.roles)) if user.roles else 0 - return f"{user.user_id}:{roles_hash}" - - def invalidate_cache(self, user_id: Optional[str] = None): - """Invalidate cache for specific user or all users""" - if user_id: - # Remove all cache entries for this user - keys_to_remove = [k for k in self._cache.keys() if k.startswith(f"{user_id}:")] - for key in keys_to_remove: - del self._cache[key] - logger.info(f"Invalidated cache for user {user_id}") - else: - # Clear entire cache - self._cache.clear() - logger.info("Invalidated entire quota cache") -``` - -### Quota Checker (Hard Limits Only) - -**File:** `backend/src/agentcore/quota/checker.py` - -```python -from typing import Optional -from datetime import datetime -import logging -from apis.shared.auth.models import User -from api.costs.service import CostAggregator -from .models import QuotaTier, QuotaCheckResult, QuotaEvent -from .resolver import QuotaResolver -from .event_recorder import QuotaEventRecorder - -logger = logging.getLogger(__name__) - -class QuotaChecker: - """Checks quota limits and enforces hard limits (Phase 1)""" - - def __init__( - self, - resolver: QuotaResolver, - cost_aggregator: CostAggregator, - event_recorder: QuotaEventRecorder - ): - self.resolver = resolver - self.cost_aggregator = cost_aggregator - self.event_recorder = event_recorder - - async def check_quota(self, user: User) -> QuotaCheckResult: - """ - Check if user is within quota limits (Phase 1: hard limits only). - - Returns QuotaCheckResult with: - - allowed: bool - whether request should proceed - - message: str - explanation - - tier: QuotaTier - applicable tier - - current_usage, quota_limit, percentage_used, remaining - """ - # Resolve user's quota tier - resolved = await self.resolver.resolve_user_quota(user) - - if not resolved: - # No quota configured - allow by default - return QuotaCheckResult( - allowed=True, - message="No quota configured", - current_usage=0.0, - percentage_used=0.0 - ) - - tier = resolved.tier - - # Handle unlimited tier (if configured with very high limit) - if tier.monthly_cost_limit >= 999999: - return QuotaCheckResult( - allowed=True, - message="Unlimited quota", - tier=tier, - current_usage=0.0, - quota_limit=tier.monthly_cost_limit, - percentage_used=0.0 - ) - - # Get current usage for the period - period = self._get_current_period(tier.period_type) - summary = await self.cost_aggregator.get_user_cost_summary( - user_id=user.user_id, - period=period - ) - - current_usage = summary.total_cost - limit = tier.monthly_cost_limit - percentage_used = (current_usage / limit * 100) if limit > 0 else 0 - remaining = max(0, limit - current_usage) - - # Check hard limit (Phase 1: block only, no warnings) - if current_usage >= limit: - # Record block event - await self.event_recorder.record_block( - user=user, - tier=tier, - current_usage=current_usage, - limit=limit, - percentage_used=percentage_used - ) - - return QuotaCheckResult( - allowed=False, - message=f"Quota exceeded: ${current_usage:.2f} / ${limit:.2f}", - tier=tier, - current_usage=current_usage, - quota_limit=limit, - percentage_used=percentage_used, - remaining=0.0 - ) - - # Within limits - return QuotaCheckResult( - allowed=True, - message="Within quota", - tier=tier, - current_usage=current_usage, - quota_limit=limit, - percentage_used=percentage_used, - remaining=remaining - ) - - def _get_current_period(self, period_type: str) -> str: - """Get current period string for cost aggregation""" - now = datetime.utcnow() - - if period_type == "monthly": - return now.strftime("%Y-%m") - elif period_type == "daily": - return now.strftime("%Y-%m-%d") - else: - return now.strftime("%Y-%m") -``` - -### Event Recorder (Blocks Only) - -**File:** `backend/src/agentcore/quota/event_recorder.py` - -```python -from typing import Optional -from datetime import datetime -import uuid -import logging -from apis.shared.auth.models import User -from .models import QuotaTier, QuotaEvent -from .repository import QuotaRepository - -logger = logging.getLogger(__name__) - -class QuotaEventRecorder: - """Records quota enforcement events (Phase 1: blocks only)""" - - def __init__(self, repository: QuotaRepository): - self.repository = repository - - async def record_block( - self, - user: User, - tier: QuotaTier, - current_usage: float, - limit: float, - percentage_used: float, - session_id: Optional[str] = None - ): - """Record quota block event""" - event = QuotaEvent( - event_id=str(uuid.uuid4()), - user_id=user.user_id, - tier_id=tier.tier_id, - event_type="block", - current_usage=current_usage, - quota_limit=limit, - percentage_used=percentage_used, - timestamp=datetime.utcnow().isoformat() + 'Z', - metadata={ - "tier_name": tier.tier_name, - "session_id": session_id - } - ) - - try: - await self.repository.record_event(event) - logger.info(f"Recorded block event for user {user.user_id}") - except Exception as e: - logger.error(f"Failed to record block event: {e}") -``` - -### Admin API Routes - -**File:** `backend/src/apis/app_api/admin/quota/routes.py` - -```python -from fastapi import APIRouter, Depends, HTTPException, status -from typing import List, Optional -import logging -from apis.shared.auth.dependencies import get_current_user -from apis.shared.auth.models import User -from agents.main_agent.quota.repository import QuotaRepository -from agents.main_agent.quota.resolver import QuotaResolver -from agents.main_agent.quota.models import QuotaTier, QuotaAssignment -from api.costs.service import CostAggregator -from .service import QuotaAdminService -from .models import ( - QuotaTierCreate, - QuotaTierUpdate, - QuotaAssignmentCreate, - QuotaAssignmentUpdate, - UserQuotaInfo -) - -logger = logging.getLogger(__name__) - -router = APIRouter(prefix="/quota", tags=["admin-quota"]) - -# ========== Dependencies ========== - -def get_quota_repository() -> QuotaRepository: - """Get quota repository instance""" - return QuotaRepository() - -def get_quota_resolver( - repo: QuotaRepository = Depends(get_quota_repository) -) -> QuotaResolver: - """Get quota resolver instance""" - return QuotaResolver(repository=repo) - -def get_quota_service( - repo: QuotaRepository = Depends(get_quota_repository), - resolver: QuotaResolver = Depends(get_quota_resolver), - cost_aggregator: CostAggregator = Depends() -) -> QuotaAdminService: - """Get quota admin service instance""" - return QuotaAdminService( - repository=repo, - resolver=resolver, - cost_aggregator=cost_aggregator - ) - -# ========== Quota Tiers ========== - -@router.post("/tiers", response_model=QuotaTier, status_code=status.HTTP_201_CREATED) -async def create_tier( - tier_data: QuotaTierCreate, - admin_user: User = Depends(get_current_user), - service: QuotaAdminService = Depends(get_quota_service) -): - """Create a new quota tier (admin only)""" - # TODO: Add admin role check - try: - tier = await service.create_tier(tier_data, admin_user) - return tier - except ValueError as e: - raise HTTPException(status_code=400, detail=str(e)) - -@router.get("/tiers", response_model=List[QuotaTier]) -async def list_tiers( - enabled_only: bool = False, - admin_user: User = Depends(get_current_user), - service: QuotaAdminService = Depends(get_quota_service) -): - """List all quota tiers (admin only)""" - tiers = await service.list_tiers(enabled_only=enabled_only) - return tiers - -@router.get("/tiers/{tier_id}", response_model=QuotaTier) -async def get_tier( - tier_id: str, - admin_user: User = Depends(get_current_user), - service: QuotaAdminService = Depends(get_quota_service) -): - """Get quota tier by ID (admin only)""" - tier = await service.get_tier(tier_id) - if not tier: - raise HTTPException(status_code=404, detail=f"Tier {tier_id} not found") - return tier - -@router.patch("/tiers/{tier_id}", response_model=QuotaTier) -async def update_tier( - tier_id: str, - updates: QuotaTierUpdate, - admin_user: User = Depends(get_current_user), - service: QuotaAdminService = Depends(get_quota_service) -): - """Update quota tier (admin only)""" - tier = await service.update_tier(tier_id, updates, admin_user) - if not tier: - raise HTTPException(status_code=404, detail=f"Tier {tier_id} not found") - return tier - -@router.delete("/tiers/{tier_id}", status_code=status.HTTP_204_NO_CONTENT) -async def delete_tier( - tier_id: str, - admin_user: User = Depends(get_current_user), - service: QuotaAdminService = Depends(get_quota_service) -): - """Delete quota tier (admin only)""" - try: - success = await service.delete_tier(tier_id, admin_user) - if not success: - raise HTTPException(status_code=404, detail=f"Tier {tier_id} not found") - except ValueError as e: - raise HTTPException(status_code=400, detail=str(e)) - -# ========== Quota Assignments ========== - -@router.post("/assignments", response_model=QuotaAssignment, status_code=status.HTTP_201_CREATED) -async def create_assignment( - assignment_data: QuotaAssignmentCreate, - admin_user: User = Depends(get_current_user), - service: QuotaAdminService = Depends(get_quota_service) -): - """Create a new quota assignment (admin only)""" - try: - assignment = await service.create_assignment(assignment_data, admin_user) - return assignment - except ValueError as e: - raise HTTPException(status_code=400, detail=str(e)) - -@router.get("/assignments", response_model=List[QuotaAssignment]) -async def list_assignments( - assignment_type: Optional[str] = None, - enabled_only: bool = False, - admin_user: User = Depends(get_current_user), - service: QuotaAdminService = Depends(get_quota_service) -): - """List all quota assignments (admin only)""" - assignments = await service.list_assignments( - assignment_type=assignment_type, - enabled_only=enabled_only - ) - return assignments - -@router.get("/assignments/{assignment_id}", response_model=QuotaAssignment) -async def get_assignment( - assignment_id: str, - admin_user: User = Depends(get_current_user), - service: QuotaAdminService = Depends(get_quota_service) -): - """Get quota assignment by ID (admin only)""" - assignment = await service.get_assignment(assignment_id) - if not assignment: - raise HTTPException(status_code=404, detail=f"Assignment {assignment_id} not found") - return assignment - -@router.patch("/assignments/{assignment_id}", response_model=QuotaAssignment) -async def update_assignment( - assignment_id: str, - updates: QuotaAssignmentUpdate, - admin_user: User = Depends(get_current_user), - service: QuotaAdminService = Depends(get_quota_service) -): - """Update quota assignment (admin only)""" - try: - assignment = await service.update_assignment(assignment_id, updates, admin_user) - if not assignment: - raise HTTPException(status_code=404, detail=f"Assignment {assignment_id} not found") - return assignment - except ValueError as e: - raise HTTPException(status_code=400, detail=str(e)) - -@router.delete("/assignments/{assignment_id}", status_code=status.HTTP_204_NO_CONTENT) -async def delete_assignment( - assignment_id: str, - admin_user: User = Depends(get_current_user), - service: QuotaAdminService = Depends(get_quota_service) -): - """Delete quota assignment (admin only)""" - success = await service.delete_assignment(assignment_id, admin_user) - if not success: - raise HTTPException(status_code=404, detail=f"Assignment {assignment_id} not found") - -# ========== User Quota Info (Inspector) ========== - -@router.get("/users/{user_id}", response_model=UserQuotaInfo) -async def get_user_quota_info( - user_id: str, - admin_user: User = Depends(get_current_user), - service: QuotaAdminService = Depends(get_quota_service) -): - """Get comprehensive quota information for a user (admin only)""" - # TODO: Add ability to pass user email/roles for resolution - info = await service.get_user_quota_info(user_id=user_id, email="", roles=[]) - return info -``` - ---- - -## CDK Infrastructure - -### Stack Structure - -``` -cdk/ -└── lib/ - └── stacks/ - └── quota-stack.ts # ← NEW: Quota DynamoDB tables -``` - -### QuotaStack Implementation - -**File:** `cdk/lib/stacks/quota-stack.ts` - -```typescript -import * as cdk from 'aws-cdk-lib'; -import * as dynamodb from 'aws-cdk-lib/aws-dynamodb'; -import { Construct } from 'constructs'; - -export interface QuotaStackProps extends cdk.StackProps { - environment: string; -} - -export class QuotaStack extends cdk.Stack { - public readonly userQuotasTable: dynamodb.Table; - public readonly quotaEventsTable: dynamodb.Table; - - constructor(scope: Construct, id: string, props: QuotaStackProps) { - super(scope, id, props); - - const { environment } = props; - - // ========== UserQuotas Table ========== - - this.userQuotasTable = new dynamodb.Table(this, 'UserQuotasTable', { - tableName: `UserQuotas-${environment}`, - partitionKey: { - name: 'PK', - type: dynamodb.AttributeType.STRING, - }, - sortKey: { - name: 'SK', - type: dynamodb.AttributeType.STRING, - }, - billingMode: dynamodb.BillingMode.PAY_PER_REQUEST, - pointInTimeRecovery: true, - removalPolicy: environment === 'prod' - ? cdk.RemovalPolicy.RETAIN - : cdk.RemovalPolicy.DESTROY, - }); - - // GSI1: AssignmentTypeIndex - // Query assignments by type, sorted by priority - this.userQuotasTable.addGlobalSecondaryIndex({ - indexName: 'AssignmentTypeIndex', - partitionKey: { - name: 'GSI1PK', - type: dynamodb.AttributeType.STRING, - }, - sortKey: { - name: 'GSI1SK', - type: dynamodb.AttributeType.STRING, - }, - projectionType: dynamodb.ProjectionType.ALL, - }); - - // GSI2: UserAssignmentIndex - // Query direct user assignments (O(1) lookup) - this.userQuotasTable.addGlobalSecondaryIndex({ - indexName: 'UserAssignmentIndex', - partitionKey: { - name: 'GSI2PK', - type: dynamodb.AttributeType.STRING, - }, - sortKey: { - name: 'GSI2SK', - type: dynamodb.AttributeType.STRING, - }, - projectionType: dynamodb.ProjectionType.ALL, - }); - - // GSI3: RoleAssignmentIndex - // Query role-based assignments, sorted by priority - this.userQuotasTable.addGlobalSecondaryIndex({ - indexName: 'RoleAssignmentIndex', - partitionKey: { - name: 'GSI3PK', - type: dynamodb.AttributeType.STRING, - }, - sortKey: { - name: 'GSI3SK', - type: dynamodb.AttributeType.STRING, - }, - projectionType: dynamodb.ProjectionType.ALL, - }); - - // ========== QuotaEvents Table ========== - - this.quotaEventsTable = new dynamodb.Table(this, 'QuotaEventsTable', { - tableName: `QuotaEvents-${environment}`, - partitionKey: { - name: 'PK', - type: dynamodb.AttributeType.STRING, - }, - sortKey: { - name: 'SK', - type: dynamodb.AttributeType.STRING, - }, - billingMode: dynamodb.BillingMode.PAY_PER_REQUEST, - pointInTimeRecovery: true, - removalPolicy: environment === 'prod' - ? cdk.RemovalPolicy.RETAIN - : cdk.RemovalPolicy.DESTROY, - }); - - // GSI5: TierEventIndex - // Query events by tier for analytics (Phase 2) - this.quotaEventsTable.addGlobalSecondaryIndex({ - indexName: 'TierEventIndex', - partitionKey: { - name: 'GSI5PK', - type: dynamodb.AttributeType.STRING, - }, - sortKey: { - name: 'GSI5SK', - type: dynamodb.AttributeType.STRING, - }, - projectionType: dynamodb.ProjectionType.ALL, - }); - - // ========== Outputs ========== - - new cdk.CfnOutput(this, 'UserQuotasTableName', { - value: this.userQuotasTable.tableName, - description: 'UserQuotas table name', - exportName: `UserQuotasTable-${environment}`, - }); - - new cdk.CfnOutput(this, 'QuotaEventsTableName', { - value: this.quotaEventsTable.tableName, - description: 'QuotaEvents table name', - exportName: `QuotaEventsTable-${environment}`, - }); - - // ========== Tags ========== - - cdk.Tags.of(this).add('Environment', environment); - cdk.Tags.of(this).add('Service', 'quota-management'); - cdk.Tags.of(this).add('Phase', '1'); - } -} -``` - -### Integration with Main Stack - -**File:** `cdk/bin/cdk.ts` (modification) - -```typescript -import { QuotaStack } from '../lib/stacks/quota-stack'; - -const app = new cdk.App(); -const environment = app.node.tryGetContext('environment') || 'dev'; - -// Existing stacks... - -// Add QuotaStack -const quotaStack = new QuotaStack(app, `QuotaStack-${environment}`, { - environment, - env: { - account: process.env.CDK_DEFAULT_ACCOUNT, - region: process.env.CDK_DEFAULT_REGION, - }, -}); - -app.synth(); -``` - -### Deployment Commands - -```bash -# Deploy quota stack to dev -cd cdk -cdk deploy QuotaStack-dev - -# Deploy to production -cdk deploy QuotaStack-prod --context environment=prod - -# View differences before deploy -cdk diff QuotaStack-dev -``` - ---- - -## Testing Strategy - -### Unit Tests - -**File:** `backend/tests/quota/test_resolver.py` - -```python -import pytest -from datetime import datetime -from agents.main_agent.quota.resolver import QuotaResolver -from agents.main_agent.quota.repository import QuotaRepository -from agents.main_agent.quota.models import QuotaTier, QuotaAssignment, QuotaAssignmentType -from apis.shared.auth.models import User - -@pytest.fixture -def mock_repository(mocker): - return mocker.Mock(spec=QuotaRepository) - -@pytest.fixture -def resolver(mock_repository): - return QuotaResolver(repository=mock_repository, cache_ttl_seconds=300) - -@pytest.mark.asyncio -async def test_resolve_direct_user_assignment(resolver, mock_repository): - """Test that direct user assignment takes priority""" - user = User(user_id="test123", email="test@example.com", roles=["Student"]) - - # Mock direct user assignment - assignment = QuotaAssignment( - assignment_id="assign1", - tier_id="premium", - assignment_type=QuotaAssignmentType.DIRECT_USER, - user_id="test123", - priority=300, - enabled=True, - created_at="2025-01-01T00:00:00Z", - updated_at="2025-01-01T00:00:00Z", - created_by="admin" - ) - - tier = QuotaTier( - tier_id="premium", - tier_name="Premium", - monthly_cost_limit=500.0, - action_on_limit="block", - enabled=True, - created_at="2025-01-01T00:00:00Z", - updated_at="2025-01-01T00:00:00Z", - created_by="admin" - ) - - mock_repository.query_user_assignment.return_value = assignment - mock_repository.get_tier.return_value = tier - - # Resolve - resolved = await resolver.resolve_user_quota(user) - - assert resolved is not None - assert resolved.tier.tier_id == "premium" - assert resolved.matched_by == "direct_user" - assert resolved.assignment.assignment_id == "assign1" - -@pytest.mark.asyncio -async def test_resolve_fallback_to_role(resolver, mock_repository): - """Test fallback to role assignment when no direct user assignment""" - user = User(user_id="test456", email="test@example.com", roles=["Faculty"]) - - # No direct user assignment - mock_repository.query_user_assignment.return_value = None - - # Mock role assignment - role_assignment = QuotaAssignment( - assignment_id="assign2", - tier_id="faculty", - assignment_type=QuotaAssignmentType.JWT_ROLE, - jwt_role="Faculty", - priority=200, - enabled=True, - created_at="2025-01-01T00:00:00Z", - updated_at="2025-01-01T00:00:00Z", - created_by="admin" - ) - - tier = QuotaTier( - tier_id="faculty", - tier_name="Faculty", - monthly_cost_limit=1000.0, - action_on_limit="block", - enabled=True, - created_at="2025-01-01T00:00:00Z", - updated_at="2025-01-01T00:00:00Z", - created_by="admin" - ) - - mock_repository.query_role_assignments.return_value = [role_assignment] - mock_repository.get_tier.return_value = tier - - # Resolve - resolved = await resolver.resolve_user_quota(user) - - assert resolved is not None - assert resolved.tier.tier_id == "faculty" - assert resolved.matched_by == "jwt_role:Faculty" - -@pytest.mark.asyncio -async def test_cache_hit(resolver, mock_repository): - """Test that cache reduces DynamoDB calls""" - user = User(user_id="test789", email="test@example.com", roles=[]) - - # First call - cache miss - mock_repository.query_user_assignment.return_value = None - mock_repository.query_role_assignments.return_value = [] - - default_assignment = QuotaAssignment( - assignment_id="default1", - tier_id="basic", - assignment_type=QuotaAssignmentType.DEFAULT_TIER, - priority=100, - enabled=True, - created_at="2025-01-01T00:00:00Z", - updated_at="2025-01-01T00:00:00Z", - created_by="admin" - ) - - tier = QuotaTier( - tier_id="basic", - tier_name="Basic", - monthly_cost_limit=100.0, - action_on_limit="block", - enabled=True, - created_at="2025-01-01T00:00:00Z", - updated_at="2025-01-01T00:00:00Z", - created_by="admin" - ) - - mock_repository.list_assignments_by_type.return_value = [default_assignment] - mock_repository.get_tier.return_value = tier - - resolved1 = await resolver.resolve_user_quota(user) - - # Second call - cache hit (no DB calls) - resolved2 = await resolver.resolve_user_quota(user) - - assert resolved1 == resolved2 - # Verify DB was only called once - assert mock_repository.query_user_assignment.call_count == 1 -``` - -### Integration Tests - -**File:** `backend/tests/quota/test_integration.py` - -```python -import pytest -import boto3 -from moto import mock_dynamodb -from agents.main_agent.quota.repository import QuotaRepository -from agents.main_agent.quota.models import QuotaTier, QuotaAssignment, QuotaAssignmentType - -@pytest.fixture -def dynamodb(): - with mock_dynamodb(): - yield boto3.resource('dynamodb', region_name='us-east-1') - -@pytest.fixture -def create_tables(dynamodb): - # Create UserQuotas table - table = dynamodb.create_table( - TableName='UserQuotas', - KeySchema=[ - {'AttributeName': 'PK', 'KeyType': 'HASH'}, - {'AttributeName': 'SK', 'KeyType': 'RANGE'}, - ], - AttributeDefinitions=[ - {'AttributeName': 'PK', 'AttributeType': 'S'}, - {'AttributeName': 'SK', 'AttributeType': 'S'}, - {'AttributeName': 'GSI2PK', 'AttributeType': 'S'}, - {'AttributeName': 'GSI2SK', 'AttributeType': 'S'}, - ], - GlobalSecondaryIndexes=[ - { - 'IndexName': 'UserAssignmentIndex', - 'KeySchema': [ - {'AttributeName': 'GSI2PK', 'KeyType': 'HASH'}, - {'AttributeName': 'GSI2SK', 'KeyType': 'RANGE'}, - ], - 'Projection': {'ProjectionType': 'ALL'}, - } - ], - BillingMode='PAY_PER_REQUEST', - ) - - # Create QuotaEvents table - events_table = dynamodb.create_table( - TableName='QuotaEvents', - KeySchema=[ - {'AttributeName': 'PK', 'KeyType': 'HASH'}, - {'AttributeName': 'SK', 'KeyType': 'RANGE'}, - ], - AttributeDefinitions=[ - {'AttributeName': 'PK', 'AttributeType': 'S'}, - {'AttributeName': 'SK', 'AttributeType': 'S'}, - ], - BillingMode='PAY_PER_REQUEST', - ) - - return table, events_table - -@pytest.mark.asyncio -async def test_create_and_retrieve_tier(dynamodb, create_tables): - """Test creating and retrieving a tier from DynamoDB""" - repo = QuotaRepository() - - tier = QuotaTier( - tier_id="test-tier", - tier_name="Test Tier", - monthly_cost_limit=200.0, - action_on_limit="block", - enabled=True, - created_at="2025-01-01T00:00:00Z", - updated_at="2025-01-01T00:00:00Z", - created_by="test" - ) - - # Create - created = await repo.create_tier(tier) - assert created.tier_id == "test-tier" - - # Retrieve - retrieved = await repo.get_tier("test-tier") - assert retrieved is not None - assert retrieved.tier_name == "Test Tier" - assert retrieved.monthly_cost_limit == 200.0 -``` - -### API Tests - -**File:** `backend/tests/quota/test_api.py` - -```python -import pytest -from fastapi.testclient import TestClient -from api.main import app - -client = TestClient(app) - -@pytest.fixture -def admin_token(): - # TODO: Generate admin JWT token - return "Bearer test_admin_token" - -def test_create_tier(admin_token): - """Test creating a tier via API""" - response = client.post( - "/api/admin/quota/tiers", - json={ - "tierId": "api-test-tier", - "tierName": "API Test Tier", - "monthlyCostLimit": 300.0, - "actionOnLimit": "block" - }, - headers={"Authorization": admin_token} - ) - - assert response.status_code == 201 - data = response.json() - assert data["tierId"] == "api-test-tier" - assert data["tierName"] == "API Test Tier" - -def test_list_tiers(admin_token): - """Test listing tiers via API""" - response = client.get( - "/api/admin/quota/tiers", - headers={"Authorization": admin_token} - ) - - assert response.status_code == 200 - data = response.json() - assert isinstance(data, list) -``` - ---- - -## Validation Criteria - -### Phase 1 Completion Checklist - -Use this checklist to validate Phase 1 implementation before proceeding to Phase 2: - -#### ✅ Database (CDK) - -- [ ] `UserQuotas` table created with correct schema -- [ ] All 3 GSIs created (AssignmentTypeIndex, UserAssignmentIndex, RoleAssignmentIndex) -- [ ] `QuotaEvents` table created with correct schema -- [ ] GSI5 (TierEventIndex) created -- [ ] Tables use PAY_PER_REQUEST billing -- [ ] Point-in-time recovery enabled -- [ ] Correct removal policy (RETAIN for prod, DESTROY for dev) - -#### ✅ Backend - Core Logic - -- [ ] `QuotaTier` model validates correctly -- [ ] `QuotaAssignment` model validates criteria match -- [ ] `QuotaRepository` implements all CRUD operations -- [ ] `QuotaRepository` uses ZERO table scans (all queries use GSIs or PK) -- [ ] `QuotaResolver` caches results for 5 minutes -- [ ] `QuotaResolver` correctly prioritizes: direct user > role > default -- [ ] `QuotaChecker` blocks requests when hard limit exceeded -- [ ] `QuotaEventRecorder` records block events to QuotaEvents table - -#### ✅ Backend - Admin API - -- [ ] Admin routes mounted at `/api/admin/quota/` -- [ ] All tier CRUD endpoints working (POST, GET, PATCH, DELETE) -- [ ] All assignment CRUD endpoints working -- [ ] `/users/{user_id}` endpoint returns comprehensive quota info -- [ ] All endpoints require authentication -- [ ] Proper error handling (400, 404, 500) - -#### ✅ Testing - -- [ ] Unit tests for `QuotaResolver` pass -- [ ] Unit tests for `QuotaChecker` pass -- [ ] Unit tests for `QuotaRepository` pass -- [ ] Integration tests with mocked DynamoDB pass -- [ ] API tests for all endpoints pass - -#### ✅ Performance - -- [ ] Quota resolution completes in <100ms with cache hit -- [ ] Cache hit rate >80% after warmup -- [ ] No DynamoDB scans in CloudWatch metrics -- [ ] All queries use targeted PK or GSI queries - -#### ✅ Documentation - -- [ ] All public methods have docstrings -- [ ] Type hints on all function signatures -- [ ] README updated with quota management overview -- [ ] API endpoints documented - -### Manual Validation Steps - -#### 1. Deploy Infrastructure - -```bash -# Deploy CDK stack -cd cdk -cdk deploy QuotaStack-dev - -# Verify tables created -aws dynamodb list-tables --query "TableNames[?contains(@, 'UserQuotas')]" -aws dynamodb describe-table --table-name UserQuotas-dev \ - --query "Table.GlobalSecondaryIndexes[].IndexName" -``` - -Expected output: `["AssignmentTypeIndex", "UserAssignmentIndex", "RoleAssignmentIndex"]` - -#### 2. Test Admin API - -```bash -# Create a tier -curl -X POST http://localhost:8000/api/admin/quota/tiers \ - -H "Authorization: Bearer $ADMIN_TOKEN" \ - -H "Content-Type: application/json" \ - -d '{ - "tierId": "test-tier", - "tierName": "Test Tier", - "monthlyCostLimit": 100.0, - "actionOnLimit": "block" - }' - -# List tiers -curl http://localhost:8000/api/admin/quota/tiers \ - -H "Authorization: Bearer $ADMIN_TOKEN" - -# Create direct user assignment -curl -X POST http://localhost:8000/api/admin/quota/assignments \ - -H "Authorization: Bearer $ADMIN_TOKEN" \ - -H "Content-Type: application/json" \ - -d '{ - "tierId": "test-tier", - "assignmentType": "direct_user", - "userId": "test123", - "priority": 300 - }' -``` - -#### 3. Test Quota Resolution - -```python -# Test quota resolution in Python console -from apis.shared.auth.models import User -from agents.main_agent.quota.repository import QuotaRepository -from agents.main_agent.quota.resolver import QuotaResolver - -user = User(user_id="test123", email="test@example.com", roles=[]) -repo = QuotaRepository() -resolver = QuotaResolver(repository=repo) - -resolved = await resolver.resolve_user_quota(user) -print(f"Resolved tier: {resolved.tier.tier_name}") -print(f"Matched by: {resolved.matched_by}") -``` - -#### 4. Test Hard Limit Blocking - -```python -from agents.main_agent.quota.checker import QuotaChecker -from api.costs.service import CostAggregator - -# Assume user has exceeded quota -result = await checker.check_quota(user) -print(f"Allowed: {result.allowed}") -print(f"Message: {result.message}") -print(f"Usage: {result.current_usage} / {result.quota_limit}") -``` - -#### 5. Verify No Scans in CloudWatch - -```bash -# Check DynamoDB metrics for scans -aws cloudwatch get-metric-statistics \ - --namespace AWS/DynamoDB \ - --metric-name ConsumedReadCapacityUnits \ - --dimensions Name=TableName,Value=UserQuotas-dev Name=Operation,Value=Scan \ - --start-time 2025-12-17T00:00:00Z \ - --end-time 2025-12-17T23:59:59Z \ - --period 3600 \ - --statistics Sum -``` - -Expected: Sum should be 0 (no scans) - ---- - -## Next Steps - -Once Phase 1 validation is complete: - -1. **User Acceptance Testing** - - Admin creates 3 tiers (Basic, Premium, Enterprise) - - Admin creates assignments for different user types - - Verify quota resolution works for sample users - - Verify hard limits block requests correctly - -2. **Performance Benchmarking** - - Load test with 10,000 simulated users - - Measure cache hit rate - - Measure DynamoDB query latency - - Verify no performance degradation - -3. **Proceed to Phase 2** - - See `QUOTA_MANAGEMENT_PHASE2_SPEC.md` - - Implement quota overrides - - Implement soft limit warnings - - Implement email domain matching - - Build frontend UI - ---- - -## Appendix - -### Sample Data for Testing - -#### Sample Tiers - -```json -[ - { - "tierId": "basic", - "tierName": "Basic", - "description": "For casual users", - "monthlyCostLimit": 50.0, - "actionOnLimit": "block", - "enabled": true - }, - { - "tierId": "premium", - "tierName": "Premium", - "description": "For regular users", - "monthlyCostLimit": 200.0, - "actionOnLimit": "block", - "enabled": true - }, - { - "tierId": "enterprise", - "tierName": "Enterprise", - "description": "For power users", - "monthlyCostLimit": 1000.0, - "actionOnLimit": "block", - "enabled": true - } -] -``` - -#### Sample Assignments - -```json -[ - { - "assignmentType": "default_tier", - "tierId": "basic", - "priority": 100 - }, - { - "assignmentType": "jwt_role", - "tierId": "premium", - "jwtRole": "Faculty", - "priority": 200 - }, - { - "assignmentType": "direct_user", - "tierId": "enterprise", - "userId": "admin123", - "priority": 300 - } -] -``` - -### Expected Query Patterns - -| Operation | Query Type | Index Used | O Complexity | -|-----------|------------|------------|--------------| -| Get tier by ID | GetItem | Primary Key | O(1) | -| List all tiers | Query (begins_with) | Primary Key | O(n) tiers | -| Get user assignment | Query | GSI2 (UserAssignmentIndex) | O(1) | -| Get role assignments | Query | GSI3 (RoleAssignmentIndex) | O(k) roles | -| List assignments by type | Query | GSI1 (AssignmentTypeIndex) | O(m) assignments | -| Get user events | Query | Primary Key | O(1) | -| Get tier events | Query | GSI5 (TierEventIndex) | O(p) events | - -**No Scans:** All operations use targeted queries with known keys. - ---- - -**End of Phase 1 Specification** diff --git a/docs/QUOTA_MANAGEMENT_PHASE2_IMPLEMENTATION_STATUS.md b/docs/QUOTA_MANAGEMENT_PHASE2_IMPLEMENTATION_STATUS.md deleted file mode 100644 index e4531142..00000000 --- a/docs/QUOTA_MANAGEMENT_PHASE2_IMPLEMENTATION_STATUS.md +++ /dev/null @@ -1,400 +0,0 @@ -# Quota Management Phase 2 - Implementation Status - -**Date:** December 20, 2024 -**Status:** Backend Complete | Frontend Foundation Complete | UI Pages Pending -**Completion:** 9/17 tasks (53%) - ---- - -## ✅ Completed Work - -### **1. Backend Models & Domain Logic (Items 1-5)** - -#### **Models (`backend/src/agents/main_agent/quota/models.py`)** -- ✅ Added `EMAIL_DOMAIN` to `QuotaAssignmentType` enum -- ✅ Updated `QuotaTier` with Phase 2 fields: - - `soft_limit_percentage` (default: 80.0) - - `action_on_limit: Literal["block", "warn"]` -- ✅ Updated `QuotaAssignment` with `email_domain` field -- ✅ Updated `QuotaEvent` with all event types: - - `"warning"`, `"block"`, `"reset"`, `"override_applied"` -- ✅ Added `warning_level` to `QuotaCheckResult` -- ✅ Updated `ResolvedQuota` with optional `override` field -- ✅ **New:** `QuotaOverride` model with temporal bounds and validation - -#### **Repository (`backend/src/agents/main_agent/quota/repository.py`)** -- ✅ Added override CRUD methods: - - `create_override()`, `get_override()`, `get_active_override()` - - `list_overrides()`, `update_override()`, `delete_override()` -- ✅ Added `get_recent_event()` for warning deduplication -- ✅ Uses GSI4 (UserOverrideIndex) for O(1) active override lookups - -#### **Checker (`backend/src/agents/main_agent/quota/checker.py`)** -- ✅ Implemented soft limit warning detection (80%, 90%) -- ✅ Added `action_on_limit: "warn"` support (allow over-limit with warning) -- ✅ Returns `warning_level` in `QuotaCheckResult` -- ✅ Records warning events with deduplication - -#### **Event Recorder (`backend/src/agents/main_agent/quota/event_recorder.py`)** -- ✅ `record_warning_if_needed()` - 60-minute deduplication -- ✅ `record_override_applied()` - tracks override usage -- ✅ `record_reset()` - manual quota resets - -#### **Resolver (`backend/src/agents/main_agent/quota/resolver.py`)** -- ✅ Priority-based resolution with Phase 2 order: - 1. Active override (highest) - 2. Direct user assignment - 3. JWT role assignment - 4. **Email domain assignment** (new) - 5. Default tier -- ✅ `_override_to_tier()` - converts overrides to tiers -- ✅ `_matches_email_domain()` - supports: - - Exact: `university.edu` - - Wildcard: `*.university.edu` - - Regex: `regex:^(cs|eng)\\.university\\.edu$` - - Multiple: `university.edu,college.edu` -- ✅ Separate domain assignment cache - ---- - -### **2. Backend API Layer (Items 6-7)** - -#### **API Models (`backend/src/apis/app_api/admin/quota/models.py`)** -- ✅ Updated `QuotaTierCreate` with Phase 2 fields -- ✅ Updated `QuotaAssignmentCreate` with `emailDomain` -- ✅ **New:** `QuotaOverrideCreate` and `QuotaOverrideUpdate` - -#### **API Routes (`backend/src/apis/app_api/admin/quota/routes.py`)** -- ✅ Override endpoints: - - `POST /api/admin/quota/overrides` - create - - `GET /api/admin/quota/overrides` - list (with filters) - - `GET /api/admin/quota/overrides/{id}` - get by ID - - `PATCH /api/admin/quota/overrides/{id}` - update - - `DELETE /api/admin/quota/overrides/{id}` - delete -- ✅ Event endpoint: - - `GET /api/admin/quota/events` - query with filters - -#### **API Service (`backend/src/apis/app_api/admin/quota/service.py`)** -- ✅ Override service methods with cache invalidation -- ✅ Event query service with filtering - ---- - -### **3. Infrastructure (Item 8)** - -#### **CDK (`infrastructure/lib/app-api-stack.ts`)** -- ✅ Added GSI4 (UserOverrideIndex) to UserQuotas table: - - `GSI4PK`: `USER#{user_id}` - - `GSI4SK`: `VALID_UNTIL#{timestamp}` - - Enables O(1) active override lookups per user - - Supports expiry-based filtering - ---- - -### **4. Frontend Foundation (Item 9)** - -#### **TypeScript Models (`frontend/ai.client/src/app/admin/quota-tiers/models/quota.models.ts`)** -- ✅ Complete type definitions (15+ interfaces, 4 enums) -- ✅ Enums: `QuotaAssignmentType`, `QuotaEventType`, `ActionOnLimit`, `OverrideType` -- ✅ All domain models: `QuotaTier`, `QuotaAssignment`, `QuotaOverride`, `QuotaEvent` -- ✅ Create/Update DTOs for all entities -- ✅ `UserQuotaInfo` for inspector - -#### **HTTP Service (`frontend/ai.client/src/app/admin/quota-tiers/services/quota-http.service.ts`)** -- ✅ Full CRUD for tiers, assignments, overrides -- ✅ Event querying with filters -- ✅ User quota inspector endpoint -- ✅ Modern Angular pattern: `inject()` instead of constructor DI - -#### **State Service (`frontend/ai.client/src/app/admin/quota-tiers/services/quota-state.service.ts`)** -- ✅ Signal-based reactive state (Angular v21+ pattern) -- ✅ Computed signals: `enabledTiers`, `activeOverrides`, counts -- ✅ Async CRUD methods with automatic state updates -- ✅ Error handling and loading states - -#### **Routing (`frontend/ai.client/src/app/admin/quota-tiers/quota-routing.module.ts`)** -- ✅ Lazy-loaded route configuration -- ✅ 9 routes defined (list/detail for tiers, assignments, overrides + inspector + events) - ---- - -## 📋 Remaining Work - -### **5. UI Pages (Items 10-14) - NOT STARTED** - -#### **Item 10: Tier Management Pages** -**Files to create:** -- `pages/tier-list/tier-list.component.ts` - List all tiers with create/delete -- `pages/tier-detail/tier-detail.component.ts` - Edit tier details - -**Features:** -- Display tiers in table/card view -- Create tier form with Phase 2 fields (soft limit %, action on limit) -- Edit tier (name, limits, soft limit %, action) -- Delete tier with confirmation -- Enable/disable toggle - ---- - -#### **Item 11: Assignment Management Pages** -**Files to create:** -- `pages/assignment-list/assignment-list.component.ts` - List assignments -- `pages/assignment-detail/assignment-detail.component.ts` - Edit assignment - -**Features:** -- Filter by tier, assignment type -- Create assignment form with type selector: - - Direct user (userId input) - - JWT role (role dropdown/input) - - Email domain (domain pattern input with examples) - - Default tier -- Edit assignment (tier, priority, enabled) -- Delete with confirmation -- Priority indicator - ---- - -#### **Item 12: Override Management Pages** -**Files to create:** -- `pages/override-list/override-list.component.ts` - List overrides -- `pages/override-detail/override-detail.component.ts` - Edit override - -**Features:** -- Filter: active only, by user -- Status badges (active/expired/upcoming) -- Create override form: - - User ID lookup - - Type selector (custom limit / unlimited) - - Date pickers (valid from/until) - - Limit inputs (if custom) - - Reason textarea -- Edit: extend expiry, disable, update reason -- Delete with confirmation -- Visual timeline of override validity - ---- - -#### **Item 13: Quota Inspector Page** -**Files to create:** -- `pages/quota-inspector/quota-inspector.component.ts` - Debug user quotas - -**Features:** -- User search (by ID or email) -- Display resolved quota info: - - Matched tier and how it was resolved (override/direct/role/domain/default) - - Current usage with progress bar - - Warning level indicator - - Recent block events -- Override indicator (if applicable) -- Visual quota meter with color-coded zones: - - Green: 0-80% - - Yellow: 80-90% - - Orange: 90-100% - - Red: over limit - ---- - -#### **Item 14: Event Viewer Page** -**Files to create:** -- `pages/event-viewer/event-viewer.component.ts` - Monitor quota events - -**Features:** -- Filter by: - - User ID - - Tier ID - - Event type (warning/block/reset/override_applied) - - Date range -- Event timeline/table with: - - Event type badge - - Timestamp - - User/tier info - - Usage at time of event - - Metadata expansion -- Export to CSV -- Real-time updates (optional) - ---- - -### **6. Routing Integration (Item 15) - NOT STARTED** - -**File to update:** -- Main admin routing configuration -- Add navigation menu items - -**Tasks:** -- Wire up `quotaRoutes` to main admin module -- Add navigation links: - - Tiers - - Assignments - - Overrides - - Inspector - - Events -- Add breadcrumbs -- Add route guards (admin-only) - ---- - -### **7. Testing (Items 16-17) - NOT STARTED** - -#### **Backend Tests (Item 16)** -**Files to create/update:** -- `backend/tests/agents/main_agent/quota/test_resolver.py` - Phase 2 tests -- `backend/tests/agents/main_agent/quota/test_checker.py` - Soft limit tests -- `backend/tests/apis/app_api/admin/quota/test_routes.py` - Override routes - -**Test coverage needed:** -- Override priority (highest wins) -- Email domain matching (exact, wildcard, regex) -- Soft limit warnings (80%, 90%) -- Warning deduplication (60-minute window) -- Action on limit: "warn" behavior - -#### **Frontend Tests (Item 17)** -**Files to create:** -- Component tests for all 9 pages -- Service tests (HTTP, State) -- Model validation tests - -**Test coverage needed:** -- HTTP service CRUD operations -- State service signal updates -- Form validation -- User interactions - ---- - -## 🎯 Key Implementation Details - -### **Priority-Based Quota Resolution** -``` -1. Override (active, within valid dates) → HIGHEST -2. Direct user assignment (userId match) -3. JWT role assignment (role match, highest priority) -4. Email domain assignment (domain match, highest priority) -5. Default tier → FALLBACK -``` - -### **Email Domain Matching Patterns** -```typescript -// Exact -"university.edu" → matches university.edu - -// Wildcard subdomain -"*.university.edu" → matches cs.university.edu, eng.university.edu, etc. - -// Regex -"regex:^(cs|eng)\\.university\\.edu$" → matches cs.university.edu OR eng.university.edu - -// Multiple -"university.edu,college.edu" → matches either domain -``` - -### **Soft Limit Behavior** -```typescript -// Tier configured with: -softLimitPercentage: 80.0 -actionOnLimit: "block" - -// User at 85% usage: -warningLevel: "80%" // Warning event recorded (deduplicated 60min) -allowed: true // Still allowed - -// User at 100% usage: -warningLevel: "90%" // Warning event recorded -allowed: false // BLOCKED (actionOnLimit: "block") - -// If actionOnLimit: "warn": -allowed: true // Still allowed even at 100%! -``` - -### **DynamoDB Access Patterns** -``` -UserQuotas Table: -- GSI1 (AssignmentTypeIndex): Query by assignment type + priority -- GSI2 (UserAssignmentIndex): O(1) direct user assignment lookup -- GSI3 (RoleAssignmentIndex): O(1) role-based assignment lookup -- GSI4 (UserOverrideIndex): O(1) active override lookup by user - -QuotaEvents Table: -- Main table: Query by user + timestamp range -- GSI5 (TierEventIndex): Query by tier + timestamp range -``` - ---- - -## 🚀 Next Steps - -### **Recommended Implementation Order:** - -1. **Start with Tier List page** (foundational) - - Simple CRUD, no dependencies - - Tests the full stack end-to-end - - Reference: Existing admin pages in codebase - -2. **Then Assignment List** (builds on tiers) - - Tier dropdown populated from tier list - - More complex form (conditional fields) - -3. **Then Override List** (Phase 2 flagship feature) - - User lookup - - Date pickers - - Most complex form - -4. **Then Inspector** (debugging tool) - - Read-only - - Tests resolver integration - -5. **Finally Events** (analytics) - - Read-only - - Filtering + pagination - -### **UI Component Patterns to Reuse:** -- Existing admin pages (manage-models, bedrock-models, etc.) -- Tailwind CSS v4.1 utilities -- Angular v21 patterns (signals, native control flow) -- Heroicons for icons - ---- - -## 📦 Deliverables Summary - -### **✅ Production-Ready:** -- Complete backend API (Phase 2 features) -- Database schema with all indexes -- Type-safe frontend models and services -- Modern Angular architecture - -### **⏳ Pending:** -- 9 UI pages (5 list + 4 detail) -- Routing integration -- Comprehensive tests - -### **📊 Estimated Remaining Effort:** -- UI Pages: ~3-4 hours (reuse patterns, straightforward CRUD) -- Routing: ~30 minutes -- Testing: ~2-3 hours -- **Total:** ~6-8 hours - ---- - -## 📝 Notes for Next Session - -1. **Start Fresh Conversation:** Avoids token limits, keeps context clean -2. **Reference This Document:** Contains all implementation details -3. **Use Existing Patterns:** Check other admin pages for UI consistency -4. **Incremental Approach:** Build one page, test, then move to next -5. **Modern Angular:** Continue using signals, `inject()`, native control flow - ---- - -## 🔗 Related Documentation - -- Phase 1 Spec: `docs/QUOTA_MANAGEMENT_PHASE1_SPEC.md` -- Phase 2 Spec: `docs/QUOTA_MANAGEMENT_PHASE2_SPEC.md` -- Backend Models: `backend/src/agents/main_agent/quota/models.py` -- Frontend Models: `frontend/ai.client/src/app/admin/quota-tiers/models/quota.models.ts` -- API Routes: `backend/src/apis/app_api/admin/quota/routes.py` - ---- - -**Ready for UI implementation!** All complex logic is complete and tested. diff --git a/docs/QUOTA_MANAGEMENT_PHASE2_SPEC.md b/docs/QUOTA_MANAGEMENT_PHASE2_SPEC.md deleted file mode 100644 index 8f314ce6..00000000 --- a/docs/QUOTA_MANAGEMENT_PHASE2_SPEC.md +++ /dev/null @@ -1,1421 +0,0 @@ -# Quota Management System - Phase 2 Implementation Specification - -**Phase:** 2 (Enhanced Features + Frontend) -**Created:** 2025-12-17 -**Status:** Ready for Implementation (after Phase 1 validation) - ---- - -## Table of Contents - -1. [Overview](#overview) -2. [Phase 2 Scope](#phase-2-scope) -3. [Backend Enhancements](#backend-enhancements) -4. [Frontend Implementation](#frontend-implementation) -5. [Testing Strategy](#testing-strategy) -6. [Deployment Plan](#deployment-plan) -7. [Validation Criteria](#validation-criteria) - ---- - -## Overview - -### Objectives - -Build upon Phase 1 foundation to deliver: -- Temporary quota overrides for exceptional cases -- Soft limit warnings (80%, 90%) before hard blocks -- Email domain-based quota matching -- Admin UI for comprehensive quota management -- Event viewer and analytics -- Quota inspector for troubleshooting - -### Prerequisites - -**Phase 1 must be complete and validated:** -- ✅ DynamoDB tables deployed -- ✅ Core quota resolution working -- ✅ Hard limit blocking functional -- ✅ Admin CRUD APIs operational -- ✅ Cache achieving >80% hit rate -- ✅ Zero table scans in production - ---- - -## Phase 2 Scope - -### ✅ Included in Phase 2 - -**Backend Enhancements:** -- Quota override management (temporary exceptions) -- Soft limit warning system (80%, 90% thresholds) -- Email domain matching (exact, wildcard, regex) -- Enhanced event recording (warnings, overrides) -- Deduplication logic for warning events - -**Frontend Implementation:** -- Admin dashboard layout -- Tier management UI (CRUD) -- Assignment management UI (CRUD) -- Override management UI (create, list, disable) -- User quota inspector (search by user ID) -- Event viewer (filter by user, tier, type) -- Real-time usage display - -**Analytics & Monitoring:** -- Tier usage statistics -- Event frequency charts -- Top quota consumers -- Warning/block trends - -### ❌ Out of Scope - -- Automated quota adjustment (ML-based) -- Usage forecasting -- Multi-tenant quota isolation -- Quota pooling (shared quotas across users) - ---- - -## Backend Enhancements - -### 1. Quota Override Support - -**Already designed in Phase 1 schema** - now implement the logic. - -#### Update Models - -**File:** `backend/src/agentcore/quota/models.py` (additions) - -```python -class QuotaOverride(BaseModel): - """Temporary quota override for a user""" - model_config = ConfigDict(populate_by_name=True) - - override_id: str = Field(..., alias="overrideId") - user_id: str = Field(..., alias="userId") - - override_type: Literal["custom_limit", "unlimited"] = Field( - ..., - alias="overrideType" - ) - - # Custom limits (required if override_type == "custom_limit") - monthly_cost_limit: Optional[float] = Field(None, alias="monthlyCostLimit", gt=0) - daily_cost_limit: Optional[float] = Field(None, alias="dailyCostLimit", gt=0) - - # Temporal bounds - valid_from: str = Field(..., alias="validFrom") - valid_until: str = Field(..., alias="validUntil") - - # Metadata - reason: str = Field(..., description="Justification for override") - created_by: str = Field(..., alias="createdBy") - created_at: str = Field(..., alias="createdAt") - enabled: bool = Field(default=True) - - @field_validator('monthly_cost_limit') - @classmethod - def validate_custom_limit(cls, v, info): - """Ensure custom_limit type has a limit specified""" - if info.data.get('override_type') == 'custom_limit' and v is None: - raise ValueError("monthly_cost_limit required for custom_limit type") - return v -``` - -#### Update Repository - -**File:** `backend/src/agentcore/quota/repository.py` (additions) - -```python -# ========== Quota Overrides ========== - -async def create_override(self, override: QuotaOverride) -> QuotaOverride: - """Create a new quota override""" - item = { - "PK": f"OVERRIDE#{override.override_id}", - "SK": "METADATA", - "GSI4PK": f"USER#{override.user_id}", - "GSI4SK": f"VALID_UNTIL#{override.valid_until}", - **override.model_dump(by_alias=True, exclude_none=True) - } - - try: - self.table.put_item(Item=item) - return override - except ClientError as e: - logger.error(f"Error creating override: {e}") - raise - -async def get_active_override(self, user_id: str) -> Optional[QuotaOverride]: - """Get active override for user (valid and enabled)""" - now = datetime.utcnow().isoformat() + 'Z' - - try: - response = self.table.query( - IndexName="UserOverrideIndex", - KeyConditionExpression="GSI4PK = :pk AND GSI4SK >= :now", - ExpressionAttributeValues={ - ":pk": f"USER#{user_id}", - ":now": f"VALID_UNTIL#{now}" - }, - ScanIndexForward=False, # Latest first - Limit=1 - ) - - items = response.get('Items', []) - if not items: - return None - - item = items[0] - for key in ['PK', 'SK', 'GSI4PK', 'GSI4SK']: - item.pop(key, None) - - override = QuotaOverride(**item) - - # Check if override is currently valid - if override.enabled and override.valid_from <= now <= override.valid_until: - return override - - return None - except ClientError as e: - logger.error(f"Error getting active override for {user_id}: {e}") - return None -``` - -#### Update Resolver - -**File:** `backend/src/agentcore/quota/resolver.py` (modify `_resolve_from_db`) - -```python -async def _resolve_from_db(self, user: User) -> Optional[ResolvedQuota]: - """ - Resolve quota from database using targeted GSI queries. - - Priority order (Phase 2): - 1. Active override (highest priority) ← NEW - 2. Direct user assignment - 3. JWT role assignment - 4. Email domain assignment ← NEW - 5. Default tier - """ - - # 1. Check for active override (highest priority) - override = await self.repository.get_active_override(user.user_id) - if override: - tier = self._override_to_tier(override) - return ResolvedQuota( - user_id=user.user_id, - tier=tier, - matched_by="override", - assignment=None, # Overrides don't have assignments - override=override - ) - - # 2. Check for direct user assignment - # ... (same as Phase 1) - - # 3. Check JWT role assignments - # ... (same as Phase 1) - - # 4. Check email domain assignments (NEW) - if user.email and '@' in user.email: - domain_assignments = await self._get_cached_domain_assignments() - user_domain = user.email.split('@')[1] - - # Sort by priority and find matching domain - for assignment in sorted(domain_assignments, key=lambda a: a.priority, reverse=True): - if assignment.enabled and self._matches_email_domain(user_domain, assignment.email_domain): - tier = await self.repository.get_tier(assignment.tier_id) - if tier and tier.enabled: - return ResolvedQuota( - user_id=user.user_id, - tier=tier, - matched_by=f"email_domain:{assignment.email_domain}", - assignment=assignment - ) - - # 5. Fall back to default tier - # ... (same as Phase 1) - -def _override_to_tier(self, override: QuotaOverride) -> QuotaTier: - """Convert override to a tier for use in quota checking""" - if override.override_type == "unlimited": - return QuotaTier( - tier_id=f"override_{override.override_id}", - tier_name="Unlimited Override", - monthly_cost_limit=float('inf'), - action_on_limit="warn", - created_at=override.created_at, - updated_at=override.created_at, - created_by=override.created_by - ) - else: # custom_limit - return QuotaTier( - tier_id=f"override_{override.override_id}", - tier_name="Custom Override", - monthly_cost_limit=override.monthly_cost_limit or 0, - daily_cost_limit=override.daily_cost_limit, - action_on_limit="block", - soft_limit_percentage=80.0, # Default - created_at=override.created_at, - updated_at=override.created_at, - created_by=override.created_by - ) - -async def _get_cached_domain_assignments(self) -> list: - """Get domain assignments with separate cache (expensive query)""" - if self._domain_assignments_cache: - assignments, cached_at = self._domain_assignments_cache - if datetime.utcnow() - cached_at < timedelta(seconds=self.cache_ttl): - return assignments - - # Cache miss - query domain assignments - assignments = await self.repository.list_assignments_by_type( - assignment_type="email_domain", - enabled_only=True - ) - self._domain_assignments_cache = (assignments, datetime.utcnow()) - return assignments - -def _matches_email_domain(self, user_domain: str, pattern: str) -> bool: - """ - Enhanced email domain matching. - - Supported patterns: - - Exact: "university.edu" - - Wildcard subdomain: "*.university.edu" - - Regex: "regex:^(cs|eng)\\.university\\.edu$" - - Multiple: "university.edu,college.edu" - """ - if not pattern: - return False - - # Exact match - if pattern == user_domain: - return True - - # Wildcard subdomain (*.example.com) - if pattern.startswith('*.'): - base_domain = pattern[2:] - return user_domain == base_domain or user_domain.endswith('.' + base_domain) - - # Regex pattern (prefix with "regex:") - if pattern.startswith('regex:'): - import re - regex_pattern = pattern[6:] - try: - return bool(re.match(regex_pattern, user_domain)) - except re.error: - logger.error(f"Invalid regex pattern: {regex_pattern}") - return False - - # Multiple domains (comma-separated) - if ',' in pattern: - domains = [d.strip() for d in pattern.split(',')] - return any(self._matches_email_domain(user_domain, d) for d in domains) - - return False -``` - -### 2. Soft Limit Warnings - -#### Update Models - -**File:** `backend/src/agentcore/quota/models.py` (modifications) - -```python -class QuotaTier(BaseModel): - """A quota tier configuration""" - # ... existing fields ... - - # Soft limit configuration (Phase 2) - soft_limit_percentage: float = Field( - default=80.0, - alias="softLimitPercentage", - ge=0, - le=100, - description="Percentage at which warnings start" - ) - - # Hard limit behavior (Phase 2: warn or block) - action_on_limit: Literal["block", "warn"] = Field( - default="block", - alias="actionOnLimit" - ) - -class QuotaEvent(BaseModel): - """Track quota enforcement events (Phase 2: all event types)""" - # ... existing fields ... - - event_type: Literal["warning", "block", "reset", "override_applied"] = Field( - ..., - alias="eventType" - ) - -class QuotaCheckResult(BaseModel): - """Result of quota check""" - # ... existing fields ... - - warning_level: Optional[Literal["none", "80%", "90%"]] = Field( - None, - alias="warningLevel" - ) -``` - -#### Update Checker - -**File:** `backend/src/agentcore/quota/checker.py` (replace Phase 1 version) - -```python -async def check_quota(self, user: User) -> QuotaCheckResult: - """ - Check if user is within quota limits (Phase 2: soft + hard limits). - - Returns QuotaCheckResult with: - - allowed: bool - whether request should proceed - - message: str - explanation - - tier: QuotaTier - applicable tier - - current_usage, quota_limit, percentage_used, remaining - - warning_level: "none", "80%", "90%" - """ - # Resolve user's quota tier - resolved = await self.resolver.resolve_user_quota(user) - - if not resolved: - # No quota configured - allow by default - return QuotaCheckResult( - allowed=True, - message="No quota configured", - current_usage=0.0, - percentage_used=0.0, - warning_level="none" - ) - - tier = resolved.tier - - # Handle unlimited tier - if tier.monthly_cost_limit == float('inf'): - return QuotaCheckResult( - allowed=True, - message="Unlimited quota", - tier=tier, - current_usage=0.0, - quota_limit=float('inf'), - percentage_used=0.0, - warning_level="none" - ) - - # Get current usage for the period - period = self._get_current_period(tier.period_type) - summary = await self.cost_aggregator.get_user_cost_summary( - user_id=user.user_id, - period=period - ) - - current_usage = summary.total_cost - limit = tier.monthly_cost_limit - percentage_used = (current_usage / limit * 100) if limit > 0 else 0 - remaining = max(0, limit - current_usage) - - # Determine warning level (Phase 2) - warning_level = "none" - soft_limit_percentage = tier.soft_limit_percentage - - if percentage_used >= 90: - warning_level = "90%" - elif percentage_used >= soft_limit_percentage: - warning_level = f"{int(soft_limit_percentage)}%" - - # Record warning events if thresholds crossed (Phase 2) - if warning_level != "none": - await self.event_recorder.record_warning_if_needed( - user=user, - tier=tier, - current_usage=current_usage, - limit=limit, - percentage_used=percentage_used, - threshold=warning_level - ) - - # Check hard limit - if current_usage >= limit: - if tier.action_on_limit == "block": - # Record block event - await self.event_recorder.record_block( - user=user, - tier=tier, - current_usage=current_usage, - limit=limit, - percentage_used=percentage_used - ) - - return QuotaCheckResult( - allowed=False, - message=f"Quota exceeded: ${current_usage:.2f} / ${limit:.2f}", - tier=tier, - current_usage=current_usage, - quota_limit=limit, - percentage_used=percentage_used, - remaining=0.0, - warning_level=warning_level - ) - else: # warn only (Phase 2) - return QuotaCheckResult( - allowed=True, - message=f"Warning: Quota limit reached (${current_usage:.2f} / ${limit:.2f})", - tier=tier, - current_usage=current_usage, - quota_limit=limit, - percentage_used=percentage_used, - remaining=0.0, - warning_level=warning_level - ) - - # Within limits - message = "Within quota" - if warning_level != "none": - message = f"Warning: {warning_level} quota used (${current_usage:.2f} / ${limit:.2f})" - - return QuotaCheckResult( - allowed=True, - message=message, - tier=tier, - current_usage=current_usage, - quota_limit=limit, - percentage_used=percentage_used, - remaining=remaining, - warning_level=warning_level - ) -``` - -#### Update Event Recorder - -**File:** `backend/src/agentcore/quota/event_recorder.py` (add methods) - -```python -async def record_warning_if_needed( - self, - user: User, - tier: QuotaTier, - current_usage: float, - limit: float, - percentage_used: float, - threshold: str -): - """ - Record warning event if user hasn't been warned recently. - Prevents duplicate warnings within 60 minutes. - """ - # Check for recent warning of this type - recent_warning = await self.repository.get_recent_event( - user_id=user.user_id, - event_type="warning", - within_minutes=60 - ) - - if recent_warning and recent_warning.metadata: - # Don't record if we've already warned about this threshold - if recent_warning.metadata.get("threshold") == threshold: - logger.debug(f"Skipping duplicate warning for user {user.user_id} at {threshold}") - return - - # Record new warning - event = QuotaEvent( - event_id=str(uuid.uuid4()), - user_id=user.user_id, - tier_id=tier.tier_id, - event_type="warning", - current_usage=current_usage, - quota_limit=limit, - percentage_used=percentage_used, - timestamp=datetime.utcnow().isoformat() + 'Z', - metadata={ - "threshold": threshold, - "tier_name": tier.tier_name - } - ) - - try: - await self.repository.record_event(event) - logger.info(f"Recorded warning event for user {user.user_id} at {threshold}") - except Exception as e: - logger.error(f"Failed to record warning event: {e}") - -async def record_override_applied( - self, - user: User, - override_id: str, - tier: QuotaTier -): - """Record when an override is applied""" - event = QuotaEvent( - event_id=str(uuid.uuid4()), - user_id=user.user_id, - tier_id=tier.tier_id, - event_type="override_applied", - current_usage=0.0, - quota_limit=tier.monthly_cost_limit, - percentage_used=0.0, - timestamp=datetime.utcnow().isoformat() + 'Z', - metadata={ - "override_id": override_id, - "tier_name": tier.tier_name - } - ) - - try: - await self.repository.record_event(event) - logger.info(f"Recorded override applied for user {user.user_id}") - except Exception as e: - logger.error(f"Failed to record override event: {e}") -``` - -### 3. Admin API - Override Routes - -**File:** `backend/src/apis/app_api/admin/quota/routes.py` (additions) - -```python -# ========== Quota Overrides ========== - -@router.post("/overrides", response_model=QuotaOverride, status_code=status.HTTP_201_CREATED) -async def create_override( - override_data: QuotaOverrideCreate, - admin_user: User = Depends(get_current_user), - service: QuotaAdminService = Depends(get_quota_service) -): - """Create a new quota override (admin only)""" - try: - override = await service.create_override(override_data, admin_user) - return override - except ValueError as e: - raise HTTPException(status_code=400, detail=str(e)) - -@router.get("/overrides", response_model=List[QuotaOverride]) -async def list_overrides( - user_id: Optional[str] = None, - active_only: bool = False, - admin_user: User = Depends(get_current_user), - service: QuotaAdminService = Depends(get_quota_service) -): - """List quota overrides (admin only)""" - overrides = await service.list_overrides( - user_id=user_id, - active_only=active_only - ) - return overrides - -@router.get("/overrides/{override_id}", response_model=QuotaOverride) -async def get_override( - override_id: str, - admin_user: User = Depends(get_current_user), - service: QuotaAdminService = Depends(get_quota_service) -): - """Get quota override by ID (admin only)""" - override = await service.get_override(override_id) - if not override: - raise HTTPException(status_code=404, detail=f"Override {override_id} not found") - return override - -@router.patch("/overrides/{override_id}", response_model=QuotaOverride) -async def update_override( - override_id: str, - updates: QuotaOverrideUpdate, - admin_user: User = Depends(get_current_user), - service: QuotaAdminService = Depends(get_quota_service) -): - """Update quota override (admin only)""" - override = await service.update_override(override_id, updates, admin_user) - if not override: - raise HTTPException(status_code=404, detail=f"Override {override_id} not found") - return override - -@router.delete("/overrides/{override_id}", status_code=status.HTTP_204_NO_CONTENT) -async def delete_override( - override_id: str, - admin_user: User = Depends(get_current_user), - service: QuotaAdminService = Depends(get_quota_service) -): - """Delete quota override (admin only)""" - success = await service.delete_override(override_id, admin_user) - if not success: - raise HTTPException(status_code=404, detail=f"Override {override_id} not found") - -# ========== Quota Events ========== - -@router.get("/events", response_model=List[QuotaEvent]) -async def get_events( - user_id: Optional[str] = None, - tier_id: Optional[str] = None, - event_type: Optional[str] = None, - limit: int = 50, - admin_user: User = Depends(get_current_user), - service: QuotaAdminService = Depends(get_quota_service) -): - """Get quota events with filters (admin only)""" - events = await service.get_events( - user_id=user_id, - tier_id=tier_id, - event_type=event_type, - limit=limit - ) - return events -``` - -### 4. CDK Infrastructure Update - -**File:** `cdk/lib/stacks/quota-stack.ts` (add GSI4 for overrides) - -```typescript -// GSI4: UserOverrideIndex (Phase 2) -// Query active overrides for a user -this.userQuotasTable.addGlobalSecondaryIndex({ - indexName: 'UserOverrideIndex', - partitionKey: { - name: 'GSI4PK', - type: dynamodb.AttributeType.STRING, - }, - sortKey: { - name: 'GSI4SK', - type: dynamodb.AttributeType.STRING, - }, - projectionType: dynamodb.ProjectionType.ALL, -}); -``` - -**Note:** This GSI was planned in Phase 1 schema but not created. Add it now. - ---- - -## Frontend Implementation - -### Directory Structure - -``` -frontend/ai.client/src/app/ -├── admin/ # ← NEW: Admin module -│ ├── quota/ # ← NEW: Quota management -│ │ ├── pages/ -│ │ │ ├── quota-dashboard.page.ts -│ │ │ ├── tier-list.page.ts -│ │ │ ├── tier-editor.page.ts -│ │ │ ├── assignment-list.page.ts -│ │ │ ├── assignment-editor.page.ts -│ │ │ ├── override-list.page.ts -│ │ │ ├── override-editor.page.ts -│ │ │ ├── quota-inspector.page.ts -│ │ │ └── event-viewer.page.ts -│ │ ├── components/ -│ │ │ ├── tier-card.component.ts -│ │ │ ├── assignment-card.component.ts -│ │ │ ├── override-card.component.ts -│ │ │ ├── usage-meter.component.ts -│ │ │ ├── event-timeline.component.ts -│ │ │ └── quota-form.component.ts -│ │ ├── services/ -│ │ │ ├── quota-http.service.ts -│ │ │ └── quota-state.service.ts -│ │ └── models/ -│ │ └── quota.models.ts -│ └── admin-routing.module.ts -└── app-routing.module.ts -``` - -### Models - -**File:** `frontend/ai.client/src/app/admin/quota/models/quota.models.ts` - -```typescript -export type QuotaAssignmentType = 'direct_user' | 'jwt_role' | 'email_domain' | 'default_tier'; -export type ActionOnLimit = 'block' | 'warn'; -export type OverrideType = 'custom_limit' | 'unlimited'; -export type EventType = 'warning' | 'block' | 'reset' | 'override_applied'; -export type WarningLevel = 'none' | '80%' | '90%'; - -export interface QuotaTier { - tierId: string; - tierName: string; - description?: string; - monthlyCostLimit: number; - dailyCostLimit?: number; - periodType: 'daily' | 'monthly'; - softLimitPercentage: number; - actionOnLimit: ActionOnLimit; - enabled: boolean; - createdAt: string; - updatedAt: string; - createdBy: string; -} - -export interface QuotaAssignment { - assignmentId: string; - tierId: string; - assignmentType: QuotaAssignmentType; - userId?: string; - jwtRole?: string; - emailDomain?: string; - priority: number; - enabled: boolean; - createdAt: string; - updatedAt: string; - createdBy: string; -} - -export interface QuotaOverride { - overrideId: string; - userId: string; - overrideType: OverrideType; - monthlyCostLimit?: number; - dailyCostLimit?: number; - validFrom: string; - validUntil: string; - reason: string; - createdBy: string; - createdAt: string; - enabled: boolean; -} - -export interface QuotaEvent { - eventId: string; - userId: string; - tierId: string; - eventType: EventType; - currentUsage: number; - quotaLimit: number; - percentageUsed: number; - timestamp: string; - metadata?: Record; -} - -export interface UserQuotaInfo { - userId: string; - tier?: QuotaTier; - matchedBy: string; - assignment?: QuotaAssignment; - override?: QuotaOverride; - currentUsage: number; - quotaLimit?: number; - percentageUsed: number; - remaining?: number; - recentEvents: QuotaEvent[]; -} - -// Request models -export interface QuotaTierCreate { - tierId: string; - tierName: string; - description?: string; - monthlyCostLimit: number; - dailyCostLimit?: number; - periodType?: 'daily' | 'monthly'; - softLimitPercentage?: number; - actionOnLimit?: ActionOnLimit; -} - -export interface QuotaAssignmentCreate { - tierId: string; - assignmentType: QuotaAssignmentType; - userId?: string; - jwtRole?: string; - emailDomain?: string; - priority?: number; -} - -export interface QuotaOverrideCreate { - userId: string; - overrideType: OverrideType; - monthlyCostLimit?: number; - dailyCostLimit?: number; - validFrom: string; - validUntil: string; - reason: string; -} -``` - -### HTTP Service - -**File:** `frontend/ai.client/src/app/admin/quota/services/quota-http.service.ts` - -```typescript -import { Injectable, inject } from '@angular/core'; -import { HttpClient, HttpParams } from '@angular/common/http'; -import { Observable } from 'rxjs'; -import { environment } from '../../../../environments/environment'; -import { - QuotaTier, - QuotaAssignment, - QuotaOverride, - QuotaEvent, - UserQuotaInfo, - QuotaTierCreate, - QuotaAssignmentCreate, - QuotaOverrideCreate, -} from '../models/quota.models'; - -@Injectable({ - providedIn: 'root', -}) -export class QuotaHttpService { - private http = inject(HttpClient); - private baseUrl = `${environment.apiUrl}/api/admin/quota`; - - // ========== Tiers ========== - - listTiers(enabledOnly: boolean = false): Observable { - const params = new HttpParams().set('enabled_only', enabledOnly); - return this.http.get(`${this.baseUrl}/tiers`, { params }); - } - - getTier(tierId: string): Observable { - return this.http.get(`${this.baseUrl}/tiers/${tierId}`); - } - - createTier(tierData: QuotaTierCreate): Observable { - return this.http.post(`${this.baseUrl}/tiers`, tierData); - } - - updateTier(tierId: string, updates: Partial): Observable { - return this.http.patch(`${this.baseUrl}/tiers/${tierId}`, updates); - } - - deleteTier(tierId: string): Observable { - return this.http.delete(`${this.baseUrl}/tiers/${tierId}`); - } - - // ========== Assignments ========== - - listAssignments( - assignmentType?: string, - enabledOnly: boolean = false - ): Observable { - let params = new HttpParams().set('enabled_only', enabledOnly); - if (assignmentType) { - params = params.set('assignment_type', assignmentType); - } - return this.http.get(`${this.baseUrl}/assignments`, { params }); - } - - getAssignment(assignmentId: string): Observable { - return this.http.get(`${this.baseUrl}/assignments/${assignmentId}`); - } - - createAssignment(assignmentData: QuotaAssignmentCreate): Observable { - return this.http.post(`${this.baseUrl}/assignments`, assignmentData); - } - - updateAssignment( - assignmentId: string, - updates: Partial - ): Observable { - return this.http.patch( - `${this.baseUrl}/assignments/${assignmentId}`, - updates - ); - } - - deleteAssignment(assignmentId: string): Observable { - return this.http.delete(`${this.baseUrl}/assignments/${assignmentId}`); - } - - // ========== Overrides ========== - - listOverrides(userId?: string, activeOnly: boolean = false): Observable { - let params = new HttpParams().set('active_only', activeOnly); - if (userId) { - params = params.set('user_id', userId); - } - return this.http.get(`${this.baseUrl}/overrides`, { params }); - } - - createOverride(overrideData: QuotaOverrideCreate): Observable { - return this.http.post(`${this.baseUrl}/overrides`, overrideData); - } - - updateOverride( - overrideId: string, - updates: Partial - ): Observable { - return this.http.patch(`${this.baseUrl}/overrides/${overrideId}`, updates); - } - - deleteOverride(overrideId: string): Observable { - return this.http.delete(`${this.baseUrl}/overrides/${overrideId}`); - } - - // ========== User Info ========== - - getUserQuotaInfo(userId: string): Observable { - return this.http.get(`${this.baseUrl}/users/${userId}`); - } - - // ========== Events ========== - - getEvents( - userId?: string, - tierId?: string, - eventType?: string, - limit: number = 50 - ): Observable { - let params = new HttpParams().set('limit', limit); - if (userId) params = params.set('user_id', userId); - if (tierId) params = params.set('tier_id', tierId); - if (eventType) params = params.set('event_type', eventType); - - return this.http.get(`${this.baseUrl}/events`, { params }); - } -} -``` - -### State Service - -**File:** `frontend/ai.client/src/app/admin/quota/services/quota-state.service.ts` - -```typescript -import { Injectable, inject, signal, computed } from '@angular/core'; -import { QuotaHttpService } from './quota-http.service'; -import { QuotaTier, QuotaAssignment, QuotaOverride } from '../models/quota.models'; - -@Injectable({ - providedIn: 'root', -}) -export class QuotaStateService { - private http = inject(QuotaHttpService); - - // State - tiers = signal([]); - assignments = signal([]); - overrides = signal([]); - loading = signal(false); - - // Computed - enabledTiers = computed(() => this.tiers().filter((t) => t.enabled)); - tierCount = computed(() => this.tiers().length); - assignmentCount = computed(() => this.assignments().length); - - // ========== Tiers ========== - - loadTiers(enabledOnly: boolean = false): void { - this.loading.set(true); - this.http.listTiers(enabledOnly).subscribe({ - next: (tiers) => { - this.tiers.set(tiers); - this.loading.set(false); - }, - error: () => this.loading.set(false), - }); - } - - addTier(tier: QuotaTier): void { - this.tiers.update((tiers) => [...tiers, tier]); - } - - updateTier(tierId: string, updates: Partial): void { - this.tiers.update((tiers) => - tiers.map((t) => (t.tierId === tierId ? { ...t, ...updates } : t)) - ); - } - - removeTier(tierId: string): void { - this.tiers.update((tiers) => tiers.filter((t) => t.tierId !== tierId)); - } - - // ========== Assignments ========== - - loadAssignments(assignmentType?: string, enabledOnly: boolean = false): void { - this.loading.set(true); - this.http.listAssignments(assignmentType, enabledOnly).subscribe({ - next: (assignments) => { - this.assignments.set(assignments); - this.loading.set(false); - }, - error: () => this.loading.set(false), - }); - } - - addAssignment(assignment: QuotaAssignment): void { - this.assignments.update((assignments) => [...assignments, assignment]); - } - - updateAssignment(assignmentId: string, updates: Partial): void { - this.assignments.update((assignments) => - assignments.map((a) => (a.assignmentId === assignmentId ? { ...a, ...updates } : a)) - ); - } - - removeAssignment(assignmentId: string): void { - this.assignments.update((assignments) => - assignments.filter((a) => a.assignmentId !== assignmentId) - ); - } - - // ========== Overrides ========== - - loadOverrides(userId?: string, activeOnly: boolean = false): void { - this.loading.set(true); - this.http.listOverrides(userId, activeOnly).subscribe({ - next: (overrides) => { - this.overrides.set(overrides); - this.loading.set(false); - }, - error: () => this.loading.set(false), - }); - } - - addOverride(override: QuotaOverride): void { - this.overrides.update((overrides) => [...overrides, override]); - } - - removeOverride(overrideId: string): void { - this.overrides.update((overrides) => - overrides.filter((o) => o.overrideId !== overrideId) - ); - } -} -``` - -### Sample Page Component - -**File:** `frontend/ai.client/src/app/admin/quota/pages/tier-list.page.ts` - -```typescript -import { Component, ChangeDetectionStrategy, inject, signal, OnInit } from '@angular/core'; -import { Router } from '@angular/router'; -import { NgIcon, provideIcons } from '@ng-icons/core'; -import { heroPlusCircle, heroPencil, heroTrash } from '@ng-icons/heroicons/outline'; -import { QuotaStateService } from '../services/quota-state.service'; -import { QuotaHttpService } from '../services/quota-http.service'; -import { QuotaTier } from '../models/quota.models'; - -@Component({ - selector: 'app-tier-list', - changeDetection: ChangeDetectionStrategy.OnPush, - imports: [NgIcon], - providers: [provideIcons({ heroPlusCircle, heroPencil, heroTrash })], - host: { - class: 'block p-6', - }, - template: ` -
-

Quota Tiers

- -
- - @if (state.loading()) { -
Loading tiers...
- } - -
- @for (tier of state.tiers(); track tier.tierId) { -
-
-
-

{{ tier.tierName }}

-

{{ tier.tierId }}

-
- @if (!tier.enabled) { - - Disabled - - } -
- - @if (tier.description) { -

{{ tier.description }}

- } - -
-
- Monthly Limit: - \${{ tier.monthlyCostLimit.toFixed(2) }} -
- @if (tier.dailyCostLimit) { -
- Daily Limit: - \${{ tier.dailyCostLimit.toFixed(2) }} -
- } -
- Warning at: - {{ tier.softLimitPercentage }}% -
-
- Action: - - {{ tier.actionOnLimit }} - -
-
- -
- - -
-
- } -
- - @if (state.tiers().length === 0 && !state.loading()) { -
-

No tiers configured

-

Create your first tier to get started

-
- } - `, -}) -export class TierListPage implements OnInit { - state = inject(QuotaStateService); - private http = inject(QuotaHttpService); - private router = inject(Router); - - ngOnInit(): void { - this.state.loadTiers(); - } - - createTier(): void { - this.router.navigate(['/admin/quota/tiers/new']); - } - - editTier(tier: QuotaTier): void { - this.router.navigate(['/admin/quota/tiers', tier.tierId, 'edit']); - } - - deleteTier(tier: QuotaTier): void { - if (confirm(`Delete tier "${tier.tierName}"?`)) { - this.http.deleteTier(tier.tierId).subscribe({ - next: () => this.state.removeTier(tier.tierId), - error: (err) => alert(`Failed to delete tier: ${err.error?.detail || err.message}`), - }); - } - } -} -``` - ---- - -## Testing Strategy - -### Backend Tests - -**File:** `backend/tests/quota/test_soft_limits.py` - -```python -import pytest -from agents.main_agent.quota.checker import QuotaChecker -from agents.main_agent.quota.models import QuotaTier, QuotaCheckResult - -@pytest.mark.asyncio -async def test_soft_limit_warning_80_percent(checker, mock_resolver, mock_cost_aggregator): - """Test that 80% usage triggers warning""" - user = User(user_id="test", email="test@example.com", roles=[]) - - # Mock tier with 80% soft limit - tier = QuotaTier( - tier_id="test", - tier_name="Test", - monthly_cost_limit=100.0, - soft_limit_percentage=80.0, - action_on_limit="block", - enabled=True, - created_at="2025-01-01T00:00:00Z", - updated_at="2025-01-01T00:00:00Z", - created_by="test" - ) - - mock_resolver.resolve_user_quota.return_value = ResolvedQuota( - user_id="test", - tier=tier, - matched_by="default", - assignment=mock_assignment - ) - - # Mock 85% usage - mock_cost_aggregator.get_user_cost_summary.return_value = CostSummary(total_cost=85.0) - - result = await checker.check_quota(user) - - assert result.allowed is True - assert result.warning_level == "80%" - assert "Warning" in result.message - assert result.percentage_used == 85.0 -``` - -### Frontend Tests - -**File:** `frontend/ai.client/src/app/admin/quota/services/quota-http.service.spec.ts` - -```typescript -import { TestBed } from '@angular/core/testing'; -import { HttpClientTestingModule, HttpTestingController } from '@angular/common/http/testing'; -import { QuotaHttpService } from './quota-http.service'; - -describe('QuotaHttpService', () => { - let service: QuotaHttpService; - let httpMock: HttpTestingController; - - beforeEach(() => { - TestBed.configureTestingModule({ - imports: [HttpClientTestingModule], - providers: [QuotaHttpService], - }); - - service = TestBed.inject(QuotaHttpService); - httpMock = TestBed.inject(HttpTestingController); - }); - - afterEach(() => { - httpMock.verify(); - }); - - it('should list tiers', () => { - const mockTiers = [ - { tierId: 'basic', tierName: 'Basic', monthlyCostLimit: 100 }, - ]; - - service.listTiers().subscribe((tiers) => { - expect(tiers.length).toBe(1); - expect(tiers[0].tierId).toBe('basic'); - }); - - const req = httpMock.expectOne((req) => req.url.includes('/api/admin/quota/tiers')); - expect(req.request.method).toBe('GET'); - req.flush(mockTiers); - }); -}); -``` - ---- - -## Deployment Plan - -### Phase 2 Deployment Steps - -#### 1. Backend Deployment - -```bash -# 1. Deploy CDK infrastructure (add GSI4) -cd cdk -cdk deploy QuotaStack-dev - -# 2. Deploy backend code -cd backend -docker build -t quota-backend:phase2 . -docker push quota-backend:phase2 - -# 3. Run migrations (if any) -# No DB migrations needed - using DynamoDB - -# 4. Verify APIs -curl http://localhost:8000/api/admin/quota/overrides -curl http://localhost:8000/api/admin/quota/events -``` - -#### 2. Frontend Deployment - -```bash -# 1. Build frontend -cd frontend/ai.client -npm run build -- --configuration=production - -# 2. Deploy to hosting (S3, CloudFront, etc.) -aws s3 sync dist/ai-client s3://your-bucket/ - -# 3. Invalidate CDN cache -aws cloudfront create-invalidation --distribution-id XXXXX --paths "/*" -``` - -#### 3. Verification - -```bash -# Test override creation -curl -X POST http://localhost:8000/api/admin/quota/overrides \ - -H "Authorization: Bearer $TOKEN" \ - -d '{ - "userId": "test123", - "overrideType": "custom_limit", - "monthlyCostLimit": 1000.0, - "validFrom": "2025-12-17T00:00:00Z", - "validUntil": "2025-12-31T23:59:59Z", - "reason": "Testing" - }' - -# Test soft limit warning -# (requires user with 85% usage) -``` - ---- - -## Validation Criteria - -### Phase 2 Completion Checklist - -#### ✅ Backend - Overrides - -- [ ] Override creation stores to DynamoDB correctly -- [ ] GSI4 (UserOverrideIndex) allows O(1) active override lookup -- [ ] Overrides take priority over all other assignments -- [ ] Expired overrides are ignored -- [ ] Unlimited overrides allow infinite usage - -#### ✅ Backend - Soft Limits - -- [ ] 80% usage triggers warning event -- [ ] 90% usage triggers warning event -- [ ] Warning events deduplicated within 60 minutes -- [ ] Warnings don't block requests -- [ ] Tier `actionOnLimit=warn` allows over-limit usage with warning - -#### ✅ Backend - Email Domains - -- [ ] Exact domain match works (e.g., "university.edu") -- [ ] Wildcard subdomain match works (e.g., "*.university.edu") -- [ ] Regex pattern match works (e.g., "regex:^(cs|eng)\\.edu$") -- [ ] Multiple domain match works (e.g., "uni1.edu,uni2.edu") -- [ ] Domain assignments cached separately from user assignments - -#### ✅ Frontend - UI - -- [ ] Tier list displays all tiers -- [ ] Tier editor allows create/update/delete -- [ ] Assignment list displays all assignments -- [ ] Assignment editor supports all types (user, role, domain) -- [ ] Override list displays active and expired overrides -- [ ] Override editor validates date ranges -- [ ] Quota inspector resolves user quota correctly -- [ ] Event viewer displays recent events with filters - -#### ✅ Integration - -- [ ] End-to-end test: Create tier → Create assignment → User gets quota -- [ ] End-to-end test: Create override → User quota changes -- [ ] End-to-end test: User hits 85% → Warning event recorded -- [ ] End-to-end test: User hits 100% → Block event recorded - ---- - -**End of Phase 2 Specification** - -**Next Steps After Phase 2:** -- Monitor production metrics -- Gather admin feedback on UI -- Optimize cache hit rates -- Consider Phase 3 features (analytics, forecasting, automation) diff --git a/docs/QUOTA_QUICK_START.md b/docs/QUOTA_QUICK_START.md deleted file mode 100644 index 5601024e..00000000 --- a/docs/QUOTA_QUICK_START.md +++ /dev/null @@ -1,328 +0,0 @@ -# Quota Management - Quick Start Guide - -**Get up and running with Phase 1 Quota Management in 10 minutes.** - ---- - -## TL;DR - Fast Track - -```bash -# 1. Deploy DynamoDB tables -cd cdk -npm install -npm run deploy:dev - -# 2. Run tests -cd ../backend -pytest tests/quota/ -v - -# 3. Start backend -cd src -python -m uvicorn apis.app_api.main:app --reload --port 8000 - -# 4. Create test data (needs admin token) -curl -X POST http://localhost:8000/api/admin/quota/tiers \ - -H "Authorization: Bearer $ADMIN_TOKEN" \ - -H "Content-Type: application/json" \ - -d '{"tierId":"basic","tierName":"Basic","monthlyCostLimit":100,"enabled":true}' -``` - ---- - -## What Was Implemented - -### Phase 1 Scope ✅ - -1. **DynamoDB Tables** - - `UserQuotas` table with 3 GSIs for fast lookups - - `QuotaEvents` table for tracking block events - - PAY_PER_REQUEST billing for cost optimization - -2. **Backend Services** - - `QuotaResolver` - Resolves user quotas with 5-min cache - - `QuotaChecker` - Enforces hard limits (blocks requests) - - `QuotaRepository` - DynamoDB access (ZERO table scans) - - `QuotaEventRecorder` - Tracks quota violations - -3. **Admin API** - - `/api/admin/quota/tiers` - Manage quota tiers - - `/api/admin/quota/assignments` - Manage user/role assignments - - `/api/admin/quota/users/{id}` - Inspect user quota status - -4. **CDK Infrastructure** - - TypeScript CDK stack for DynamoDB - - Dev/prod environment support - - Automated deployment scripts - -5. **Testing** - - 19 unit tests (10 resolver + 9 checker) - - Mock-based testing with pytest - - Comprehensive coverage - ---- - -## Key Features - -### Quota Resolution Priority - -1. **Direct User Assignment** (priority ~300) - Highest -2. **JWT Role Assignment** (priority ~200) - Medium -3. **Default Tier** (priority ~100) - Fallback - -### Performance - -- **Cache Hit**: <5ms resolution -- **Cache Miss**: 50-200ms (2-6 DynamoDB queries) -- **Cache TTL**: 5 minutes -- **Expected Hit Rate**: 90% - -### Database Efficiency - -- **Zero Table Scans** - All queries use primary keys or GSIs -- **Targeted Lookups** - O(1) for user, O(log n) for role -- **Pay-per-request** - Only pay for what you use - ---- - -## File Structure - -### Backend -``` -backend/src/ -├── agentcore/quota/ # Core logic -│ ├── models.py # 127 lines -│ ├── repository.py # 455 lines -│ ├── resolver.py # 128 lines -│ ├── checker.py # 128 lines -│ └── event_recorder.py # 47 lines -│ -└── apis/app_api/admin/quota/ # Admin API - ├── models.py # 91 lines - ├── service.py # 333 lines - └── routes.py # 431 lines -``` - -### CDK -``` -cdk/ -├── lib/stacks/quota-stack.ts # 152 lines -├── bin/quota-app.ts # 34 lines -└── cdk.json # 50 lines -``` - -### Tests -``` -backend/tests/quota/ -├── test_resolver.py # 10 tests -└── test_checker.py # 9 tests -``` - ---- - -## API Examples - -### Create a Tier - -```bash -curl -X POST http://localhost:8000/api/admin/quota/tiers \ - -H "Authorization: Bearer $ADMIN_TOKEN" \ - -H "Content-Type: application/json" \ - -d '{ - "tierId": "premium", - "tierName": "Premium Tier", - "description": "For premium users", - "monthlyCostLimit": 500.0, - "dailyCostLimit": 20.0, - "periodType": "monthly", - "enabled": true - }' -``` - -### Create Role Assignment - -```bash -curl -X POST http://localhost:8000/api/admin/quota/assignments \ - -H "Authorization: Bearer $ADMIN_TOKEN" \ - -H "Content-Type: application/json" \ - -d '{ - "tierId": "premium", - "assignmentType": "jwt_role", - "jwtRole": "Faculty", - "priority": 200, - "enabled": true - }' -``` - -### Check User Quota - -```bash -curl http://localhost:8000/api/admin/quota/users/user123?email=test@example.com&roles=Faculty \ - -H "Authorization: Bearer $ADMIN_TOKEN" -``` - ---- - -## Validation Steps - -### 1. Verify Tables Exist - -```bash -aws dynamodb list-tables --query "TableNames[?contains(@, 'Quota')]" -``` - -Expected: `["QuotaEvents-dev", "UserQuotas-dev"]` - -### 2. Run Tests - -```bash -cd backend -pytest tests/quota/ -v -``` - -Expected: `19 passed` - -### 3. Test Quota Resolution - -```python -from agents.main_agent.quota.repository import QuotaRepository -from agents.main_agent.quota.resolver import QuotaResolver -from apis.shared.auth.models import User -import asyncio - -repo = QuotaRepository(table_name="UserQuotas-dev") -resolver = QuotaResolver(repository=repo) - -user = User(user_id="test", email="test@example.com", name="Test", roles=[]) -resolved = asyncio.run(resolver.resolve_user_quota(user)) -print(f"Tier: {resolved.tier.tier_name if resolved else 'None'}") -``` - -### 4. Verify No Table Scans - -```bash -aws cloudwatch get-metric-statistics \ - --namespace AWS/DynamoDB \ - --metric-name ConsumedReadCapacityUnits \ - --dimensions Name=TableName,Value=UserQuotas-dev Name=Operation,Value=Scan \ - --start-time $(date -u -v-1H +%Y-%m-%dT%H:%M:%S) \ - --end-time $(date -u +%Y-%m-%dT%H:%M:%S) \ - --period 3600 \ - --statistics Sum -``` - -Expected: Empty array (no scans) - ---- - -## Common Commands - -```bash -# Deploy infrastructure -cd cdk && npm run deploy:dev - -# View infrastructure changes -cd cdk && npm run diff:dev - -# Destroy infrastructure (CAUTION!) -cd cdk && npm run destroy:dev - -# Run all tests -cd backend && pytest tests/quota/ -v - -# Start backend -cd backend/src && python -m uvicorn apis.app_api.main:app --reload - -# Check table status -aws dynamodb describe-table --table-name UserQuotas-dev - -# List all tiers -curl http://localhost:8000/api/admin/quota/tiers -H "Authorization: Bearer $TOKEN" -``` - ---- - -## What's NOT Included (Phase 2) - -- ❌ Soft limit warnings (80%, 90%) -- ❌ Quota overrides (temporary adjustments) -- ❌ Email domain matching -- ❌ Frontend UI -- ❌ Enhanced analytics -- ❌ Notification system - -See `QUOTA_MANAGEMENT_PHASE2_SPEC.md` for Phase 2 features. - ---- - -## Documentation - -- **Full Spec**: `docs/QUOTA_MANAGEMENT_PHASE1_SPEC.md` (1,912 lines) -- **Implementation**: `docs/QUOTA_MANAGEMENT_IMPLEMENTATION.md` (full details) -- **Validation Guide**: `docs/QUOTA_VALIDATION_GUIDE.md` (step-by-step) -- **This File**: `docs/QUOTA_QUICK_START.md` (quick reference) - ---- - -## Troubleshooting - -### CDK Bootstrap Required -```bash -cdk bootstrap aws:/// -``` - -### Module Import Error -```bash -cd backend/src -export PYTHONPATH=$PWD:$PYTHONPATH -``` - -### Permission Denied -- Check AWS credentials: `aws sts get-caller-identity` -- Verify IAM permissions for DynamoDB and CloudFormation - -### Admin API 403 -- Verify JWT token includes admin role -- Check token expiration - ---- - -## Cost Estimate - -**Development:** -- DynamoDB: ~$0.05/month -- CloudWatch: Free tier -- **Total: <$0.10/month** - -**Production (100K users, 10M events/month):** -- DynamoDB: ~$4/month -- Storage: ~$0.03/month -- **Total: ~$4/month** - ---- - -## Success Checklist - -- [ ] DynamoDB tables deployed with GSIs -- [ ] All 19 unit tests passing -- [ ] Admin API CRUD operations work -- [ ] Quota resolution working with priority -- [ ] No table scans in CloudWatch -- [ ] Cache reduces database queries - ---- - -## Next Steps - -1. ✅ Deploy to dev environment -2. ✅ Run validation tests -3. ✅ Create initial tiers (basic, premium, enterprise) -4. ✅ Create default tier assignment -5. 🚀 Integrate QuotaChecker into chat middleware -6. 📊 Set up CloudWatch dashboards -7. 📋 Plan Phase 2 features - ---- - -**Ready to deploy?** Follow the validation guide for step-by-step instructions. - -**Questions?** Check the full implementation docs or raise an issue. diff --git a/docs/QUOTA_VALIDATION_GUIDE.md b/docs/QUOTA_VALIDATION_GUIDE.md deleted file mode 100644 index 8b8e8f9a..00000000 --- a/docs/QUOTA_VALIDATION_GUIDE.md +++ /dev/null @@ -1,904 +0,0 @@ -# Quota Management System - Validation Guide - -**Purpose:** Step-by-step validation of the Phase 1 Quota Management implementation. - -**Estimated Time:** 30-45 minutes - ---- - -## Prerequisites Checklist - -Before starting validation, ensure you have: - -- [ ] AWS credentials configured (`~/.aws/credentials` or environment variables) -- [ ] Python 3.13+ installed -- [ ] Node.js 18+ installed (for CDK) -- [ ] Docker running (for local development) -- [ ] Git repository cloned and up to date - ---- - -## Phase 1: Environment Setup (5-10 minutes) - -### Step 1.1: Install Backend Dependencies - -```bash -cd backend - -# Install dependencies -uv sync --extra dev - -# Verify quota module imports -uv run python -c "from agents.main_agent.quota import QuotaTier, QuotaResolver; print('✅ Quota module loaded')" -``` - -**Expected Output:** -``` -✅ Quota module loaded -``` - -### Step 1.2: Install CDK Dependencies - -```bash -cd ../../cdk - -# Install Node dependencies -npm install - -# Verify CDK CLI -npx cdk --version -``` - -**Expected Output:** -``` -2.120.0 (or higher) -``` - -### Step 1.3: Configure AWS Credentials - -```bash -# Verify AWS credentials -aws sts get-caller-identity -``` - -**Expected Output:** -```json -{ - "UserId": "...", - "Account": "123456789012", - "Arn": "arn:aws:iam::123456789012:user/youruser" -} -``` - ---- - -## Phase 2: Deploy DynamoDB Infrastructure (10-15 minutes) - -### Step 2.1: Bootstrap CDK (First Time Only) - -```bash -cd cdk - -# Bootstrap CDK in your account/region -cdk bootstrap -``` - -**Expected Output:** -``` -✅ Environment aws://123456789012/us-east-1 bootstrapped -``` - -**Note:** Only needed once per AWS account/region combination. - -### Step 2.2: Review Infrastructure Changes - -```bash -# View what will be created -npm run diff:dev -``` - -**Expected Output:** -``` -Stack QuotaStack-dev -Resources -[+] AWS::DynamoDB::Table UserQuotasTable UserQuotasTable... -[+] AWS::DynamoDB::Table QuotaEventsTable QuotaEventsTable... -``` - -### Step 2.3: Deploy to Development - -```bash -# Deploy the stack -npm run deploy:dev -``` - -**Expected Output:** -``` -✅ QuotaStack-dev - -Outputs: -QuotaStack-dev.QuotaEventsTableName = QuotaEvents-dev -QuotaStack-dev.UserQuotasTableName = UserQuotas-dev -``` - -**Duration:** 2-5 minutes - -### Step 2.4: Verify Tables Were Created - -```bash -# List DynamoDB tables -aws dynamodb list-tables --query "TableNames[?contains(@, 'Quota')]" -``` - -**Expected Output:** -```json -[ - "QuotaEvents-dev", - "UserQuotas-dev" -] -``` - -### Step 2.5: Verify GSIs - -```bash -# Check UserQuotas GSIs -aws dynamodb describe-table --table-name UserQuotas-dev \ - --query "Table.GlobalSecondaryIndexes[].IndexName" -``` - -**Expected Output:** -```json -[ - "AssignmentTypeIndex", - "RoleAssignmentIndex", - "UserAssignmentIndex" -] -``` - -```bash -# Check QuotaEvents GSIs -aws dynamodb describe-table --table-name QuotaEvents-dev \ - --query "Table.GlobalSecondaryIndexes[].IndexName" -``` - -**Expected Output:** -```json -[ - "TierEventIndex" -] -``` - -### Step 2.6: Verify Billing Mode - -```bash -aws dynamodb describe-table --table-name UserQuotas-dev \ - --query "Table.BillingModeSummary.BillingMode" -``` - -**Expected Output:** -``` -"PAY_PER_REQUEST" -``` - -✅ **Checkpoint:** DynamoDB tables deployed with correct schema and GSIs. - ---- - -## Phase 3: Run Unit Tests (5 minutes) - -### Step 3.1: Run Quota Resolver Tests - -```bash -cd ../backend - -# Run resolver tests -pytest tests/quota/test_resolver.py -v -``` - -**Expected Output:** -``` -tests/quota/test_resolver.py::test_resolve_direct_user_assignment PASSED -tests/quota/test_resolver.py::test_resolve_fallback_to_role PASSED -tests/quota/test_resolver.py::test_resolve_fallback_to_default PASSED -tests/quota/test_resolver.py::test_cache_hit PASSED -tests/quota/test_resolver.py::test_no_quota_configured PASSED -tests/quota/test_resolver.py::test_cache_invalidation_specific_user PASSED -tests/quota/test_resolver.py::test_disabled_assignment_skipped PASSED - -========================== 10 passed in 0.XX s ========================== -``` - -### Step 3.2: Run Quota Checker Tests - -```bash -# Run checker tests -pytest tests/quota/test_checker.py -v -``` - -**Expected Output:** -``` -tests/quota/test_checker.py::test_check_quota_no_quota_configured PASSED -tests/quota/test_checker.py::test_check_quota_within_limits PASSED -tests/quota/test_checker.py::test_check_quota_exceeded PASSED -tests/quota/test_checker.py::test_check_quota_unlimited_tier PASSED -tests/quota/test_checker.py::test_check_quota_daily_period PASSED -tests/quota/test_checker.py::test_check_quota_cost_aggregator_error PASSED -tests/quota/test_checker.py::test_check_quota_exactly_at_limit PASSED - -========================== 9 passed in 0.XX s ========================== -``` - -### Step 3.3: Run All Quota Tests - -```bash -# Run all quota tests together -pytest tests/quota/ -v --tb=short -``` - -**Expected Output:** -``` -========================== 19 passed in 0.XX s ========================== -``` - -✅ **Checkpoint:** All unit tests passing. - ---- - -## Phase 4: Start Backend Server (2 minutes) - -### Step 4.1: Update Environment Configuration - -```bash -cd backend/src - -# Copy example env file if not exists -cp .env.example .env - -# Edit .env to include quota table names -nano .env # or use your preferred editor -``` - -**Add/Update these lines in `.env`:** -```bash -# DynamoDB Quota Tables -DYNAMODB_QUOTA_TABLE=UserQuotas-dev -DYNAMODB_EVENTS_TABLE=QuotaEvents-dev -``` - -### Step 4.2: Start the Backend - -```bash -# Start FastAPI server -python -m uvicorn apis.app_api.main:app --reload --port 8000 -``` - -**Expected Output:** -``` -INFO: Started server process -INFO: Waiting for application startup. -INFO: Application startup complete. -INFO: Uvicorn running on http://127.0.0.1:8000 -``` - -**Keep this terminal running** for the next phase. - -✅ **Checkpoint:** Backend server running on port 8000. - ---- - -## Phase 5: Validate Admin API (10-15 minutes) - -### Step 5.1: Get Admin Token - -You'll need a valid JWT token with admin role. For local testing, you can: - -**Option A: Use existing auth flow** -```bash -# If you have Cognito/Auth0 set up, get token via login -# Store in environment variable -export ADMIN_TOKEN="your-jwt-token-here" -``` - -**Option B: Skip for now and test after auth setup** -```bash -# Note: Admin endpoints require authentication -# Skip to Phase 6 if auth not set up yet -``` - -### Step 5.2: Create a Quota Tier - -```bash -curl -X POST http://localhost:8000/api/admin/quota/tiers \ - -H "Authorization: Bearer $ADMIN_TOKEN" \ - -H "Content-Type: application/json" \ - -d '{ - "tierId": "basic", - "tierName": "Basic Tier", - "description": "Default tier for all users", - "monthlyCostLimit": 100.0, - "dailyCostLimit": 5.0, - "periodType": "monthly", - "actionOnLimit": "block", - "enabled": true - }' | jq -``` - -**Expected Output:** -```json -{ - "tierId": "basic", - "tierName": "Basic Tier", - "description": "Default tier for all users", - "monthlyCostLimit": 100.0, - "dailyCostLimit": 5.0, - "periodType": "monthly", - "actionOnLimit": "block", - "enabled": true, - "createdAt": "2025-12-17T...", - "updatedAt": "2025-12-17T...", - "createdBy": "admin_user_id" -} -``` - -### Step 5.3: Create Additional Tiers - -```bash -# Premium Tier -curl -X POST http://localhost:8000/api/admin/quota/tiers \ - -H "Authorization: Bearer $ADMIN_TOKEN" \ - -H "Content-Type: application/json" \ - -d '{ - "tierId": "premium", - "tierName": "Premium Tier", - "description": "For premium users", - "monthlyCostLimit": 500.0, - "dailyCostLimit": 20.0, - "periodType": "monthly", - "enabled": true - }' | jq - -# Enterprise Tier -curl -X POST http://localhost:8000/api/admin/quota/tiers \ - -H "Authorization: Bearer $ADMIN_TOKEN" \ - -H "Content-Type: application/json" \ - -d '{ - "tierId": "enterprise", - "tierName": "Enterprise Tier", - "description": "For enterprise customers", - "monthlyCostLimit": 2000.0, - "dailyCostLimit": 100.0, - "periodType": "monthly", - "enabled": true - }' | jq -``` - -### Step 5.4: List All Tiers - -```bash -curl http://localhost:8000/api/admin/quota/tiers \ - -H "Authorization: Bearer $ADMIN_TOKEN" | jq -``` - -**Expected Output:** -```json -[ - { - "tierId": "basic", - "tierName": "Basic Tier", - ... - }, - { - "tierId": "premium", - "tierName": "Premium Tier", - ... - }, - { - "tierId": "enterprise", - "tierName": "Enterprise Tier", - ... - } -] -``` - -### Step 5.5: Create Default Tier Assignment - -```bash -curl -X POST http://localhost:8000/api/admin/quota/assignments \ - -H "Authorization: Bearer $ADMIN_TOKEN" \ - -H "Content-Type: application/json" \ - -d '{ - "tierId": "basic", - "assignmentType": "default_tier", - "priority": 100, - "enabled": true - }' | jq -``` - -**Expected Output:** -```json -{ - "assignmentId": "generated-uuid", - "tierId": "basic", - "assignmentType": "default_tier", - "priority": 100, - "enabled": true, - "createdAt": "2025-12-17T...", - ... -} -``` - -### Step 5.6: Create Role-Based Assignment - -```bash -curl -X POST http://localhost:8000/api/admin/quota/assignments \ - -H "Authorization: Bearer $ADMIN_TOKEN" \ - -H "Content-Type: application/json" \ - -d '{ - "tierId": "premium", - "assignmentType": "jwt_role", - "jwtRole": "Faculty", - "priority": 200, - "enabled": true - }' | jq -``` - -### Step 5.7: Create Direct User Assignment - -```bash -curl -X POST http://localhost:8000/api/admin/quota/assignments \ - -H "Authorization: Bearer $ADMIN_TOKEN" \ - -H "Content-Type: application/json" \ - -d '{ - "tierId": "enterprise", - "assignmentType": "direct_user", - "userId": "test_user_123", - "priority": 300, - "enabled": true - }' | jq -``` - -### Step 5.8: List All Assignments - -```bash -curl http://localhost:8000/api/admin/quota/assignments \ - -H "Authorization: Bearer $ADMIN_TOKEN" | jq -``` - -**Expected Output:** -```json -[ - { - "assignmentId": "...", - "tierId": "basic", - "assignmentType": "default_tier", - ... - }, - { - "assignmentId": "...", - "tierId": "premium", - "assignmentType": "jwt_role", - "jwtRole": "Faculty", - ... - }, - { - "assignmentId": "...", - "tierId": "enterprise", - "assignmentType": "direct_user", - "userId": "test_user_123", - ... - } -] -``` - -✅ **Checkpoint:** Tiers and assignments created successfully via Admin API. - ---- - -## Phase 6: Verify DynamoDB Data (5 minutes) - -### Step 6.1: Check Tiers in DynamoDB - -```bash -aws dynamodb query \ - --table-name UserQuotas-dev \ - --key-condition-expression "begins_with(PK, :prefix)" \ - --expression-attribute-values '{":prefix":{"S":"QUOTA_TIER#"}}' \ - --query "Items[].{TierId:tierId.S, Name:tierName.S, Limit:monthlyCostLimit.N}" -``` - -**Expected Output:** -```json -[ - { - "TierId": "basic", - "Name": "Basic Tier", - "Limit": "100.0" - }, - { - "TierId": "premium", - "Name": "Premium Tier", - "Limit": "500.0" - }, - { - "TierId": "enterprise", - "Name": "Enterprise Tier", - "Limit": "2000.0" - } -] -``` - -### Step 6.2: Check Assignments via GSI - -```bash -# Query default tier assignments via GSI1 -aws dynamodb query \ - --table-name UserQuotas-dev \ - --index-name AssignmentTypeIndex \ - --key-condition-expression "GSI1PK = :pk" \ - --expression-attribute-values '{":pk":{"S":"ASSIGNMENT_TYPE#default_tier"}}' \ - --query "Items[].{AssignmentId:assignmentId.S, TierId:tierId.S, Priority:priority.N}" -``` - -**Expected Output:** -```json -[ - { - "AssignmentId": "...", - "TierId": "basic", - "Priority": "100" - } -] -``` - -### Step 6.3: Verify User Assignment GSI - -```bash -# Query direct user assignment via GSI2 -aws dynamodb query \ - --table-name UserQuotas-dev \ - --index-name UserAssignmentIndex \ - --key-condition-expression "GSI2PK = :pk" \ - --expression-attribute-values '{":pk":{"S":"USER#test_user_123"}}' \ - --query "Items[].{UserId:userId.S, TierId:tierId.S}" -``` - -**Expected Output:** -```json -[ - { - "UserId": "test_user_123", - "TierId": "enterprise" - } -] -``` - -### Step 6.4: Verify Role Assignment GSI - -```bash -# Query role assignment via GSI3 -aws dynamodb query \ - --table-name UserQuotas-dev \ - --index-name RoleAssignmentIndex \ - --key-condition-expression "GSI3PK = :pk" \ - --expression-attribute-values '{":pk":{"S":"ROLE#Faculty"}}' \ - --query "Items[].{Role:jwtRole.S, TierId:tierId.S}" -``` - -**Expected Output:** -```json -[ - { - "Role": "Faculty", - "TierId": "premium" - } -] -``` - -✅ **Checkpoint:** Data correctly stored in DynamoDB with GSI keys. - ---- - -## Phase 7: Validate Quota Resolution (5 minutes) - -### Step 7.1: Test in Python Console - -```bash -cd backend/src - -# Start Python console -python -``` - -**Run this code:** -```python -import asyncio -from apis.shared.auth.models import User -from agents.main_agent.quota.repository import QuotaRepository -from agents.main_agent.quota.resolver import QuotaResolver - -# Create repository and resolver -repo = QuotaRepository( - table_name="UserQuotas-dev", - events_table_name="QuotaEvents-dev" -) -resolver = QuotaResolver(repository=repo, cache_ttl_seconds=300) - -# Test 1: Direct user assignment -user1 = User( - user_id="test_user_123", - email="test@example.com", - name="Test User", - roles=[] -) - -resolved1 = asyncio.run(resolver.resolve_user_quota(user1)) -print(f"✅ User 1 resolved: {resolved1.tier.tier_name} (matched by: {resolved1.matched_by})") -# Expected: "Enterprise Tier (matched by: direct_user)" - -# Test 2: Role-based assignment -user2 = User( - user_id="faculty_user", - email="faculty@example.com", - name="Faculty User", - roles=["Faculty"] -) - -resolved2 = asyncio.run(resolver.resolve_user_quota(user2)) -print(f"✅ User 2 resolved: {resolved2.tier.tier_name} (matched by: {resolved2.matched_by})") -# Expected: "Premium Tier (matched by: jwt_role:Faculty)" - -# Test 3: Default tier fallback -user3 = User( - user_id="random_user", - email="random@example.com", - name="Random User", - roles=[] -) - -resolved3 = asyncio.run(resolver.resolve_user_quota(user3)) -print(f"✅ User 3 resolved: {resolved3.tier.tier_name} (matched by: {resolved3.matched_by})") -# Expected: "Basic Tier (matched by: default_tier)" - -# Test 4: Cache hit -resolved3_cached = asyncio.run(resolver.resolve_user_quota(user3)) -print(f"✅ User 3 cached: {resolved3_cached.tier.tier_name} (same object: {resolved3.tier is resolved3_cached.tier})") -# Expected: True (cache hit) - -print("\n✅ All quota resolution tests passed!") -``` - -**Expected Output:** -``` -✅ User 1 resolved: Enterprise Tier (matched by: direct_user) -✅ User 2 resolved: Premium Tier (matched by: jwt_role:Faculty) -✅ User 3 resolved: Basic Tier (matched by: default_tier) -✅ User 3 cached: Basic Tier (same object: True) - -✅ All quota resolution tests passed! -``` - -✅ **Checkpoint:** Quota resolution working correctly with priority ordering. - ---- - -## Phase 8: Validate Quota Checker (Optional, 5 minutes) - -**Note:** This requires the cost tracking system to be set up. Skip if not available. - -```python -from agents.main_agent.quota.checker import QuotaChecker -from agents.main_agent.quota.event_recorder import QuotaEventRecorder -from apis.app_api.costs.aggregator import CostAggregator - -# Create checker -event_recorder = QuotaEventRecorder(repository=repo) -cost_aggregator = CostAggregator() -checker = QuotaChecker( - resolver=resolver, - cost_aggregator=cost_aggregator, - event_recorder=event_recorder -) - -# Check quota for user -result = asyncio.run(checker.check_quota(user1)) -print(f"Allowed: {result.allowed}") -print(f"Message: {result.message}") -print(f"Current Usage: ${result.current_usage:.2f}") -print(f"Quota Limit: ${result.quota_limit:.2f}") -print(f"Percentage Used: {result.percentage_used:.1f}%") -``` - ---- - -## Phase 9: Check CloudWatch Metrics (Optional, 5 minutes) - -### Step 9.1: Verify No Table Scans - -```bash -# Check for Scan operations (should be 0) -aws cloudwatch get-metric-statistics \ - --namespace AWS/DynamoDB \ - --metric-name ConsumedReadCapacityUnits \ - --dimensions Name=TableName,Value=UserQuotas-dev Name=Operation,Value=Scan \ - --start-time $(date -u -v-1H +%Y-%m-%dT%H:%M:%S) \ - --end-time $(date -u +%Y-%m-%dT%H:%M:%S) \ - --period 3600 \ - --statistics Sum \ - --query 'Datapoints[].Sum' -``` - -**Expected Output:** -```json -[] -``` -(Empty array = no scans) - -### Step 9.2: Check Query Operations - -```bash -# Check for Query operations (should have some) -aws cloudwatch get-metric-statistics \ - --namespace AWS/DynamoDB \ - --metric-name ConsumedReadCapacityUnits \ - --dimensions Name=TableName,Value=UserQuotas-dev Name=Operation,Value=Query \ - --start-time $(date -u -v-1H +%Y-%m-%dT%H:%M:%S) \ - --end-time $(date -u +%Y-%m-%dT%H:%M:%S) \ - --period 3600 \ - --statistics Sum -``` - -**Expected:** Some non-zero values indicating successful queries. - ---- - -## Phase 10: Cleanup (Optional) - -### Step 10.1: Delete Test Data - -```bash -# Delete assignments (get IDs first) -ASSIGNMENT_IDS=$(aws dynamodb query \ - --table-name UserQuotas-dev \ - --index-name AssignmentTypeIndex \ - --key-condition-expression "begins_with(GSI1PK, :prefix)" \ - --expression-attribute-values '{":prefix":{"S":"ASSIGNMENT_TYPE#"}}' \ - --query "Items[].assignmentId.S" \ - --output text) - -# Delete each assignment via API -for id in $ASSIGNMENT_IDS; do - curl -X DELETE "http://localhost:8000/api/admin/quota/assignments/$id" \ - -H "Authorization: Bearer $ADMIN_TOKEN" -done - -# Delete tiers via API -curl -X DELETE http://localhost:8000/api/admin/quota/tiers/basic \ - -H "Authorization: Bearer $ADMIN_TOKEN" -curl -X DELETE http://localhost:8000/api/admin/quota/tiers/premium \ - -H "Authorization: Bearer $ADMIN_TOKEN" -curl -X DELETE http://localhost:8000/api/admin/quota/tiers/enterprise \ - -H "Authorization: Bearer $ADMIN_TOKEN" -``` - -### Step 10.2: Destroy CDK Stack (Caution!) - -```bash -cd cdk - -# CAUTION: This will delete all DynamoDB tables and data! -npm run destroy:dev -``` - ---- - -## Validation Checklist - -Mark each item as you complete it: - -### Infrastructure -- [ ] CDK dependencies installed -- [ ] AWS credentials configured -- [ ] DynamoDB tables deployed (UserQuotas, QuotaEvents) -- [ ] All GSIs created (3 for UserQuotas, 1 for QuotaEvents) -- [ ] Tables using PAY_PER_REQUEST billing - -### Code Quality -- [ ] All 10 resolver tests passing -- [ ] All 9 checker tests passing -- [ ] No import errors in quota module -- [ ] Backend server starts without errors - -### Admin API -- [ ] Can create quota tiers -- [ ] Can list all tiers -- [ ] Can create default tier assignment -- [ ] Can create role-based assignment -- [ ] Can create direct user assignment -- [ ] Can list all assignments - -### Data Integrity -- [ ] Tiers stored correctly in DynamoDB -- [ ] Assignments have correct GSI keys -- [ ] GSI queries return expected results -- [ ] No table scans in CloudWatch metrics - -### Business Logic -- [ ] Direct user assignment takes priority -- [ ] Role-based assignment works as fallback -- [ ] Default tier assignment works as final fallback -- [ ] Cache reduces database queries -- [ ] Resolver returns correct matched_by value - ---- - -## Troubleshooting - -### Issue: CDK Deploy Fails - -**Error:** "CDK bootstrap required" -```bash -cdk bootstrap aws:/// -``` - -### Issue: Permission Denied - -**Error:** "User is not authorized to perform: dynamodb:CreateTable" -- Check IAM permissions -- Ensure user has DynamoDB and CloudFormation permissions - -### Issue: Module Import Errors - -**Error:** "ModuleNotFoundError: No module named 'agentcore'" -```bash -# Ensure you're in the backend/src directory -cd backend/src -export PYTHONPATH=$PWD:$PYTHONPATH -``` - -### Issue: Admin API 401/403 - -**Error:** "Not authenticated" or "Insufficient permissions" -- Verify JWT token is valid -- Check token includes admin role -- Test auth endpoint first: `curl http://localhost:8000/health` - -### Issue: Table Already Exists - -**Error:** "Table already exists" -- Either use existing table or delete via Console -- Or change environment name in CDK context - ---- - -## Success Criteria - -Your implementation is validated when: - -1. ✅ All 19 unit tests pass -2. ✅ DynamoDB tables deployed with correct GSIs -3. ✅ Admin API CRUD operations work -4. ✅ Quota resolution returns correct tiers with priority ordering -5. ✅ Cache reduces database queries (verify via logs) -6. ✅ No table scans in CloudWatch metrics -7. ✅ GSI queries return data in expected format - ---- - -## Next Steps - -After successful validation: - -1. **Integrate with Chat API**: Add quota checker to message processing middleware -2. **Set Up Monitoring**: Create CloudWatch dashboards for quota metrics -3. **Populate Production Data**: Create real tiers and assignments for your users -4. **Test Cost Tracking**: Verify cost aggregator integration -5. **Plan Phase 2**: Review `QUOTA_MANAGEMENT_PHASE2_SPEC.md` for next features - ---- - -**Questions or Issues?** -- Check `docs/QUOTA_MANAGEMENT_IMPLEMENTATION.md` for detailed reference -- Review `docs/QUOTA_MANAGEMENT_PHASE1_SPEC.md` for specification details -- Check backend logs in `agentcore.log` - -**Congratulations!** You've successfully validated the Phase 1 Quota Management implementation. diff --git a/docs/RBAC_IMPLEMENTATION.md b/docs/RBAC_IMPLEMENTATION.md deleted file mode 100644 index 0edb23f0..00000000 --- a/docs/RBAC_IMPLEMENTATION.md +++ /dev/null @@ -1,367 +0,0 @@ -# Role-Based Access Control (RBAC) Implementation Guide - -## Overview - -This document describes the RBAC implementation for the AgentCore Public Stack backend API, which enables role-based access control for admin and privileged endpoints using JWT tokens from Entra ID. - -## Architecture - -### Flow Diagram - -``` -JWT Token (from OIDC Provider) - ↓ -GenericOIDCJWTValidator (validates & extracts roles) - ↓ -User Model (email, user_id, name, roles[]) - ↓ -FastAPI Dependency (require_admin, require_roles, etc.) - ↓ -Protected Route Handler -``` - -## Components - -### 1. JWT Validator (`apis/shared/auth/generic_jwt_validator.py`) - -- Validates JWT tokens from any configured OIDC provider -- Extracts user information including roles array -- Dynamically matches token issuer to configured providers - -### 2. User Model (`apis/shared/auth/models.py`) - -```python -@dataclass -class User: - email: str - user_id: str - name: str - roles: List[str] # ← Roles from JWT - picture: Optional[str] = None -``` - -### 3. RBAC Module (`apis/shared/auth/rbac.py`) - -**NEW - Created for this implementation** - -Provides FastAPI dependencies for role-based access control: - -#### Dependencies - -- `require_roles(*roles)` - User must have at least ONE of the roles (OR logic) -- `require_all_roles(*roles)` - User must have ALL of the roles (AND logic) - -#### Helper Functions - -- `has_any_role(user, *roles)` - Check if user has any role (for conditional logic) -- `has_all_roles(user, *roles)` - Check if user has all roles (for conditional logic) - -#### Predefined Checkers - -- `require_admin` - Requires "Admin" or "SuperAdmin" -- `require_faculty` - Requires "Faculty" -- `require_staff` - Requires "Staff" -- `require_developer` - Requires "DotNetDevelopers" -- `require_aws_ai_access` - Requires "AWS-BoiseStateAI" - -### 4. Admin Routes Module (`apis/app_api/admin/`) - -**NEW - Created for this implementation** - -Example implementation showing how to use RBAC in practice. - -**Files:** -- `routes.py` - Admin endpoint implementations -- `models.py` - Pydantic models for admin responses -- `README.md` - Documentation and usage examples - -## Usage Examples - -### Basic Admin Endpoint - -```python -from fastapi import APIRouter, Depends -from apis.shared.auth import User, require_admin - -router = APIRouter(prefix="/admin", tags=["admin"]) - -@router.get("/stats") -async def get_stats(admin_user: User = Depends(require_admin)): - """Only users with Admin or SuperAdmin role can access.""" - return {"stats": "..."} -``` - -### Custom Role Requirements - -```python -from apis.shared.auth import require_roles - -@router.post("/faculty-only") -async def faculty_endpoint(user: User = Depends(require_roles("Faculty", "Staff"))): - """Requires Faculty OR Staff role.""" - return {"message": f"Access granted to {user.email}"} -``` - -### Multiple Required Roles (AND logic) - -```python -from apis.shared.auth import require_all_roles - -@router.post("/critical") -async def critical_endpoint(user: User = Depends(require_all_roles("Admin", "Security"))): - """Requires BOTH Admin AND Security roles.""" - return {"message": "Access granted"} -``` - -### Conditional Features - -```python -from apis.shared.auth import get_current_user, has_any_role - -@router.get("/dashboard") -async def dashboard(user: User = Depends(get_current_user)): - """All authenticated users can access, but admins see extra data.""" - response = {"user": user.email} - - if has_any_role(user, "Admin", "SuperAdmin"): - response["admin_features"] = {...} - - return response -``` - -## Testing - -### Local Testing with Docker - -1. **Start the backend:** - ```bash - docker-compose up backend - ``` - -2. **Test with JWT token:** - ```bash - curl -H "Authorization: Bearer " \ - http://localhost:8000/admin/me - ``` - -### Development Mode (Auth Disabled) - -For local development without Entra ID setup: - -1. **Set environment variable:** - ```bash - # backend/src/.env - ENABLE_AUTHENTICATION=false - ``` - -2. **Test without token:** - ```bash - curl http://localhost:8000/admin/me - ``` - -**Note:** With auth disabled, user will have empty roles array, so role-protected endpoints will still return 403. This is by design. - -### Testing Role-Protected Endpoints - -When authentication is enabled, the JWT token must contain the required roles in the `roles` claim. - -**Example JWT payload:** -```json -{ - "email": "admin@example.com", - "name": "Admin User", - "http://schemas.boisestate.edu/claims/employeenumber": "123456789", - "roles": ["Admin", "Faculty", "AWS-BoiseStateAI"], - "aud": "your-client-id", - "iss": "https://login.microsoftonline.com/{tenant-id}/v2.0" -} -``` - -## Available Admin Endpoints - -All endpoints require authentication. Admin endpoints require Admin or SuperAdmin role. - -| Endpoint | Method | Required Role | Description | -|----------|--------|---------------|-------------| -| `/admin/me` | GET | Admin or SuperAdmin | Get admin user info | -| `/admin/sessions/all` | GET | Admin or SuperAdmin | List all sessions (all users) | -| `/admin/sessions/{id}` | DELETE | Admin or SuperAdmin | Delete any user's session | -| `/admin/stats` | GET | Admin or SuperAdmin | Get system statistics | -| `/admin/users/{id}/sessions` | GET | Admin or SuperAdmin | Get specific user's sessions | -| `/admin/conditional-example` | GET | Any authenticated | Example with conditional features | -| `/admin/require-multiple-roles-example` | POST | Admin, SuperAdmin, or DotNetDevelopers | Multi-role example | - -See `backend/src/apis/app_api/admin/README.md` for detailed endpoint documentation. - -## HTTP Status Codes - -| Code | Meaning | When It Occurs | -|------|---------|----------------| -| 200 | Success | Request succeeded | -| 401 | Unauthorized | No token provided or invalid token | -| 403 | Forbidden | Valid token but user lacks required role | -| 404 | Not Found | Resource doesn't exist | -| 500 | Server Error | Internal error | - -## Error Response Format - -### 401 Unauthorized -```json -{ - "detail": "Authentication required. Please provide a valid Bearer token in the Authorization header." -} -``` - -### 403 Forbidden -```json -{ - "detail": "Access denied. Required roles: Admin, SuperAdmin" -} -``` - -## Entra ID Configuration - -### Required Environment Variables - -```bash -# .env -ENTRA_TENANT_ID=your-tenant-id -ENTRA_CLIENT_ID=your-client-id -ENTRA_CLIENT_SECRET=your-client-secret -ENTRA_REDIRECT_URI=your-redirect-uri - -# Optional - disable auth for development -ENABLE_AUTHENTICATION=true -``` - -### App Registration Setup - -1. **Register application in Entra ID** -2. **Define app roles in app manifest:** - ```json - "appRoles": [ - { - "id": "...", - "allowedMemberTypes": ["User"], - "displayName": "Admin", - "value": "Admin", - "description": "Administrator access" - }, - { - "id": "...", - "allowedMemberTypes": ["User"], - "displayName": "Faculty", - "value": "Faculty", - "description": "Faculty access" - } - ] - ``` -3. **Assign roles to users/groups** -4. **Configure token claims to include roles** - -### Role Claim Location - -The validator checks the `roles` claim in the JWT payload: -```python -roles = payload.get('roles', []) # In generic_jwt_validator.py -``` - -## Adding New Role-Protected Endpoints - -### Step 1: Import Dependencies - -```python -from fastapi import APIRouter, Depends -from apis.shared.auth import User, require_admin, require_roles -``` - -### Step 2: Create Route with Dependency - -```python -@router.post("/my-admin-feature") -async def my_feature(admin_user: User = Depends(require_admin)): - logger.info(f"Admin {admin_user.email} accessed feature") - - # Access user properties - user_email = admin_user.email - user_id = admin_user.user_id - user_roles = admin_user.roles - - return {"message": "Success"} -``` - -### Step 3: Handle Authorization - -The dependency automatically: -- ✓ Validates JWT token -- ✓ Extracts user information -- ✓ Checks required roles -- ✓ Returns 403 if role check fails -- ✓ Injects User object into handler - -## Security Best Practices - -1. **Always use dependencies** - Never manually check roles -2. **Log admin actions** - Audit trail for compliance -3. **Use specific roles** - Prefer `require_admin` over `get_current_user` for sensitive operations -4. **Never disable auth in production** - `ENABLE_AUTHENTICATION=false` is for development only -5. **Validate on every request** - Stateless authentication, no sessions -6. **Use HTTPS in production** - Protect tokens in transit - -## Future Enhancements - -Potential improvements to the RBAC system: - -- **Permission-based access control** - Map roles to specific permissions -- **Dynamic role configuration** - Store role mappings in database -- **Role hierarchies** - Admin inherits Staff permissions, etc. -- **Audit logging** - Track all admin actions with timestamps -- **Rate limiting by role** - Different limits for different user types -- **Temporary role elevation** - Time-limited admin access -- **Multi-tenancy** - Scope roles to organizations - -## Troubleshooting - -### Issue: "User does not have required role" - -**Cause:** JWT token doesn't contain the required role in the `roles` claim. - -**Solution:** -1. Check Entra ID app role assignments -2. Verify role is defined in app manifest -3. Ensure token includes `roles` claim -4. Check role spelling (case-sensitive) - -### Issue: "Invalid token audience" - -**Cause:** Token audience doesn't match expected client ID. - -**Solution:** -1. Verify `ENTRA_CLIENT_ID` matches app registration -2. Check token was issued for correct application -3. See `generic_jwt_validator.py` for audience validation logic - -### Issue: "Authentication service misconfigured" - -**Cause:** Environment variables not set correctly. - -**Solution:** -1. Verify `.env` file exists in `backend/src/` -2. Check `ENTRA_TENANT_ID` and `ENTRA_CLIENT_ID` are set -3. Restart backend after changing environment variables - -## File References - -- RBAC utilities: `backend/src/apis/shared/auth/rbac.py` -- JWT validation: `backend/src/apis/shared/auth/generic_jwt_validator.py` -- User model: `backend/src/apis/shared/auth/models.py` -- Auth dependencies: `backend/src/apis/shared/auth/dependencies.py` -- Admin routes: `backend/src/apis/app_api/admin/routes.py` -- Admin README: `backend/src/apis/app_api/admin/README.md` - -## Additional Resources - -- [FastAPI Dependencies](https://fastapi.tiangolo.com/tutorial/dependencies/) -- [Microsoft Entra ID](https://learn.microsoft.com/en-us/entra/identity/) -- [JWT.io](https://jwt.io/) - Decode and inspect tokens -- [PyJWT Documentation](https://pyjwt.readthedocs.io/) diff --git a/docs/SESSION_DELETION_SPEC.md b/docs/SESSION_DELETION_SPEC.md deleted file mode 100644 index c449f35e..00000000 --- a/docs/SESSION_DELETION_SPEC.md +++ /dev/null @@ -1,1078 +0,0 @@ -# Session Deletion & Schema Refactoring Specification - -## Executive Summary - -This specification outlines a schema refactoring to enable session deletion while preserving cost accounting accuracy. The current `SessionsMetadata` table uses SK patterns that conflate session metadata with per-message cost data, creating performance issues and preventing clean session deletion. - -**Goal**: Allow users to delete conversations without disrupting quota enforcement, cost reports, or audit trails. - -**Approach**: Refactor SK patterns in the existing `SessionsMetadata` table to cleanly separate session records from cost records, enabling efficient queries and soft delete support. - -**Key Decision**: Use single-table design (no new tables) with updated SK prefixes for optimal operational simplicity. - -**Impact**: No user-facing or admin-facing functionality changes. Performance improvements for session listing. - ---- - -## Table of Contents - -1. [Problem Statement](#problem-statement) -2. [Current Architecture](#current-architecture) -3. [Proposed Architecture](#proposed-architecture) -4. [Schema Design](#schema-design) -5. [Session Deletion Flow](#session-deletion-flow) -6. [Impact Analysis](#impact-analysis) -7. [Implementation Plan](#implementation-plan) -8. [Implementation Details](#implementation-details) -9. [API Changes](#api-changes) -10. [Testing Strategy](#testing-strategy) - ---- - -## Problem Statement - -### Current Issues - -1. **Session and Message Records Mixed**: The `SessionsMetadata` table stores both: - - Session records: `SK = SESSION#{session_id}` - - Message cost records: `SK = SESSION#{session_id}#MSG#{message_id}` - - Both start with `SESSION#`, so `begins_with(SK, 'SESSION#')` matches both. Listing sessions requires filtering out message records in memory. - -2. **No Session Deletion**: Deleting a session would orphan cost records or break audit trails. - -3. **Performance Degradation**: A user with 100 sessions and 10,000 messages returns ~10,100 items when listing sessions, then filters 10,000 in memory. - -4. **No Server-Side Pagination**: Sessions must be sorted by `last_message_at` in memory because DynamoDB pagination follows SK order. - -### Business Requirements - -| Requirement | Priority | Notes | -|-------------|----------|-------| -| Users can delete conversations | HIGH | Privacy, cleanup | -| Deleted sessions don't appear in session list | HIGH | User expectation | -| Cost accounting remains accurate after deletion | HIGH | Billing integrity | -| Quota enforcement unaffected by deletion | HIGH | Quota uses pre-aggregated data | -| Audit trail preserved for compliance | MEDIUM | Financial records retention | -| Admin can view costs for deleted sessions | LOW | Investigation capability | - ---- - -## Current Architecture - -### SessionsMetadata Table (Current SK Patterns) - -``` -Table: SessionsMetadata -───────────────────────────────────────────────────────────────────────── -PK │ SK │ Type -───────────────────────────────────────────────────────────────────────── -USER#{user_id} │ SESSION#{session_id} │ Session metadata -USER#{user_id} │ SESSION#{session_id}#MSG#00001 │ Message cost -USER#{user_id} │ SESSION#{session_id}#MSG#00002 │ Message cost -USER#{user_id} │ SESSION#{session_id}#MSG#00003 │ Message cost -... -───────────────────────────────────────────────────────────────────────── -``` - -### Problems with Current Design - -```python -# Current list_user_sessions implementation (simplified) -async def _list_user_sessions_cloud(...): - # Query returns BOTH session and message records - response = table.query( - KeyConditionExpression="PK = :pk AND begins_with(SK, :prefix)", - ExpressionAttributeValues={ - ":pk": f"USER#{user_id}", - ":prefix": "SESSION#" # Matches both SESSION#{id} and SESSION#{id}#MSG# - } - ) - - sessions = [] - for item in response['Items']: - # Filter out message records in memory - if '#MSG#' in item.get('SK', ''): - continue # Skip message records - sessions.append(item) - - # Sort in memory (can't use DynamoDB for this) - sessions.sort(key=lambda x: x.last_message_at, reverse=True) - - return sessions[:limit] # Pagination is fake -``` - -**Complexity**: O(m + s) where m = messages, s = sessions - ---- - -## Proposed Architecture - -### Single-Table Design with New SK Prefixes - -Instead of creating new tables, we refactor the SK patterns in the existing `SessionsMetadata` table: - -``` -┌─────────────────────────────────────────────────────────────────────────┐ -│ CURRENT SK PATTERNS │ -├─────────────────────────────────────────────────────────────────────────┤ -│ SESSION#{session_id} ← Session metadata │ -│ SESSION#{session_id}#MSG#00001 ← Message cost │ -│ SESSION#{session_id}#MSG#00002 ← Message cost │ -│ │ -│ Problem: Both start with "SESSION#" - can't query sessions only │ -└─────────────────────────────────────────────────────────────────────────┘ - │ - ▼ -┌─────────────────────────────────────────────────────────────────────────┐ -│ NEW SK PATTERNS │ -├─────────────────────────────────────────────────────────────────────────┤ -│ S#ACTIVE#{last_message_at}#{session_id} ← Active session │ -│ S#DELETED#{deleted_at}#{session_id} ← Soft-deleted session │ -│ C#{timestamp}#{uuid} ← Message cost record │ -│ │ -│ Benefits: │ -│ - Query sessions: begins_with(SK, 'S#ACTIVE#') │ -│ - Query costs: begins_with(SK, 'C#') │ -│ - Sessions sorted by timestamp in SK │ -│ - No in-memory filtering or sorting needed │ -└─────────────────────────────────────────────────────────────────────────┘ -``` - -### Why Single-Table Design? - -| Factor | Single Table | Multiple Tables | -|--------|--------------|-----------------| -| **Query efficiency** | Same (with proper SK prefixes) | Same | -| **Operational complexity** | Lower (1 table to manage) | Higher (3 tables, 3 sets of alarms) | -| **Backup/restore** | Simpler (1 backup) | More complex | -| **Cost** | Slightly lower (fewer table overheads) | Slightly higher | -| **TTL handling** | Only cost records get `ttl` attribute | Clean separation | -| **Code clarity** | Requires SK prefix discipline | Natural separation | - -**Recommendation**: Single-table design for operational simplicity. The SK prefix approach provides the same query efficiency with less infrastructure overhead. - ---- - -## Schema Design - -### SessionsMetadata Table (Refactored SK Patterns) - -**Same table, new SK patterns:** - -``` -Table: SessionsMetadata (existing table, refactored) -───────────────────────────────────────────────────────────────────────── -PK │ SK │ Type -───────────────────────────────────────────────────────────────────────── -USER#{user_id} │ S#ACTIVE#{last_message_at}#{session_id} │ Active session -USER#{user_id} │ S#DELETED#{deleted_at}#{session_id} │ Deleted session -USER#{user_id} │ C#{timestamp}#{uuid} │ Message cost -───────────────────────────────────────────────────────────────────────── -``` - -### Session Record Attributes - -```python -{ - # Keys - "PK": "USER#alice", - "SK": "S#ACTIVE#2025-01-15T10:30:00Z#abc123", - - # GSI keys for direct session lookup - "GSI_PK": "SESSION#abc123", - "GSI_SK": "META", - - # Session data - "sessionId": "abc123", - "userId": "alice", - "title": "Conversation about weather", - "status": "active", - "createdAt": "2025-01-15T09:00:00Z", - "lastMessageAt": "2025-01-15T10:30:00Z", - "messageCount": 15, - - # User preferences - "starred": False, - "tags": ["weather", "planning"], - "preferences": { - "lastModel": "claude-sonnet-4-5", - "lastTemperature": 0.7, - "enabledTools": ["weather", "search"] - }, - - # Soft delete fields (only present when deleted) - "deleted": False, - "deletedAt": None - - # NOTE: No TTL attribute - sessions persist until soft-deleted -} -``` - -### Cost Record Attributes - -```python -{ - # Keys - "PK": "USER#alice", - "SK": "C#2025-01-15T10:30:45.123Z#550e8400-e29b-41d4-a716-446655440000", - - # GSI keys for per-session cost queries - "GSI_PK": "SESSION#abc123", - "GSI_SK": "C#2025-01-15T10:30:45.123Z", - - # Session reference - "sessionId": "abc123", - "messageId": 5, - - # Cost data - "cost": 0.0234, - "inputTokens": 1000, - "outputTokens": 500, - "cacheReadTokens": 200, - "cacheWriteTokens": 100, - - # Model info - "modelId": "us.anthropic.claude-sonnet-4-5-20250929-v1:0", - "modelName": "Claude 3.5 Sonnet", - "provider": "bedrock", - - # Pricing snapshot - "pricingSnapshot": { - "inputPricePerMtok": 3.0, - "outputPricePerMtok": 15.0, - "cacheReadPricePerMtok": 0.30, - "cacheWritePricePerMtok": 3.75, - "currency": "USD", - "snapshotAt": "2025-01-15T10:30:45Z" - }, - - # Latency - "timeToFirstToken": 250, - "endToEndLatency": 1500, - - # Attribution - "userId": "alice", - "timestamp": "2025-01-15T10:30:45.123Z", - - # TTL - ONLY cost records have this attribute - "ttl": 1768118400 # 365 days from creation -} -``` - -### SK Pattern Design Rationale - -| SK Pattern | Purpose | Benefits | -|------------|---------|----------| -| `S#ACTIVE#{last_message_at}#{session_id}` | Active sessions | Sorted by recency, clean prefix query | -| `S#DELETED#{deleted_at}#{session_id}` | Soft-deleted sessions | Separate from active, queryable for admin | -| `C#{timestamp}#{uuid}` | Cost records | Time-ordered, unique, supports TTL | - -### TTL Handling in Single Table - -DynamoDB TTL only deletes items that have the `ttl` attribute set: - -```python -# Session records: NO ttl attribute → persist indefinitely (until soft-deleted) -session_item = { - "PK": "USER#alice", - "SK": "S#ACTIVE#2025-01-15T10:30:00Z#abc123", - # No "ttl" attribute -} - -# Cost records: HAVE ttl attribute → auto-delete after 365 days -cost_item = { - "PK": "USER#alice", - "SK": "C#2025-01-15T10:30:45.123Z#uuid", - "ttl": int((datetime.now() + timedelta(days=365)).timestamp()) -} -``` - -### GSI: SessionLookupIndex - -For direct session access by ID and per-session cost queries: - -``` -GSI: SessionLookupIndex - PK: GSI_PK (e.g., SESSION#{session_id}) - SK: GSI_SK (e.g., META for sessions, C#{timestamp} for costs) - -Projection: ALL -``` - -**Access Patterns via GSI:** - -```python -# Get session by ID (without knowing status or timestamp) -response = table.query( - IndexName="SessionLookupIndex", - KeyConditionExpression="GSI_PK = :pk AND GSI_SK = :sk", - ExpressionAttributeValues={ - ":pk": f"SESSION#{session_id}", - ":sk": "META" - } -) - -# Get all costs for a specific session -response = table.query( - IndexName="SessionLookupIndex", - KeyConditionExpression="GSI_PK = :pk AND begins_with(GSI_SK, :prefix)", - ExpressionAttributeValues={ - ":pk": f"SESSION#{session_id}", - ":prefix": "C#" - } -) -``` - -### Access Patterns (Primary Table) - -```python -# 1. List active sessions (sorted by most recent) - O(page_size) -response = table.query( - KeyConditionExpression="PK = :pk AND begins_with(SK, :prefix)", - ExpressionAttributeValues={ - ":pk": f"USER#{user_id}", - ":prefix": "S#ACTIVE#" - }, - ScanIndexForward=False, # Descending order (most recent first) - Limit=20, - ExclusiveStartKey=pagination_token # Native DynamoDB pagination works! -) - -# 2. List deleted sessions (for admin/recovery) -response = table.query( - KeyConditionExpression="PK = :pk AND begins_with(SK, :prefix)", - ExpressionAttributeValues={ - ":pk": f"USER#{user_id}", - ":prefix": "S#DELETED#" - }, - ScanIndexForward=False, - Limit=20 -) - -# 3. Get user costs in date range (for detailed reports) -response = table.query( - KeyConditionExpression="PK = :pk AND SK BETWEEN :start AND :end", - ExpressionAttributeValues={ - ":pk": f"USER#{user_id}", - ":start": f"C#{start_date}", - ":end": f"C#{end_date}~" # ~ sorts after any timestamp - } -) -``` - ---- - -## Session Deletion Flow - -### Soft Delete Process - -```python -async def delete_session(user_id: str, session_id: str) -> None: - """ - Soft-delete a session while preserving cost records. - - Steps: - 1. Get current session to find its SK - 2. Transactionally move from S#ACTIVE# to S#DELETED# prefix - 3. Delete conversation content from AgentCore Memory - 4. Cost records (C# prefix) remain untouched - """ - now = datetime.now(timezone.utc) - - # 1. Get current session via GSI - session = await get_session_by_id(user_id, session_id) - if not session: - raise NotFoundError(f"Session {session_id} not found") - - if session.deleted: - return # Already deleted - - # 2. Build old and new SKs - old_sk = f"S#ACTIVE#{session.last_message_at}#{session_id}" - new_sk = f"S#DELETED#{now.isoformat()}#{session_id}" - - # 3. Transactional move: delete old + create new - dynamodb.transact_write_items( - TransactItems=[ - { - 'Delete': { - 'TableName': 'SessionsMetadata', - 'Key': { - 'PK': f'USER#{user_id}', - 'SK': old_sk - }, - 'ConditionExpression': 'attribute_exists(PK)' - } - }, - { - 'Put': { - 'TableName': 'SessionsMetadata', - 'Item': { - 'PK': f'USER#{user_id}', - 'SK': new_sk, - 'GSI_PK': f'SESSION#{session_id}', - 'GSI_SK': 'META', - 'sessionId': session_id, - 'userId': user_id, - 'title': session.title, - 'status': 'deleted', - 'createdAt': session.created_at, - 'lastMessageAt': session.last_message_at, - 'messageCount': session.message_count, - 'starred': session.starred, - 'tags': session.tags, - 'preferences': session.preferences, - 'deleted': True, - 'deletedAt': now.isoformat() - } - } - } - ] - ) - - # 4. Delete conversation content from AgentCore Memory (async) - # This removes the actual messages but NOT the cost records - await agentcore_memory.delete_session(session_id) - - logger.info(f"Soft-deleted session {session_id} for user {user_id}") -``` - -### What Happens to Each Data Type - -| Data Type | SK Pattern | After Deletion | -|-----------|------------|----------------| -| Session metadata | `S#ACTIVE#...` → `S#DELETED#...` | Moved to deleted prefix | -| Conversation content | AgentCore Memory | **Deleted** (user expectation) | -| Per-message costs | `C#...` | **Preserved** (audit trail, unchanged) | -| User cost summary | `UserCostSummary` table | **Unchanged** (pre-aggregated) | -| System rollups | `SystemCostRollup` table | **Unchanged** | - ---- - -## Impact Analysis - -### User Features - -| Feature | Before | After | Impact | -|---------|--------|-------|--------| -| List sessions | Filter in memory, sort in memory | Query `S#ACTIVE#` prefix | **Much faster** | -| Get session | Query by old SK | Query GSI by session ID | Same | -| Update session | Update item | Transact if `lastMessageAt` changes | Slightly more complex | -| Delete session | Not supported | Soft delete | **New feature** | -| View cost summary | `UserCostSummary` | `UserCostSummary` | Unchanged | -| Detailed cost report | Query `SESSION#...#MSG#` | Query `C#` prefix | Same | -| Quota enforcement | `UserCostSummary` | `UserCostSummary` | Unchanged | - -### Admin Features - -| Feature | Before | After | Impact | -|---------|--------|-------|--------| -| System summary | `SystemCostRollup` | `SystemCostRollup` | Unchanged | -| Top users by cost | `UserCostSummary` GSI | `UserCostSummary` GSI | Unchanged | -| Cost by model | Query `SESSION#...#MSG#` | Query `C#` prefix | Same | -| Cost trends | Query `SESSION#...#MSG#` | Query `C#` prefix | Same | -| Per-session costs | Query by session prefix | Query GSI `SESSION#{id}` + `C#` | Same | -| View deleted sessions | Not supported | Query `S#DELETED#` prefix | **New feature** | - -### Performance Comparison - -| Operation | Current | After Refactor | -|-----------|---------|----------------| -| List 20 sessions (user with 100 sessions, 10k messages) | O(10,100) query + O(100) filter + O(100) sort | **O(20) query** | -| Get session by ID | O(1) | O(1) via GSI | -| Delete session | N/A | O(1) transact write | -| Per-session costs | O(m) query | O(m) query via GSI | -| Quota check | O(1) | O(1) | - ---- - -## Implementation Plan - -Since the application is not yet in production, this is a **greenfield implementation** rather than a migration. - -### Phase 1: Add GSI to Existing Table - -Add the `SessionLookupIndex` GSI to `SessionsMetadata`: - -```bash -aws dynamodb update-table \ - --table-name SessionsMetadata \ - --attribute-definitions \ - AttributeName=GSI_PK,AttributeType=S \ - AttributeName=GSI_SK,AttributeType=S \ - --global-secondary-index-updates \ - "[{ - \"Create\": { - \"IndexName\": \"SessionLookupIndex\", - \"KeySchema\": [ - {\"AttributeName\":\"GSI_PK\",\"KeyType\":\"HASH\"}, - {\"AttributeName\":\"GSI_SK\",\"KeyType\":\"RANGE\"} - ], - \"Projection\": {\"ProjectionType\":\"ALL\"} - } - }]" -``` - -### Phase 2: Update Backend Code - -Refactor code to use new SK patterns: - -| File | Changes | -|------|---------| -| `backend/src/apis/app_api/sessions/services/metadata.py` | New SK patterns for sessions and costs | -| `backend/src/apis/app_api/sessions/routes.py` | Add `DELETE /sessions/{id}` endpoint | -| `backend/src/apis/app_api/costs/aggregator.py` | Query `C#` prefix instead of `SESSION#...#MSG#` | -| `backend/src/apis/app_api/admin/costs/routes.py` | Update queries for cost reports | - -### Phase 3: Frontend Changes - -Add delete functionality: - -| File | Changes | -|------|---------| -| `session.service.ts` | Add `deleteSession()` method | -| Session list component | Add delete button with confirmation | - ---- - -## Implementation Details - -### Updated store_session_metadata - -```python -# backend/src/apis/app_api/sessions/services/metadata.py - -async def _store_session_metadata_cloud( - session_id: str, - user_id: str, - session_metadata: SessionMetadata, - table_name: str -) -> None: - """ - Store session metadata with new SK pattern. - - Schema: - PK: USER#{user_id} - SK: S#ACTIVE#{last_message_at}#{session_id} - - GSI: SessionLookupIndex - GSI_PK: SESSION#{session_id} - GSI_SK: META - """ - dynamodb = boto3.resource('dynamodb') - table = dynamodb.Table(table_name) - - # Prepare item - item = session_metadata.model_dump(by_alias=True, exclude_none=True) - item = _convert_floats_to_decimal(item) - - last_message_at = session_metadata.last_message_at or datetime.now(timezone.utc).isoformat() - - # Build keys with new pattern - item['PK'] = f'USER#{user_id}' - item['SK'] = f'S#ACTIVE#{last_message_at}#{session_id}' - - # GSI keys for direct lookup - item['GSI_PK'] = f'SESSION#{session_id}' - item['GSI_SK'] = 'META' - - # Note: NO ttl attribute - sessions persist until soft-deleted - - table.put_item(Item=item) - logger.info(f"Stored session metadata: {session_id}") -``` - -### Updated store_message_metadata - -```python -async def _store_message_metadata_cloud( - session_id: str, - user_id: str, - message_id: int, - message_metadata: MessageMetadata, - table_name: str -) -> None: - """ - Store message metadata with new SK pattern. - - Schema: - PK: USER#{user_id} - SK: C#{timestamp}#{uuid} - - GSI: SessionLookupIndex - GSI_PK: SESSION#{session_id} - GSI_SK: C#{timestamp} - """ - import uuid as uuid_lib - from datetime import datetime, timezone, timedelta - - dynamodb = boto3.resource('dynamodb') - table = dynamodb.Table(table_name) - - metadata_dict = message_metadata.model_dump(by_alias=True, exclude_none=True) - metadata_decimal = _convert_floats_to_decimal(metadata_dict) - - timestamp = metadata_dict.get("attribution", {}).get( - "timestamp", - datetime.now(timezone.utc).isoformat() - ) - - # Generate unique SK - unique_id = str(uuid_lib.uuid4()) - - # TTL: 365 days (only cost records have TTL) - ttl = int((datetime.now(timezone.utc) + timedelta(days=365)).timestamp()) - - item = { - # Primary key with new pattern - "PK": f"USER#{user_id}", - "SK": f"C#{timestamp}#{unique_id}", - - # GSI keys for per-session queries - "GSI_PK": f"SESSION#{session_id}", - "GSI_SK": f"C#{timestamp}", - - # Session reference - "sessionId": session_id, - "messageId": message_id, - - # Attribution - "userId": user_id, - "timestamp": timestamp, - - # TTL - only cost records have this - "ttl": ttl, - - # Metadata - **metadata_decimal - } - - table.put_item(Item=item) - - # Update cost summary (unchanged) - await _update_cost_summary_async( - user_id=user_id, - timestamp=timestamp, - message_metadata=message_metadata - ) -``` - -### Updated list_user_sessions - -```python -async def _list_user_sessions_cloud( - user_id: str, - table_name: str, - limit: Optional[int] = None, - next_token: Optional[str] = None -) -> Tuple[list[SessionMetadata], Optional[str]]: - """ - List sessions with new SK pattern. - - Key improvements: - - No in-memory filtering (S#ACTIVE# only matches sessions) - - No in-memory sorting (SK includes timestamp) - - True server-side pagination - """ - dynamodb = boto3.resource('dynamodb') - table = dynamodb.Table(table_name) - - query_params = { - 'KeyConditionExpression': Key('PK').eq(f'USER#{user_id}') & Key('SK').begins_with('S#ACTIVE#'), - 'ScanIndexForward': False # Descending (most recent first) - } - - if limit: - query_params['Limit'] = limit - - if next_token: - query_params['ExclusiveStartKey'] = json.loads( - base64.b64decode(next_token).decode('utf-8') - ) - - response = table.query(**query_params) - - sessions = [] - for item in response.get('Items', []): - item = _convert_decimal_to_float(item) - # Remove DynamoDB keys - for key in ['PK', 'SK', 'GSI_PK', 'GSI_SK']: - item.pop(key, None) - sessions.append(SessionMetadata.model_validate(item)) - - # Generate next_token from LastEvaluatedKey - next_page_token = None - if 'LastEvaluatedKey' in response: - next_page_token = base64.b64encode( - json.dumps(response['LastEvaluatedKey']).encode('utf-8') - ).decode('utf-8') - - return sessions, next_page_token -``` - -### Session Service for Delete - -```python -# backend/src/apis/app_api/sessions/services/session_service.py - -class SessionService: - """Service for session CRUD operations.""" - - def __init__(self): - self.dynamodb = boto3.resource('dynamodb') - self.table_name = os.environ.get('DYNAMODB_SESSIONS_METADATA_TABLE_NAME', 'SessionsMetadata') - self.table = self.dynamodb.Table(self.table_name) - - async def get_session(self, user_id: str, session_id: str) -> Optional[SessionMetadata]: - """Get session by ID using GSI.""" - response = self.table.query( - IndexName='SessionLookupIndex', - KeyConditionExpression=Key('GSI_PK').eq(f'SESSION#{session_id}') & Key('GSI_SK').eq('META') - ) - - items = response.get('Items', []) - if not items: - return None - - item = _convert_decimal_to_float(items[0]) - - # Verify user ownership - if item.get('userId') != user_id: - return None - - # Remove DynamoDB keys - for key in ['PK', 'SK', 'GSI_PK', 'GSI_SK']: - item.pop(key, None) - - return SessionMetadata.model_validate(item) - - async def delete_session(self, user_id: str, session_id: str) -> bool: - """ - Soft-delete a session. - - Moves from S#ACTIVE# to S#DELETED# prefix. - Deletes conversation content from AgentCore Memory. - Preserves cost records (C# prefix). - """ - session = await self.get_session(user_id, session_id) - if not session: - return False - - if session.deleted: - return True # Already deleted - - now = datetime.now(timezone.utc) - - old_sk = f'S#ACTIVE#{session.last_message_at}#{session_id}' - new_sk = f'S#DELETED#{now.isoformat()}#{session_id}' - - # Build deleted item - deleted_item = { - 'PK': {'S': f'USER#{user_id}'}, - 'SK': {'S': new_sk}, - 'GSI_PK': {'S': f'SESSION#{session_id}'}, - 'GSI_SK': {'S': 'META'}, - 'sessionId': {'S': session_id}, - 'userId': {'S': user_id}, - 'title': {'S': session.title or ''}, - 'status': {'S': 'deleted'}, - 'createdAt': {'S': session.created_at}, - 'lastMessageAt': {'S': session.last_message_at}, - 'messageCount': {'N': str(session.message_count or 0)}, - 'deleted': {'BOOL': True}, - 'deletedAt': {'S': now.isoformat()} - } - - # Transactional move - self.dynamodb.meta.client.transact_write_items( - TransactItems=[ - { - 'Delete': { - 'TableName': self.table_name, - 'Key': { - 'PK': {'S': f'USER#{user_id}'}, - 'SK': {'S': old_sk} - } - } - }, - { - 'Put': { - 'TableName': self.table_name, - 'Item': deleted_item - } - } - ] - ) - - # Delete conversation content from AgentCore Memory - await self._delete_agentcore_memory(session_id) - - return True - - async def _delete_agentcore_memory(self, session_id: str) -> None: - """Delete conversation content from AgentCore Memory.""" - # Implementation depends on AgentCore Memory API - pass -``` - ---- - -## API Changes - -### New Endpoint: Delete Session - -```python -# backend/src/apis/app_api/sessions/routes.py - -@router.delete("/{session_id}", status_code=204) -async def delete_session( - session_id: str, - current_user: User = Depends(get_current_user) -): - """ - Delete a conversation. - - This soft-deletes the session metadata and permanently deletes - the conversation content from AgentCore Memory. - - Cost records are preserved for billing and audit purposes. - - Args: - session_id: Session identifier - current_user: Authenticated user - - Returns: - 204 No Content on success - - Raises: - 404: Session not found - """ - service = SessionService() - deleted = await service.delete_session( - user_id=current_user.user_id, - session_id=session_id - ) - - if not deleted: - raise HTTPException(status_code=404, detail="Session not found") - - return Response(status_code=204) -``` - -### Frontend Service Update - -```typescript -// frontend/ai.client/src/app/session/services/session/session.service.ts - -@Injectable({ providedIn: 'root' }) -export class SessionService { - private http = inject(HttpClient); - - /** - * Delete a conversation. - * - * This removes the conversation from the user's list and deletes - * the message content. Cost records are preserved. - */ - deleteSession(sessionId: string): Observable { - return this.http.delete(`${environment.apiUrl}/sessions/${sessionId}`); - } -} -``` - -### Frontend Component Update - -```typescript -@Component({ - selector: 'app-session-list-item', - changeDetection: ChangeDetectionStrategy.OnPush, - imports: [NgIcon], - providers: [provideIcons({ heroTrash })], - template: ` -
- {{ session().title }} - - -
- - @if (showConfirmDialog()) { - - } - ` -}) -export class SessionListItemComponent { - session = input.required(); - deleted = output(); - - private sessionService = inject(SessionService); - - showConfirmDialog = signal(false); - isDeleting = signal(false); - - onDelete(event: Event) { - event.stopPropagation(); - this.showConfirmDialog.set(true); - } - - confirmDelete() { - this.isDeleting.set(true); - - this.sessionService.deleteSession(this.session().sessionId) - .pipe(finalize(() => { - this.isDeleting.set(false); - this.showConfirmDialog.set(false); - })) - .subscribe({ - next: () => this.deleted.emit(this.session().sessionId), - error: (err) => console.error('Failed to delete session:', err) - }); - } -} -``` - ---- - -## Testing Strategy - -### Unit Tests - -```python -class TestSessionService: - - async def test_list_sessions_returns_only_active(self, mock_dynamodb): - """Listing sessions should not include deleted sessions.""" - service = SessionService() - - # Create active and deleted sessions - await create_session_with_sk("S#ACTIVE#2025-01-15T10:00:00Z#session1", ...) - await create_session_with_sk("S#DELETED#2025-01-15T11:00:00Z#session2", ...) - - sessions, _ = await service.list_sessions(user_id="alice") - - assert len(sessions) == 1 - assert sessions[0].session_id == "session1" - - async def test_delete_session_preserves_cost_records(self, mock_dynamodb): - """Deleting a session should not affect cost records (C# prefix).""" - # Create session and cost records - await create_session_with_sk("S#ACTIVE#...", ...) - await create_cost_record("C#2025-01-15T10:00:00Z#uuid1", session_id="abc") - await create_cost_record("C#2025-01-15T10:01:00Z#uuid2", session_id="abc") - - # Delete session - await service.delete_session(user_id="alice", session_id="abc") - - # Cost records should still exist - costs = await get_costs_for_session("abc") - assert len(costs) == 2 - - async def test_list_sessions_no_longer_returns_cost_records(self, mock_dynamodb): - """Cost records (C# prefix) should never appear in session listing.""" - # Create session and many cost records - await create_session_with_sk("S#ACTIVE#...", ...) - for i in range(100): - await create_cost_record(f"C#2025-01-15T10:{i:02d}:00Z#uuid{i}", ...) - - sessions, _ = await service.list_sessions(user_id="alice", limit=20) - - # Should only get the 1 session, not cost records - assert len(sessions) == 1 -``` - -### Performance Tests - -```python -async def test_list_sessions_performance_with_many_costs(self, mock_dynamodb): - """ - Verify O(page_size) performance even with many cost records. - - Old implementation: O(sessions + messages) with in-memory filtering - New implementation: O(page_size) direct query - """ - # Create 100 sessions with 100 cost records each = 10,000 total records - for i in range(100): - await create_session_with_sk(f"S#ACTIVE#...", session_id=f"session{i}") - for j in range(100): - await create_cost_record(f"C#...", session_id=f"session{i}") - - # Time the list operation - start = time.time() - sessions, _ = await service.list_sessions(user_id="alice", limit=20) - elapsed = time.time() - start - - assert len(sessions) == 20 - assert elapsed < 0.1 # Should be <100ms -``` - ---- - -## Rollback Plan - -Since this is pre-production, rollback is straightforward: - -1. **Revert code changes** via git -2. **Remove GSI** (optional - GSI doesn't break old code) -3. Old SK patterns continue to work - ---- - -## Success Metrics - -| Metric | Target | Measurement | -|--------|--------|-------------| -| Session listing latency | <100ms p99 | CloudWatch metrics | -| Session deletion latency | <500ms p99 | CloudWatch metrics | -| Cost accuracy after deletion | 100% | Automated tests | -| Quota accuracy after deletion | 100% | Automated tests | -| Zero data loss during deletion | 100% | Cost record comparison | - ---- - -## Open Questions - -### 1. Hard Delete vs Soft Delete Only - -**Current Decision**: Soft delete only (move to `S#DELETED#` prefix) - -**Recommendation**: Implement soft delete first. Add scheduled hard delete in future if storage costs become significant. - -### 2. Bulk Delete - -**Question**: Should users be able to delete multiple sessions at once? - -**Recommendation**: Phase 2 feature. Single delete first, then add bulk delete endpoint. - -### 3. Admin Restore Capability - -**Question**: Should admins be able to restore deleted sessions? - -**Recommendation**: Session metadata can be restored (move from `S#DELETED#` to `S#ACTIVE#`), but AgentCore Memory content cannot be recovered. Document this limitation. - ---- - -## Summary: SK Pattern Changes - -| Record Type | Old SK Pattern | New SK Pattern | -|-------------|----------------|----------------| -| Active session | `SESSION#{session_id}` | `S#ACTIVE#{last_message_at}#{session_id}` | -| Deleted session | N/A | `S#DELETED#{deleted_at}#{session_id}` | -| Message cost | `SESSION#{session_id}#MSG#{message_id}` | `C#{timestamp}#{uuid}` | - -**Key Benefits:** -- Clean prefix separation enables efficient queries -- Timestamp in session SK enables server-side sorted pagination -- Single table = simpler operations -- No new tables to create or manage -- TTL only affects cost records (sessions don't have `ttl` attribute) diff --git a/docs/USER_ADMIN_SPEC.md b/docs/USER_ADMIN_SPEC.md deleted file mode 100644 index 31963f02..00000000 --- a/docs/USER_ADMIN_SPEC.md +++ /dev/null @@ -1,2310 +0,0 @@ -# User Admin System - Implementation Specification - -**Version:** 1.0 -**Created:** 2025-12-27 -**Status:** Ready for Implementation - ---- - -## Table of Contents - -1. [Overview](#overview) -2. [Scope](#scope) -3. [DynamoDB Schema](#dynamodb-schema) -4. [Backend Implementation](#backend-implementation) -5. [Frontend Implementation](#frontend-implementation) -6. [User Sync Strategy](#user-sync-strategy) -7. [Testing Strategy](#testing-strategy) -8. [Deployment Plan](#deployment-plan) -9. [Validation Criteria](#validation-criteria) - ---- - -## Overview - -### Objectives - -Provide admins with a centralized user lookup view to: -- Search and browse users -- View user profile information synced from JWT -- See user cost and quota status at a glance -- Access user-specific quota events and history -- Take admin actions (create overrides, assign tiers) - -### Design Principles - -1. **Scan-Free Queries** - All access patterns use GSIs, no table scans -2. **Just-in-Time Sync** - User records created/updated from JWT on login -3. **Eventual Consistency** - `lastLoginAt` updated on login, not per-request -4. **Composable Queries** - User detail aggregates data from multiple tables in parallel - ---- - -## Scope - -### Included - -**User Management:** -- User record storage with JWT-synced data -- Search by email (exact match) -- Browse by email domain -- Browse by status + recent login -- User detail view with aggregated data - -**User Detail View:** -- Profile info (email, name, roles, picture) -- Current month cost summary -- Quota status (resolved tier, usage, remaining) -- Recent quota events -- Admin actions (create override, assign tier) - -**Admin Dashboard Widgets:** -- Recently active users -- Users approaching quota (80%+) -- Users by email domain - -### Not Included (Future Consideration) - -- Full-text search (name/email partial match) -- User suspension/account management -- Usage analytics and trends -- Session history browsing -- Data export (GDPR) - ---- - -## DynamoDB Schema - -### Users Table - -``` -Table: Users -Environment Variable: DYNAMODB_USERS_TABLE_NAME (default: "Users") -═══════════════════════════════════════════════════════════════ - -Primary Key: - PK: USER# - SK: PROFILE - -Attributes: - userId: string # From JWT "sub" claim - email: string # Lowercase, from JWT - name: string # From JWT "name" claim - roles: string[] # From JWT "roles" claim (stored as List) - picture: string? # From JWT "picture" claim (optional) - emailDomain: string # Extracted from email, lowercase - createdAt: string # ISO timestamp, first login - lastLoginAt: string # ISO timestamp, updated on each login - status: string # "active" | "inactive" | "suspended" - -═══════════════════════════════════════════════════════════════ -``` - -### Global Secondary Indexes - -| GSI | PK | SK | Projection | Use Case | -|-----|----|----|------------|----------| -| **UserIdIndex** | `userId` | - | ALL | O(1) lookup by user ID (for deep links) | -| **EmailIndex** | `email` | - | ALL | O(1) exact email lookup | -| **EmailDomainIndex** | `DOMAIN#` | `lastLoginAt` | KEYS_ONLY + userId, email, name, status | Browse users by company/domain | -| **StatusLoginIndex** | `STATUS#` | `lastLoginAt` | KEYS_ONLY + userId, email, name, emailDomain | Browse active users by recency | - -### Access Patterns - -| Pattern | Query | GSI | Notes | -|---------|-------|-----|-------| -| Get user by ID (internal) | `PK = USER#` | - | Primary key lookup (requires PK prefix) | -| Get user by ID (deep link) | `userId = ` | UserIdIndex | Direct ID lookup for admin deep links | -| Get user by email | `email = ` | EmailIndex | Case-insensitive (store lowercase) | -| List users by domain | `PK = DOMAIN#`, sorted by `lastLoginAt` | EmailDomainIndex | Paginated, most recent first | -| List active users | `PK = STATUS#active`, sorted by `lastLoginAt` | StatusLoginIndex | Paginated, most recent first | -| List inactive users | `PK = STATUS#inactive`, sorted by `lastLoginAt` | StatusLoginIndex | Users with old lastLoginAt | - -### Deep Link Support - -The `UserIdIndex` enables admin deep links to user detail pages: - -``` -/admin/users/:userId -``` - -This is used by: -- **TopUsersTableComponent** - Click on a row to navigate to user detail -- **Cost Dashboard** - Click on user in cost breakdown -- **Quota Events** - Click on user ID to view user detail -- **External links** - Share user detail URL with other admins - -#### Integration with Existing Components - -**TopUsersTableComponent** (`frontend/ai.client/src/app/admin/costs/components/top-users-table.component.ts`) - -Already emits `userClick` event with `userId`. Update the parent component's handler: - -```typescript -// In admin-costs.page.ts -onUserClick(userId: string): void { - this.router.navigate(['/admin/users', userId]); -} -``` - -**Quota Event Viewer** - Add user ID links in the event list to navigate to user detail. - -### Capacity Planning (30K Users) - -**Read Capacity:** -- User lookup: 1 RCU per request -- List queries: ~10 RCU per page (25 items) -- Expected: 100-500 RCU sustained - -**Write Capacity:** -- User sync on login: 1 WCU per login -- 30K users × 2 logins/day = 60K writes/day = ~1 WCU sustained -- Peak: 10-50 WCU (morning login surge) - -**Recommendation:** On-demand capacity mode - ---- - -## Backend Implementation - -### Directory Structure - -``` -backend/src/ -├── apis/ -│ └── app_api/ -│ └── admin/ -│ └── users/ -│ ├── __init__.py -│ ├── routes.py # API endpoints -│ ├── service.py # Business logic -│ └── models.py # Request/response models -└── users/ - ├── __init__.py - ├── models.py # Domain models - ├── repository.py # DynamoDB operations - └── sync.py # JWT sync logic -``` - -### Domain Models - -**File:** `backend/src/users/models.py` - -```python -from pydantic import BaseModel, Field, field_validator -from typing import List, Optional -from datetime import datetime - -class UserProfile(BaseModel): - """User profile stored in DynamoDB""" - user_id: str = Field(..., alias="userId") - email: str - name: str - roles: List[str] = Field(default_factory=list) - picture: Optional[str] = None - email_domain: str = Field(..., alias="emailDomain") - created_at: str = Field(..., alias="createdAt") - last_login_at: str = Field(..., alias="lastLoginAt") - status: str = Field(default="active") - - @field_validator('email', mode='before') - @classmethod - def lowercase_email(cls, v: str) -> str: - return v.lower() if v else v - - @field_validator('email_domain', mode='before') - @classmethod - def lowercase_domain(cls, v: str) -> str: - return v.lower() if v else v - - class Config: - populate_by_name = True - - -class UserListItem(BaseModel): - """Minimal user info for list views""" - user_id: str = Field(..., alias="userId") - email: str - name: str - status: str - last_login_at: str = Field(..., alias="lastLoginAt") - email_domain: Optional[str] = Field(None, alias="emailDomain") - - -class UserDetailView(BaseModel): - """Comprehensive user view for admin detail page""" - profile: UserProfile - - # Cost summary (from UserCostSummary table) - current_month_cost: float = Field(0.0, alias="currentMonthCost") - current_month_requests: int = Field(0, alias="currentMonthRequests") - - # Quota status (from quota resolver) - quota_tier_name: Optional[str] = Field(None, alias="quotaTierName") - quota_matched_by: Optional[str] = Field(None, alias="quotaMatchedBy") - quota_limit: Optional[float] = Field(None, alias="quotaLimit") - quota_usage_percentage: float = Field(0.0, alias="quotaUsagePercentage") - quota_remaining: Optional[float] = Field(None, alias="quotaRemaining") - has_active_override: bool = Field(False, alias="hasActiveOverride") - - # Recent events (from QuotaEvents) - recent_events: List[dict] = Field(default_factory=list, alias="recentEvents") - - class Config: - populate_by_name = True -``` - -### Repository - -**File:** `backend/src/users/repository.py` - -```python -import logging -from typing import Optional, List, Tuple -from datetime import datetime -from botocore.exceptions import ClientError - -from .models import UserProfile, UserListItem - -logger = logging.getLogger(__name__) - - -class UserRepository: - """DynamoDB repository for user operations""" - - def __init__(self, dynamodb_client, table_name: str): - self._client = dynamodb_client - self._table_name = table_name - - # ========== Single User Operations ========== - - async def get_user(self, user_id: str) -> Optional[UserProfile]: - """ - Get user by ID using primary key. - Use this for internal operations where you have the full PK. - """ - try: - response = self._client.get_item( - TableName=self._table_name, - Key={ - "PK": {"S": f"USER#{user_id}"}, - "SK": {"S": "PROFILE"} - } - ) - item = response.get("Item") - if not item: - return None - return self._item_to_profile(item) - except ClientError as e: - logger.error(f"Error getting user {user_id}: {e}") - raise - - async def get_user_by_user_id(self, user_id: str) -> Optional[UserProfile]: - """ - Get user by userId attribute via UserIdIndex GSI. - Use this for admin deep links where you only have the raw user ID. - """ - try: - response = self._client.query( - TableName=self._table_name, - IndexName="UserIdIndex", - KeyConditionExpression="userId = :userId", - ExpressionAttributeValues={ - ":userId": {"S": user_id} - }, - Limit=1 - ) - items = response.get("Items", []) - if not items: - return None - return self._item_to_profile(items[0]) - except ClientError as e: - logger.error(f"Error getting user by userId {user_id}: {e}") - raise - - async def get_user_by_email(self, email: str) -> Optional[UserProfile]: - """Get user by email (case-insensitive)""" - try: - response = self._client.query( - TableName=self._table_name, - IndexName="EmailIndex", - KeyConditionExpression="email = :email", - ExpressionAttributeValues={ - ":email": {"S": email.lower()} - }, - Limit=1 - ) - items = response.get("Items", []) - if not items: - return None - return self._item_to_profile(items[0]) - except ClientError as e: - logger.error(f"Error getting user by email {email}: {e}") - raise - - async def create_user(self, profile: UserProfile) -> UserProfile: - """Create a new user""" - item = self._profile_to_item(profile) - try: - self._client.put_item( - TableName=self._table_name, - Item=item, - ConditionExpression="attribute_not_exists(PK)" - ) - return profile - except ClientError as e: - if e.response["Error"]["Code"] == "ConditionalCheckFailedException": - raise ValueError(f"User {profile.user_id} already exists") - logger.error(f"Error creating user: {e}") - raise - - async def update_user(self, user_id: str, profile: UserProfile) -> UserProfile: - """Update existing user""" - item = self._profile_to_item(profile) - try: - self._client.put_item( - TableName=self._table_name, - Item=item - ) - return profile - except ClientError as e: - logger.error(f"Error updating user {user_id}: {e}") - raise - - async def upsert_user(self, profile: UserProfile) -> Tuple[UserProfile, bool]: - """ - Create or update user. - Returns (profile, is_new_user) - """ - existing = await self.get_user(profile.user_id) - if existing: - # Preserve createdAt from existing record - profile.created_at = existing.created_at - await self.update_user(profile.user_id, profile) - return profile, False - else: - await self.create_user(profile) - return profile, True - - # ========== List Operations ========== - - async def list_users_by_domain( - self, - domain: str, - limit: int = 25, - last_evaluated_key: Optional[dict] = None - ) -> Tuple[List[UserListItem], Optional[dict]]: - """List users by email domain, sorted by last login (descending)""" - try: - kwargs = { - "TableName": self._table_name, - "IndexName": "EmailDomainIndex", - "KeyConditionExpression": "GSI2PK = :pk", - "ExpressionAttributeValues": { - ":pk": {"S": f"DOMAIN#{domain.lower()}"} - }, - "ScanIndexForward": False, # Most recent first - "Limit": limit - } - if last_evaluated_key: - kwargs["ExclusiveStartKey"] = last_evaluated_key - - response = self._client.query(**kwargs) - items = [self._item_to_list_item(item) for item in response.get("Items", [])] - next_key = response.get("LastEvaluatedKey") - return items, next_key - except ClientError as e: - logger.error(f"Error listing users by domain {domain}: {e}") - raise - - async def list_users_by_status( - self, - status: str = "active", - limit: int = 25, - last_evaluated_key: Optional[dict] = None - ) -> Tuple[List[UserListItem], Optional[dict]]: - """List users by status, sorted by last login (descending)""" - try: - kwargs = { - "TableName": self._table_name, - "IndexName": "StatusLoginIndex", - "KeyConditionExpression": "GSI3PK = :pk", - "ExpressionAttributeValues": { - ":pk": {"S": f"STATUS#{status}"} - }, - "ScanIndexForward": False, # Most recent first - "Limit": limit - } - if last_evaluated_key: - kwargs["ExclusiveStartKey"] = last_evaluated_key - - response = self._client.query(**kwargs) - items = [self._item_to_list_item(item) for item in response.get("Items", [])] - next_key = response.get("LastEvaluatedKey") - return items, next_key - except ClientError as e: - logger.error(f"Error listing users by status {status}: {e}") - raise - - # ========== Helpers ========== - - def _profile_to_item(self, profile: UserProfile) -> dict: - """Convert UserProfile to DynamoDB item""" - item = { - "PK": {"S": f"USER#{profile.user_id}"}, - "SK": {"S": "PROFILE"}, - "userId": {"S": profile.user_id}, - "email": {"S": profile.email.lower()}, - "name": {"S": profile.name}, - "roles": {"L": [{"S": r} for r in profile.roles]}, - "emailDomain": {"S": profile.email_domain.lower()}, - "createdAt": {"S": profile.created_at}, - "lastLoginAt": {"S": profile.last_login_at}, - "status": {"S": profile.status}, - # GSI keys - "GSI2PK": {"S": f"DOMAIN#{profile.email_domain.lower()}"}, - "GSI2SK": {"S": profile.last_login_at}, - "GSI3PK": {"S": f"STATUS#{profile.status}"}, - "GSI3SK": {"S": profile.last_login_at}, - } - if profile.picture: - item["picture"] = {"S": profile.picture} - return item - - def _item_to_profile(self, item: dict) -> UserProfile: - """Convert DynamoDB item to UserProfile""" - return UserProfile( - user_id=item["userId"]["S"], - email=item["email"]["S"], - name=item["name"]["S"], - roles=[r["S"] for r in item.get("roles", {}).get("L", [])], - picture=item.get("picture", {}).get("S"), - email_domain=item["emailDomain"]["S"], - created_at=item["createdAt"]["S"], - last_login_at=item["lastLoginAt"]["S"], - status=item.get("status", {}).get("S", "active") - ) - - def _item_to_list_item(self, item: dict) -> UserListItem: - """Convert DynamoDB item to UserListItem""" - return UserListItem( - user_id=item["userId"]["S"], - email=item["email"]["S"], - name=item["name"]["S"], - status=item.get("status", {}).get("S", "active"), - last_login_at=item["lastLoginAt"]["S"], - email_domain=item.get("emailDomain", {}).get("S") - ) -``` - -### User Sync Service - -**File:** `backend/src/users/sync.py` - -```python -import logging -from datetime import datetime -from typing import Tuple - -from .models import UserProfile -from .repository import UserRepository - -logger = logging.getLogger(__name__) - - -class UserSyncService: - """ - Syncs user data from JWT claims to DynamoDB. - Called on each login/token refresh. - """ - - def __init__(self, repository: UserRepository): - self._repository = repository - - async def sync_from_jwt(self, jwt_claims: dict) -> Tuple[UserProfile, bool]: - """ - Create or update user from JWT claims. - - Args: - jwt_claims: Decoded JWT payload containing user info - - Returns: - Tuple of (UserProfile, is_new_user) - """ - user_id = jwt_claims.get("sub") - if not user_id: - raise ValueError("JWT missing 'sub' claim") - - email = jwt_claims.get("email", "") - if not email: - raise ValueError("JWT missing 'email' claim") - - # Extract domain from email - email_domain = email.split("@")[1] if "@" in email else "" - - now = datetime.utcnow().isoformat() + "Z" - - # Build profile from JWT claims - profile = UserProfile( - user_id=user_id, - email=email.lower(), - name=jwt_claims.get("name", ""), - roles=jwt_claims.get("roles", []), - picture=jwt_claims.get("picture"), - email_domain=email_domain.lower(), - created_at=now, # Will be overwritten if user exists - last_login_at=now, - status="active" - ) - - # Upsert user - profile, is_new = await self._repository.upsert_user(profile) - - if is_new: - logger.info(f"Created new user: {user_id} ({email})") - else: - logger.debug(f"Updated user: {user_id} ({email})") - - return profile, is_new -``` - -### Admin API Routes - -**File:** `backend/src/apis/app_api/admin/users/routes.py` - -```python -from fastapi import APIRouter, Depends, HTTPException, Query -from typing import List, Optional - -from apis.shared.auth.dependencies import require_admin -from apis.shared.auth.models import User - -from .service import UserAdminService -from .models import ( - UserListResponse, - UserDetailResponse, - UserSearchQuery -) - -router = APIRouter(prefix="/users", tags=["Admin - Users"]) - - -def get_user_service() -> UserAdminService: - """Dependency to get UserAdminService instance""" - # Implementation depends on your DI setup - from apis.shared.dependencies import get_user_admin_service - return get_user_admin_service() - - -@router.get("", response_model=UserListResponse) -async def list_users( - status: str = Query("active", description="Filter by status"), - domain: Optional[str] = Query(None, description="Filter by email domain"), - limit: int = Query(25, ge=1, le=100), - cursor: Optional[str] = Query(None, description="Pagination cursor"), - admin_user: User = Depends(require_admin), - service: UserAdminService = Depends(get_user_service) -): - """ - List users with optional filters. - - - **status**: Filter by user status (active, inactive, suspended) - - **domain**: Filter by email domain (e.g., "example.com") - - **limit**: Number of results per page (1-100) - - **cursor**: Pagination cursor from previous response - """ - return await service.list_users( - status=status, - domain=domain, - limit=limit, - cursor=cursor - ) - - -@router.get("/search", response_model=UserListResponse) -async def search_users( - email: str = Query(..., description="Email to search (exact match)"), - admin_user: User = Depends(require_admin), - service: UserAdminService = Depends(get_user_service) -): - """ - Search for a user by exact email match. - """ - user = await service.search_by_email(email) - if not user: - return UserListResponse(users=[], next_cursor=None) - return UserListResponse(users=[user], next_cursor=None) - - -@router.get("/{user_id}", response_model=UserDetailResponse) -async def get_user_detail( - user_id: str, - admin_user: User = Depends(require_admin), - service: UserAdminService = Depends(get_user_service) -): - """ - Get comprehensive user detail including: - - Profile information - - Current month cost summary - - Quota status - - Recent quota events - """ - detail = await service.get_user_detail(user_id) - if not detail: - raise HTTPException(status_code=404, detail=f"User {user_id} not found") - return detail - - -@router.get("/domains/list", response_model=List[str]) -async def list_email_domains( - limit: int = Query(50, ge=1, le=200), - admin_user: User = Depends(require_admin), - service: UserAdminService = Depends(get_user_service) -): - """ - List distinct email domains with user counts. - Useful for domain filter dropdown. - """ - return await service.list_domains(limit=limit) -``` - -### Admin API Models - -**File:** `backend/src/apis/app_api/admin/users/models.py` - -```python -from pydantic import BaseModel, Field -from typing import List, Optional - - -class UserListItem(BaseModel): - """User item for list views""" - user_id: str = Field(..., alias="userId") - email: str - name: str - status: str - last_login_at: str = Field(..., alias="lastLoginAt") - email_domain: Optional[str] = Field(None, alias="emailDomain") - - # Quick stats (optional, populated for dashboard views) - current_month_cost: Optional[float] = Field(None, alias="currentMonthCost") - quota_usage_percentage: Optional[float] = Field(None, alias="quotaUsagePercentage") - - class Config: - populate_by_name = True - - -class UserListResponse(BaseModel): - """Paginated user list response""" - users: List[UserListItem] - next_cursor: Optional[str] = Field(None, alias="nextCursor") - total_count: Optional[int] = Field(None, alias="totalCount") - - class Config: - populate_by_name = True - - -class QuotaStatus(BaseModel): - """User's current quota status""" - tier_id: Optional[str] = Field(None, alias="tierId") - tier_name: Optional[str] = Field(None, alias="tierName") - matched_by: Optional[str] = Field(None, alias="matchedBy") - monthly_limit: Optional[float] = Field(None, alias="monthlyLimit") - current_usage: float = Field(0.0, alias="currentUsage") - usage_percentage: float = Field(0.0, alias="usagePercentage") - remaining: Optional[float] = None - has_active_override: bool = Field(False, alias="hasActiveOverride") - override_reason: Optional[str] = Field(None, alias="overrideReason") - - class Config: - populate_by_name = True - - -class CostSummary(BaseModel): - """User's current month cost summary""" - total_cost: float = Field(0.0, alias="totalCost") - total_requests: int = Field(0, alias="totalRequests") - total_input_tokens: int = Field(0, alias="totalInputTokens") - total_output_tokens: int = Field(0, alias="totalOutputTokens") - cache_savings: float = Field(0.0, alias="cacheSavings") - primary_model: Optional[str] = Field(None, alias="primaryModel") - - class Config: - populate_by_name = True - - -class QuotaEventSummary(BaseModel): - """Summary of a quota event""" - event_id: str = Field(..., alias="eventId") - event_type: str = Field(..., alias="eventType") - timestamp: str - percentage_used: float = Field(..., alias="percentageUsed") - - class Config: - populate_by_name = True - - -class UserProfile(BaseModel): - """Full user profile""" - user_id: str = Field(..., alias="userId") - email: str - name: str - roles: List[str] = Field(default_factory=list) - picture: Optional[str] = None - email_domain: str = Field(..., alias="emailDomain") - created_at: str = Field(..., alias="createdAt") - last_login_at: str = Field(..., alias="lastLoginAt") - status: str - - class Config: - populate_by_name = True - - -class UserDetailResponse(BaseModel): - """Comprehensive user detail for admin view""" - profile: UserProfile - cost_summary: CostSummary = Field(..., alias="costSummary") - quota_status: QuotaStatus = Field(..., alias="quotaStatus") - recent_events: List[QuotaEventSummary] = Field( - default_factory=list, - alias="recentEvents" - ) - - class Config: - populate_by_name = True -``` - -### Admin Service - -**File:** `backend/src/apis/app_api/admin/users/service.py` - -```python -import asyncio -import logging -import base64 -import json -from typing import Optional, List -from datetime import datetime - -from users.repository import UserRepository -from users.models import UserProfile, UserListItem -from apis.app_api.costs.aggregator import CostAggregator -from agents.main_agent.quota.resolver import QuotaResolver -from agents.main_agent.quota.repository import QuotaRepository -from apis.shared.auth.models import User - -from .models import ( - UserListResponse, - UserDetailResponse, - QuotaStatus, - CostSummary, - QuotaEventSummary -) - -logger = logging.getLogger(__name__) - - -class UserAdminService: - """Service for user admin operations""" - - def __init__( - self, - user_repository: UserRepository, - cost_aggregator: CostAggregator, - quota_resolver: QuotaResolver, - quota_repository: QuotaRepository - ): - self._user_repo = user_repository - self._cost_aggregator = cost_aggregator - self._quota_resolver = quota_resolver - self._quota_repo = quota_repository - - async def list_users( - self, - status: str = "active", - domain: Optional[str] = None, - limit: int = 25, - cursor: Optional[str] = None - ) -> UserListResponse: - """List users with filters and pagination""" - - # Decode cursor if provided - last_key = None - if cursor: - try: - last_key = json.loads(base64.b64decode(cursor).decode()) - except Exception: - pass - - # Query based on filters - if domain: - users, next_key = await self._user_repo.list_users_by_domain( - domain=domain, - limit=limit, - last_evaluated_key=last_key - ) - else: - users, next_key = await self._user_repo.list_users_by_status( - status=status, - limit=limit, - last_evaluated_key=last_key - ) - - # Encode next cursor - next_cursor = None - if next_key: - next_cursor = base64.b64encode(json.dumps(next_key).encode()).decode() - - return UserListResponse( - users=users, - next_cursor=next_cursor - ) - - async def search_by_email(self, email: str) -> Optional[UserListItem]: - """Search for user by exact email""" - profile = await self._user_repo.get_user_by_email(email) - if not profile: - return None - - return UserListItem( - user_id=profile.user_id, - email=profile.email, - name=profile.name, - status=profile.status, - last_login_at=profile.last_login_at, - email_domain=profile.email_domain - ) - - async def get_user_detail(self, user_id: str) -> Optional[UserDetailResponse]: - """ - Get comprehensive user detail. - Uses UserIdIndex GSI to support admin deep links by raw user ID. - """ - - # Get user profile using UserIdIndex (for deep link support) - profile = await self._user_repo.get_user_by_user_id(user_id) - if not profile: - return None - - # Parallel fetch of related data - current_period = datetime.utcnow().strftime("%Y-%m") - - # Create a mock User object for quota resolution - user = User( - user_id=profile.user_id, - email=profile.email, - name=profile.name, - roles=profile.roles - ) - - cost_summary_task = self._cost_aggregator.get_user_cost_summary( - user_id=user_id, - period=current_period - ) - quota_task = self._quota_resolver.resolve_user_quota(user) - events_task = self._quota_repo.list_user_events( - user_id=user_id, - limit=5 - ) - - # Await all in parallel - cost_data, resolved_quota, recent_events = await asyncio.gather( - cost_summary_task, - quota_task, - events_task, - return_exceptions=True - ) - - # Build cost summary - cost_summary = CostSummary(total_cost=0.0, total_requests=0) - if cost_data and not isinstance(cost_data, Exception): - cost_summary = CostSummary( - total_cost=cost_data.total_cost, - total_requests=cost_data.total_requests, - total_input_tokens=cost_data.total_input_tokens, - total_output_tokens=cost_data.total_output_tokens, - cache_savings=cost_data.total_cache_savings, - primary_model=self._get_primary_model(cost_data) - ) - - # Build quota status - quota_status = QuotaStatus() - if resolved_quota and not isinstance(resolved_quota, Exception): - tier = resolved_quota.tier - usage_pct = 0.0 - remaining = None - - if tier and tier.monthly_cost_limit and tier.monthly_cost_limit != float('inf'): - usage_pct = (cost_summary.total_cost / tier.monthly_cost_limit) * 100 - remaining = max(0, tier.monthly_cost_limit - cost_summary.total_cost) - - quota_status = QuotaStatus( - tier_id=tier.tier_id if tier else None, - tier_name=tier.tier_name if tier else None, - matched_by=resolved_quota.matched_by, - monthly_limit=tier.monthly_cost_limit if tier else None, - current_usage=cost_summary.total_cost, - usage_percentage=round(usage_pct, 1), - remaining=remaining, - has_active_override=resolved_quota.override is not None, - override_reason=resolved_quota.override.reason if resolved_quota.override else None - ) - - # Build event summaries - event_summaries = [] - if recent_events and not isinstance(recent_events, Exception): - for event in recent_events: - event_summaries.append(QuotaEventSummary( - event_id=event.event_id, - event_type=event.event_type, - timestamp=event.timestamp, - percentage_used=event.percentage_used - )) - - return UserDetailResponse( - profile=profile, - cost_summary=cost_summary, - quota_status=quota_status, - recent_events=event_summaries - ) - - async def list_domains(self, limit: int = 50) -> List[str]: - """ - List distinct email domains. - Note: This requires a scan or maintaining a separate domain list. - For now, return empty - implement if needed. - """ - # TODO: Implement domain listing - # Options: - # 1. Maintain a separate DOMAINS item updated on user create - # 2. Scan with projection (not recommended at scale) - # 3. Use application-level aggregation - return [] - - def _get_primary_model(self, cost_data) -> Optional[str]: - """Get the most-used model from cost data""" - if not cost_data or not cost_data.models: - return None - - # Find model with most requests - primary = max(cost_data.models, key=lambda m: m.request_count) - return primary.model_name if primary else None -``` - ---- - -## Frontend Implementation - -### Directory Structure - -``` -frontend/ai.client/src/app/admin/ -├── users/ -│ ├── models/ -│ │ └── user.models.ts -│ ├── services/ -│ │ ├── user-http.service.ts -│ │ └── user-state.service.ts -│ └── pages/ -│ ├── user-list/ -│ │ └── user-list.page.ts -│ └── user-detail/ -│ └── user-detail.page.ts -└── admin.page.ts # Add user lookup card -``` - -### TypeScript Models - -**File:** `frontend/ai.client/src/app/admin/users/models/user.models.ts` - -```typescript -export interface UserListItem { - userId: string; - email: string; - name: string; - status: 'active' | 'inactive' | 'suspended'; - lastLoginAt: string; - emailDomain?: string; - currentMonthCost?: number; - quotaUsagePercentage?: number; -} - -export interface UserListResponse { - users: UserListItem[]; - nextCursor?: string; - totalCount?: number; -} - -export interface QuotaStatus { - tierId?: string; - tierName?: string; - matchedBy?: string; - monthlyLimit?: number; - currentUsage: number; - usagePercentage: number; - remaining?: number; - hasActiveOverride: boolean; - overrideReason?: string; -} - -export interface CostSummary { - totalCost: number; - totalRequests: number; - totalInputTokens: number; - totalOutputTokens: number; - cacheSavings: number; - primaryModel?: string; -} - -export interface QuotaEventSummary { - eventId: string; - eventType: 'warning' | 'block' | 'reset' | 'override_applied'; - timestamp: string; - percentageUsed: number; -} - -export interface UserProfile { - userId: string; - email: string; - name: string; - roles: string[]; - picture?: string; - emailDomain: string; - createdAt: string; - lastLoginAt: string; - status: 'active' | 'inactive' | 'suspended'; -} - -export interface UserDetailResponse { - profile: UserProfile; - costSummary: CostSummary; - quotaStatus: QuotaStatus; - recentEvents: QuotaEventSummary[]; -} -``` - -### HTTP Service - -**File:** `frontend/ai.client/src/app/admin/users/services/user-http.service.ts` - -```typescript -import { Injectable, inject } from '@angular/core'; -import { HttpClient, HttpParams } from '@angular/common/http'; -import { Observable } from 'rxjs'; -import { environment } from '../../../../environments/environment'; -import { UserListResponse, UserDetailResponse } from '../models/user.models'; - -@Injectable({ - providedIn: 'root', -}) -export class UserHttpService { - private http = inject(HttpClient); - private baseUrl = `${environment.apiUrl}/api/admin/users`; - - listUsers( - status: string = 'active', - domain?: string, - limit: number = 25, - cursor?: string - ): Observable { - let params = new HttpParams() - .set('status', status) - .set('limit', limit.toString()); - - if (domain) { - params = params.set('domain', domain); - } - if (cursor) { - params = params.set('cursor', cursor); - } - - return this.http.get(this.baseUrl, { params }); - } - - searchByEmail(email: string): Observable { - const params = new HttpParams().set('email', email); - return this.http.get(`${this.baseUrl}/search`, { params }); - } - - getUserDetail(userId: string): Observable { - return this.http.get(`${this.baseUrl}/${userId}`); - } - - listDomains(limit: number = 50): Observable { - const params = new HttpParams().set('limit', limit.toString()); - return this.http.get(`${this.baseUrl}/domains/list`, { params }); - } -} -``` - -### State Service - -**File:** `frontend/ai.client/src/app/admin/users/services/user-state.service.ts` - -```typescript -import { Injectable, inject, signal, computed } from '@angular/core'; -import { UserHttpService } from './user-http.service'; -import { - UserListItem, - UserDetailResponse, -} from '../models/user.models'; - -@Injectable({ - providedIn: 'root', -}) -export class UserStateService { - private http = inject(UserHttpService); - - // State - users = signal([]); - selectedUser = signal(null); - loading = signal(false); - searchQuery = signal(''); - statusFilter = signal<'active' | 'inactive' | 'suspended'>('active'); - domainFilter = signal(null); - nextCursor = signal(null); - - // Computed - hasMore = computed(() => this.nextCursor() !== null); - userCount = computed(() => this.users().length); - - loadUsers(reset: boolean = false): void { - if (reset) { - this.users.set([]); - this.nextCursor.set(null); - } - - this.loading.set(true); - - this.http - .listUsers( - this.statusFilter(), - this.domainFilter() ?? undefined, - 25, - reset ? undefined : this.nextCursor() ?? undefined - ) - .subscribe({ - next: (response) => { - if (reset) { - this.users.set(response.users); - } else { - this.users.update((current) => [...current, ...response.users]); - } - this.nextCursor.set(response.nextCursor ?? null); - this.loading.set(false); - }, - error: () => this.loading.set(false), - }); - } - - searchByEmail(email: string): void { - this.loading.set(true); - this.searchQuery.set(email); - - this.http.searchByEmail(email).subscribe({ - next: (response) => { - this.users.set(response.users); - this.nextCursor.set(null); - this.loading.set(false); - }, - error: () => this.loading.set(false), - }); - } - - loadUserDetail(userId: string): void { - this.loading.set(true); - this.selectedUser.set(null); - - this.http.getUserDetail(userId).subscribe({ - next: (detail) => { - this.selectedUser.set(detail); - this.loading.set(false); - }, - error: () => this.loading.set(false), - }); - } - - clearSelection(): void { - this.selectedUser.set(null); - } - - setStatusFilter(status: 'active' | 'inactive' | 'suspended'): void { - this.statusFilter.set(status); - this.loadUsers(true); - } - - setDomainFilter(domain: string | null): void { - this.domainFilter.set(domain); - this.loadUsers(true); - } -} -``` - -### User List Page - -**File:** `frontend/ai.client/src/app/admin/users/pages/user-list/user-list.page.ts` - -```typescript -import { - Component, - ChangeDetectionStrategy, - inject, - OnInit, - signal, -} from '@angular/core'; -import { Router } from '@angular/router'; -import { FormsModule } from '@angular/forms'; -import { NgIcon, provideIcons } from '@ng-icons/core'; -import { - heroMagnifyingGlass, - heroUser, - heroChevronRight, -} from '@ng-icons/heroicons/outline'; -import { UserStateService } from '../../services/user-state.service'; -import { UserListItem } from '../../models/user.models'; - -@Component({ - selector: 'app-user-list', - changeDetection: ChangeDetectionStrategy.OnPush, - imports: [FormsModule, NgIcon], - providers: [ - provideIcons({ heroMagnifyingGlass, heroUser, heroChevronRight }), - ], - host: { - class: 'block p-6', - }, - template: ` -
-

User Lookup

-

- Search and browse users to view their profile, costs, and quota status. -

-
- - -
-
- - -
-
- - -
- -
- - - @if (state.loading() && state.users().length === 0) { -
Loading users...
- } - - -
- @for (user of state.users(); track user.userId) { -
- -
- -
- - -
-
- {{ user.email }} - @if (user.status !== 'active') { - - {{ user.status }} - - } -
-
- {{ user.name || 'No name' }} · Last login: - {{ formatDate(user.lastLoginAt) }} -
-
- - - @if (user.quotaUsagePercentage !== undefined) { -
-
- {{ user.quotaUsagePercentage }}% quota used -
- @if (user.currentMonthCost !== undefined) { -
- \${{ user.currentMonthCost.toFixed(2) }} this month -
- } -
- } - - -
- } -
- - - @if (state.users().length === 0 && !state.loading()) { -
- -

No users found

-

Try adjusting your search or filters

-
- } - - - @if (state.hasMore()) { -
- -
- } - `, -}) -export class UserListPage implements OnInit { - state = inject(UserStateService); - private router = inject(Router); - - searchEmail = ''; - - ngOnInit(): void { - this.state.loadUsers(true); - } - - search(): void { - if (this.searchEmail.trim()) { - this.state.searchByEmail(this.searchEmail.trim()); - } else { - this.state.loadUsers(true); - } - } - - viewUser(user: UserListItem): void { - this.router.navigate(['/admin/users', user.userId]); - } - - loadMore(): void { - this.state.loadUsers(false); - } - - formatDate(isoString: string): string { - const date = new Date(isoString); - const now = new Date(); - const diffMs = now.getTime() - date.getTime(); - const diffDays = Math.floor(diffMs / (1000 * 60 * 60 * 24)); - - if (diffDays === 0) { - return 'Today'; - } else if (diffDays === 1) { - return 'Yesterday'; - } else if (diffDays < 7) { - return `${diffDays} days ago`; - } else { - return date.toLocaleDateString(); - } - } -} -``` - -### User Detail Page - -**File:** `frontend/ai.client/src/app/admin/users/pages/user-detail/user-detail.page.ts` - -```typescript -import { - Component, - ChangeDetectionStrategy, - inject, - OnInit, - computed, -} from '@angular/core'; -import { ActivatedRoute, Router } from '@angular/router'; -import { NgIcon, provideIcons } from '@ng-icons/core'; -import { - heroArrowLeft, - heroUser, - heroCurrencyDollar, - heroChartBar, - heroShieldCheck, - heroExclamationTriangle, - heroClock, -} from '@ng-icons/heroicons/outline'; -import { UserStateService } from '../../services/user-state.service'; - -@Component({ - selector: 'app-user-detail', - changeDetection: ChangeDetectionStrategy.OnPush, - imports: [NgIcon], - providers: [ - provideIcons({ - heroArrowLeft, - heroUser, - heroCurrencyDollar, - heroChartBar, - heroShieldCheck, - heroExclamationTriangle, - heroClock, - }), - ], - host: { - class: 'block p-6', - }, - template: ` - - - - @if (state.loading()) { -
Loading user details...
- } - - @if (user(); as detail) { - -
- - @if (detail.profile.picture) { - - } @else { -
- -
- } - - -
-

{{ detail.profile.name || 'Unknown User' }}

-

{{ detail.profile.email }}

-
- ID: {{ detail.profile.userId }} - Domain: {{ detail.profile.emailDomain }} -
-
- @for (role of detail.profile.roles; track role) { - - {{ role }} - - } -
-
- - -
- - {{ detail.profile.status }} - -
-
- - -
- -
-
- -

Current Month Cost

-
-
- \${{ detail.costSummary.totalCost.toFixed(2) }} -
-
-
{{ detail.costSummary.totalRequests }} requests
-
- {{ formatTokens(detail.costSummary.totalInputTokens) }} input / - {{ formatTokens(detail.costSummary.totalOutputTokens) }} output tokens -
- @if (detail.costSummary.cacheSavings > 0) { -
- \${{ detail.costSummary.cacheSavings.toFixed(2) }} cache savings -
- } -
-
- - -
-
- -

Quota Status

-
- @if (detail.quotaStatus.tierName) { -
- {{ detail.quotaStatus.tierName }} - - ({{ detail.quotaStatus.matchedBy }}) - -
- -
-
- \${{ detail.quotaStatus.currentUsage.toFixed(2) }} - \${{ detail.quotaStatus.monthlyLimit?.toFixed(2) ?? '∞' }} -
-
-
-
-
- {{ detail.quotaStatus.usagePercentage.toFixed(1) }}% used - @if (detail.quotaStatus.remaining !== undefined) { - · \${{ detail.quotaStatus.remaining.toFixed(2) }} remaining - } -
-
- @if (detail.quotaStatus.hasActiveOverride) { -
- - - Override active: {{ detail.quotaStatus.overrideReason }} - -
- } - } @else { -
No quota assigned
- } -
- - -
-
- -

Activity

-
-
-
- Member since: - {{ formatFullDate(detail.profile.createdAt) }} -
-
- Last login: - {{ formatFullDate(detail.profile.lastLoginAt) }} -
- @if (detail.costSummary.primaryModel) { -
- Primary model: - {{ detail.costSummary.primaryModel }} -
- } -
-
-
- - -
-
-

Recent Quota Events

- -
- @if (detail.recentEvents.length > 0) { -
- @for (event of detail.recentEvents; track event.eventId) { -
- -
- {{ event.eventType }} - - at {{ event.percentageUsed.toFixed(0) }}% usage - -
- - {{ formatFullDate(event.timestamp) }} - -
- } -
- } @else { -
No recent events
- } -
- - -
- - - -
- } - `, -}) -export class UserDetailPage implements OnInit { - state = inject(UserStateService); - private route = inject(ActivatedRoute); - private router = inject(Router); - - user = computed(() => this.state.selectedUser()); - Math = Math; // Expose Math for template - - ngOnInit(): void { - const userId = this.route.snapshot.paramMap.get('userId'); - if (userId) { - this.state.loadUserDetail(userId); - } - } - - goBack(): void { - this.state.clearSelection(); - this.router.navigate(['/admin/users']); - } - - createOverride(): void { - const userId = this.user()?.profile.userId; - if (userId) { - this.router.navigate(['/admin/quota/overrides/new'], { - queryParams: { userId }, - }); - } - } - - assignTier(): void { - const userId = this.user()?.profile.userId; - if (userId) { - this.router.navigate(['/admin/quota/assignments/new'], { - queryParams: { userId, type: 'direct_user' }, - }); - } - } - - viewCostDetails(): void { - const userId = this.user()?.profile.userId; - if (userId) { - // Navigate to cost dashboard with user filter (if supported) - this.router.navigate(['/admin/costs'], { - queryParams: { userId }, - }); - } - } - - formatTokens(tokens: number): string { - if (tokens >= 1_000_000) { - return `${(tokens / 1_000_000).toFixed(1)}M`; - } else if (tokens >= 1_000) { - return `${(tokens / 1_000).toFixed(1)}K`; - } - return tokens.toString(); - } - - formatFullDate(isoString: string): string { - return new Date(isoString).toLocaleString(); - } -} -``` - ---- - -## User Sync Strategy - -### When to Sync - -User sync from JWT should occur: - -1. **On Login** - When user authenticates and receives new tokens -2. **On Token Refresh** - When refresh token is exchanged for new access token - -### Integration Point - -Modify the existing auth dependency to call sync: - -**File:** `backend/src/apis/shared/auth/dependencies.py` - -```python -from users.sync import UserSyncService -from users.repository import UserRepository - -# Initialize once -user_repo = UserRepository(dynamodb_client, table_name) -user_sync = UserSyncService(user_repo) - - -async def get_current_user( - token: str = Depends(oauth2_scheme) -) -> User: - """Validate JWT and sync user to database""" - # Validate JWT (existing logic) - claims = validate_jwt(token) - - # Sync user to database (fire-and-forget for performance) - try: - asyncio.create_task(user_sync.sync_from_jwt(claims)) - except Exception as e: - logger.warning(f"User sync failed: {e}") - # Don't fail the request if sync fails - - # Return user object - return User( - user_id=claims["sub"], - email=claims["email"], - name=claims.get("name", ""), - roles=claims.get("roles", []), - picture=claims.get("picture") - ) -``` - -### First-Time User Flow - -``` -1. User logs in for first time -2. JWT validated -3. sync_from_jwt() called -4. No existing user found -5. New user created with: - - createdAt = now - - lastLoginAt = now - - status = "active" -6. User record now in DynamoDB -``` - -### Returning User Flow - -``` -1. User logs in -2. JWT validated -3. sync_from_jwt() called -4. Existing user found -5. User updated with: - - lastLoginAt = now - - Other fields synced (name, roles, picture) - - createdAt preserved -6. User record updated -``` - ---- - -## Testing Strategy - -### Backend Unit Tests - -**File:** `backend/tests/users/test_repository.py` - -```python -import pytest -from users.repository import UserRepository -from users.models import UserProfile - -@pytest.mark.asyncio -async def test_create_and_get_user(user_repo): - """Test creating and retrieving a user""" - profile = UserProfile( - user_id="test-123", - email="test@example.com", - name="Test User", - roles=["user"], - email_domain="example.com", - created_at="2025-01-01T00:00:00Z", - last_login_at="2025-01-01T00:00:00Z", - status="active" - ) - - await user_repo.create_user(profile) - retrieved = await user_repo.get_user("test-123") - - assert retrieved is not None - assert retrieved.email == "test@example.com" - assert retrieved.status == "active" - - -@pytest.mark.asyncio -async def test_get_user_by_email_case_insensitive(user_repo): - """Test email lookup is case-insensitive""" - profile = UserProfile( - user_id="test-456", - email="Test.User@Example.COM", - name="Test User", - roles=[], - email_domain="example.com", - created_at="2025-01-01T00:00:00Z", - last_login_at="2025-01-01T00:00:00Z", - status="active" - ) - - await user_repo.create_user(profile) - - # Should find with lowercase - retrieved = await user_repo.get_user_by_email("test.user@example.com") - assert retrieved is not None - assert retrieved.user_id == "test-456" - - -@pytest.mark.asyncio -async def test_list_users_by_domain(user_repo): - """Test listing users by email domain""" - # Create users in different domains - for i, domain in enumerate(["example.com", "example.com", "other.com"]): - profile = UserProfile( - user_id=f"user-{i}", - email=f"user{i}@{domain}", - name=f"User {i}", - roles=[], - email_domain=domain, - created_at="2025-01-01T00:00:00Z", - last_login_at=f"2025-01-0{i+1}T00:00:00Z", - status="active" - ) - await user_repo.create_user(profile) - - users, _ = await user_repo.list_users_by_domain("example.com") - assert len(users) == 2 -``` - -### Frontend Tests - -**File:** `frontend/ai.client/src/app/admin/users/services/user-http.service.spec.ts` - -```typescript -import { TestBed } from '@angular/core/testing'; -import { - HttpClientTestingModule, - HttpTestingController, -} from '@angular/common/http/testing'; -import { UserHttpService } from './user-http.service'; - -describe('UserHttpService', () => { - let service: UserHttpService; - let httpMock: HttpTestingController; - - beforeEach(() => { - TestBed.configureTestingModule({ - imports: [HttpClientTestingModule], - providers: [UserHttpService], - }); - - service = TestBed.inject(UserHttpService); - httpMock = TestBed.inject(HttpTestingController); - }); - - afterEach(() => { - httpMock.verify(); - }); - - it('should list users with status filter', () => { - const mockResponse = { - users: [{ userId: '123', email: 'test@example.com', name: 'Test', status: 'active' }], - nextCursor: null, - }; - - service.listUsers('active').subscribe((response) => { - expect(response.users.length).toBe(1); - expect(response.users[0].userId).toBe('123'); - }); - - const req = httpMock.expectOne((r) => r.url.includes('/api/admin/users')); - expect(req.request.params.get('status')).toBe('active'); - req.flush(mockResponse); - }); - - it('should search by email', () => { - service.searchByEmail('test@example.com').subscribe(); - - const req = httpMock.expectOne((r) => r.url.includes('/search')); - expect(req.request.params.get('email')).toBe('test@example.com'); - req.flush({ users: [], nextCursor: null }); - }); -}); -``` - ---- - -## Deployment Plan - -### 1. Infrastructure (DynamoDB Table) - -#### Option A: AWS CLI (Manual) - -```bash -aws dynamodb create-table \ - --table-name Users \ - --attribute-definitions \ - AttributeName=PK,AttributeType=S \ - AttributeName=SK,AttributeType=S \ - AttributeName=userId,AttributeType=S \ - AttributeName=email,AttributeType=S \ - AttributeName=GSI2PK,AttributeType=S \ - AttributeName=GSI2SK,AttributeType=S \ - AttributeName=GSI3PK,AttributeType=S \ - AttributeName=GSI3SK,AttributeType=S \ - --key-schema \ - AttributeName=PK,KeyType=HASH \ - AttributeName=SK,KeyType=RANGE \ - --global-secondary-indexes \ - '[ - { - "IndexName": "UserIdIndex", - "KeySchema": [{"AttributeName": "userId", "KeyType": "HASH"}], - "Projection": {"ProjectionType": "ALL"} - }, - { - "IndexName": "EmailIndex", - "KeySchema": [{"AttributeName": "email", "KeyType": "HASH"}], - "Projection": {"ProjectionType": "ALL"} - }, - { - "IndexName": "EmailDomainIndex", - "KeySchema": [ - {"AttributeName": "GSI2PK", "KeyType": "HASH"}, - {"AttributeName": "GSI2SK", "KeyType": "RANGE"} - ], - "Projection": { - "ProjectionType": "INCLUDE", - "NonKeyAttributes": ["userId", "email", "name", "status"] - } - }, - { - "IndexName": "StatusLoginIndex", - "KeySchema": [ - {"AttributeName": "GSI3PK", "KeyType": "HASH"}, - {"AttributeName": "GSI3SK", "KeyType": "RANGE"} - ], - "Projection": { - "ProjectionType": "INCLUDE", - "NonKeyAttributes": ["userId", "email", "name", "emailDomain"] - } - } - ]' \ - --billing-mode PAY_PER_REQUEST -``` - -#### Option B: CDK (Recommended) - -**File:** `infrastructure/lib/app-api-stack.ts` - -Add the Users table after the existing Managed Models table section (~line 520): - -```typescript -// ============================================================ -// Users Table (User Admin) -// ============================================================ - -// Users Table - User profiles synced from JWT for admin lookup -const usersTable = new dynamodb.Table(this, 'UsersTable', { - tableName: getResourceName(config, 'users'), - partitionKey: { - name: 'PK', - type: dynamodb.AttributeType.STRING, - }, - sortKey: { - name: 'SK', - type: dynamodb.AttributeType.STRING, - }, - billingMode: dynamodb.BillingMode.PAY_PER_REQUEST, - pointInTimeRecovery: true, - removalPolicy: config.environment === 'prod' - ? cdk.RemovalPolicy.RETAIN - : cdk.RemovalPolicy.DESTROY, - encryption: dynamodb.TableEncryption.AWS_MANAGED, -}); - -// UserIdIndex - O(1) lookup by userId for admin deep links -usersTable.addGlobalSecondaryIndex({ - indexName: 'UserIdIndex', - partitionKey: { - name: 'userId', - type: dynamodb.AttributeType.STRING, - }, - projectionType: dynamodb.ProjectionType.ALL, -}); - -// EmailIndex - O(1) lookup by email -usersTable.addGlobalSecondaryIndex({ - indexName: 'EmailIndex', - partitionKey: { - name: 'email', - type: dynamodb.AttributeType.STRING, - }, - projectionType: dynamodb.ProjectionType.ALL, -}); - -// EmailDomainIndex - Browse users by company/domain -usersTable.addGlobalSecondaryIndex({ - indexName: 'EmailDomainIndex', - partitionKey: { - name: 'GSI2PK', - type: dynamodb.AttributeType.STRING, - }, - sortKey: { - name: 'GSI2SK', - type: dynamodb.AttributeType.STRING, - }, - projectionType: dynamodb.ProjectionType.INCLUDE, - nonKeyAttributes: ['userId', 'email', 'name', 'status'], -}); - -// StatusLoginIndex - Browse users by status, sorted by last login -usersTable.addGlobalSecondaryIndex({ - indexName: 'StatusLoginIndex', - partitionKey: { - name: 'GSI3PK', - type: dynamodb.AttributeType.STRING, - }, - sortKey: { - name: 'GSI3SK', - type: dynamodb.AttributeType.STRING, - }, - projectionType: dynamodb.ProjectionType.INCLUDE, - nonKeyAttributes: ['userId', 'email', 'name', 'emailDomain'], -}); - -// Store users table name in SSM -new ssm.StringParameter(this, 'UsersTableNameParameter', { - parameterName: `/${config.projectPrefix}/users/users-table-name`, - stringValue: usersTable.tableName, - description: 'Users table name for admin user lookup', - tier: ssm.ParameterTier.STANDARD, -}); - -new ssm.StringParameter(this, 'UsersTableArnParameter', { - parameterName: `/${config.projectPrefix}/users/users-table-arn`, - stringValue: usersTable.tableArn, - description: 'Users table ARN', - tier: ssm.ParameterTier.STANDARD, -}); -``` - -**Add to ECS container environment variables** (~line 555-567): - -```typescript -environment: { - // ... existing environment variables ... - DYNAMODB_USERS_TABLE_NAME: usersTable.tableName, -}, -``` - -**Grant permissions to ECS task role** (~line 600): - -```typescript -// Grant permissions for users table -usersTable.grantReadWriteData(taskDefinition.taskRole); -``` - -**Add CloudFormation output** (~line 730): - -```typescript -new cdk.CfnOutput(this, 'UsersTableName', { - value: usersTable.tableName, - description: 'Users table name for admin user lookup', - exportName: `${config.projectPrefix}-UsersTableName`, -}); -``` - -### 2. Environment Configuration - -**File:** `backend/src/.env.example` - -Add after the existing quota table configuration (~line 160): - -```bash -# ============================================================================= -# USER ADMIN CONFIGURATION -# ============================================================================= - -# DynamoDB table for user profiles (OPTIONAL - User Admin) -# Purpose: Store user profiles synced from JWT for admin user lookup -# Local Development: Leave empty to disable user sync (admin user lookup disabled) -# Production: Set to your DynamoDB table name for admin user management -# Schema: PK=USER#, SK=PROFILE -# GSIs: UserIdIndex (deep links), EmailIndex (search), EmailDomainIndex, StatusLoginIndex -# Features: JWT sync on login, admin deep links from cost dashboard -# CDK Deployment: See infrastructure/lib/app-api-stack.ts -# Example: Users-dev -DYNAMODB_USERS_TABLE_NAME= -``` - -### 3. Backend Deployment - -```bash -# Add environment variable -export DYNAMODB_USERS_TABLE_NAME=Users - -# Deploy backend -cd backend -docker build -t backend:user-admin . -docker push backend:user-admin -``` - -### 4. Frontend Deployment - -```bash -cd frontend/ai.client - -# Add routes to admin module -# Build and deploy -npm run build -- --configuration=production -aws s3 sync dist/ai-client s3://your-bucket/ -``` - -### 5. Verification - -```bash -# Test user sync -curl -X POST http://localhost:8000/api/chat \ - -H "Authorization: Bearer $TOKEN" \ - -d '{"message": "hello"}' - -# Verify user was created -aws dynamodb get-item \ - --table-name Users \ - --key '{"PK": {"S": "USER#your-user-id"}, "SK": {"S": "PROFILE"}}' - -# Test admin API -curl http://localhost:8000/api/admin/users \ - -H "Authorization: Bearer $ADMIN_TOKEN" -``` - ---- - -## Validation Criteria - -### Backend - -- [ ] Users table created with correct schema -- [ ] All 4 GSIs created and queryable (UserIdIndex, EmailIndex, EmailDomainIndex, StatusLoginIndex) -- [ ] User sync creates new users on first login -- [ ] User sync updates existing users on subsequent logins -- [ ] `lastLoginAt` updated correctly -- [ ] `createdAt` preserved on updates -- [ ] Email stored and queried as lowercase -- [ ] List by domain returns users sorted by lastLoginAt -- [ ] List by status returns users sorted by lastLoginAt -- [ ] Search by email is case-insensitive -- [ ] User detail aggregates data from multiple tables -- [ ] Admin endpoints require admin role - -### Frontend - -- [ ] User list displays with pagination -- [ ] Search by email works -- [ ] Status filter works -- [ ] Domain filter works (if implemented) -- [ ] User detail shows profile, cost, quota, events -- [ ] Admin actions navigate to correct pages -- [ ] Loading states display correctly -- [ ] Empty states display correctly - -### Integration - -- [ ] End-to-end: Login → User created → Admin can view -- [ ] End-to-end: User with cost → Detail shows correct cost -- [ ] End-to-end: User with quota → Detail shows correct quota -- [ ] End-to-end: Create override from user detail - ---- - -## Future Enhancements - -1. **Full-Text Search** - Integrate OpenSearch for name/email partial matching -2. **User Suspension** - Add suspend/unsuspend functionality -3. **Bulk Operations** - Export users, bulk tier assignment -4. **Usage Analytics** - Trends, graphs, comparisons -5. **Session History** - View user's conversation sessions -6. **Audit Logging** - Track admin actions on users - ---- - -**End of Specification** diff --git a/docs/USER_COST_TRACKING_SPEC.md b/docs/USER_COST_TRACKING_SPEC.md deleted file mode 100644 index 2a3d9f6f..00000000 --- a/docs/USER_COST_TRACKING_SPEC.md +++ /dev/null @@ -1,2193 +0,0 @@ -# User Cost Tracking Specification - -## Executive Summary - -This specification outlines a comprehensive approach to accurately track user inference costs based on model usage, including token caching considerations. The system will capture token usage and pricing data at the point of inference, store it in DynamoDB for production (local files for development), and provide high-performance aggregation capabilities for future quota implementation. - -**Production Target**: Scale to 10,000+ monthly active users with sub-100ms query performance. - -**Note**: This application has not yet been deployed to production, so no migration strategy is required. All cost tracking features will be implemented as part of the initial production deployment. - -## Table of Contents - -1. [Architecture Overview](#architecture-overview) -2. [Current Infrastructure Analysis](#current-infrastructure-analysis) -3. [Data Models](#data-models) -4. [Cost Capture Strategy](#cost-capture-strategy) -5. [Storage Architecture](#storage-architecture) -6. [Token Caching Considerations](#token-caching-considerations) -7. [Cost Calculation](#cost-calculation) -8. [Aggregation & Querying](#aggregation--querying) -9. [Future: Quota Implementation](#future-quota-implementation) -10. [Implementation Plan](#implementation-plan) - ---- - -## Architecture Overview - -### Current Flow - -``` -User Request - ↓ -FastAPI Endpoint (inference_api/chat/routes.py) - ↓ -get_agent() (chat/service.py) - Creates MainAgent with model config - ↓ -StreamCoordinator.stream_response() (streaming/stream_coordinator.py) - ↓ -process_agent_stream() (streaming/stream_processor.py) - Extracts metadata - ↓ -_store_message_metadata() (stream_coordinator.py:146-155) - Stores metadata - ↓ -Storage Layer (DynamoDB in production, local files in development) -``` - -### Key Capture Points - -1. **Model Configuration**: Captured at agent creation (`chat/service.py:99-109`) -2. **Token Usage**: Extracted from stream events (`stream_processor.py:844-1088`) -3. **Pricing Data**: Available from managed models (`admin/models.py:147-168`) -4. **User Attribution**: Available from JWT authentication (`auth/dependencies.py`) - ---- - -## Current Infrastructure Analysis - -### Existing Components ✅ - -#### 1. Token Usage Tracking (Already Implemented) -- **Location**: `backend/src/agents/main_agent/streaming/stream_processor.py:844-1088` -- **Functionality**: Extracts token usage from model metadata events -- **Data Captured**: - - `inputTokens` - Standard input tokens - - `outputTokens` - Standard output tokens - - `totalTokens` - Sum of input + output - - `cacheReadInputTokens` - Tokens read from cache (90% discount) - - `cacheWriteInputTokens` - Tokens written to cache (25% markup) - -#### 2. Model Pricing (Partially Implemented) -- **Location**: `backend/src/apis/app_api/admin/models.py:107-168` -- **Managed Model Data**: - - `input_price_per_million_tokens` - - `output_price_per_million_tokens` - - Model metadata (provider, name, id) - -**Gap**: No cache pricing in managed models (exists in `costs/pricing_config.py` for Bedrock only) - -#### 3. Message Metadata Storage (Already Implemented) -- **Location**: `backend/src/apis/app_api/messages/models.py:74-84` -- **Storage Path**: `sessions/session_{id}/message-metadata.json` -- **Current Structure**: - ```python - { - "latency": { "timeToFirstToken": int, "endToEndLatency": int }, - "token_usage": { "inputTokens": int, "outputTokens": int, ... }, - "model_info": { "modelId": str, "modelName": str, ... }, - "attribution": { "userId": str, "sessionId": str, "timestamp": str } - } - ``` - -**Gap**: Missing `pricing_snapshot` in stored metadata - -#### 4. User Authentication (Already Implemented) -- **Location**: `backend/src/apis/shared/auth/dependencies.py` -- **Provides**: `user_id`, `email`, `roles` from JWT - -### Missing Components ❌ - -1. **Cache Pricing in Managed Models**: Need to add cache pricing fields -2. **Pricing Snapshot**: Need to capture pricing at request time -3. **Cost Calculation**: Need service to calculate cost from usage + pricing -4. **User Cost Aggregation**: Need database/service for aggregating user costs -5. **Multi-Provider Pricing**: OpenAI and Gemini pricing not yet configured - ---- - -## Data Models - -### 1. Enhanced ManagedModel (Update Required) - -**File**: `backend/src/apis/app_api/admin/models.py` - -```python -class ManagedModel(BaseModel): - """Managed model with full details including cache pricing""" - model_config = ConfigDict(populate_by_name=True) - - id: str - model_id: str = Field(..., alias="modelId") - model_name: str = Field(..., alias="modelName") - provider: str - provider_name: str = Field(..., alias="providerName") - - # Token limits - max_input_tokens: int = Field(..., alias="maxInputTokens") - max_output_tokens: int = Field(..., alias="maxOutputTokens") - - # Standard pricing - input_price_per_million_tokens: float = Field(..., alias="inputPricePerMillionTokens") - output_price_per_million_tokens: float = Field(..., alias="outputPricePerMillionTokens") - - # ✨ NEW: Cache pricing (for providers that support it) - cache_write_price_per_million_tokens: Optional[float] = Field( - None, - alias="cacheWritePricePerMillionTokens", - description="Price per million tokens written to cache (Bedrock only, ~25% markup)" - ) - cache_read_price_per_million_tokens: Optional[float] = Field( - None, - alias="cacheReadPricePerMillionTokens", - description="Price per million tokens read from cache (Bedrock only, ~90% discount)" - ) - - # Other fields... - available_to_roles: List[str] = Field(..., alias="availableToRoles") - enabled: bool - is_reasoning_model: bool = Field(..., alias="isReasoningModel") - knowledge_cutoff_date: Optional[str] = Field(None, alias="knowledgeCutoffDate") - created_at: datetime = Field(..., alias="createdAt") - updated_at: datetime = Field(..., alias="updatedAt") -``` - -### 2. Enhanced PricingSnapshot (Update Required) - -**File**: `backend/src/apis/app_api/messages/models.py` - -```python -class PricingSnapshot(BaseModel): - """Pricing rates at time of request for historical accuracy""" - model_config = ConfigDict(populate_by_name=True) - - # Standard pricing - input_price_per_mtok: float = Field(..., alias="inputPricePerMtok") - output_price_per_mtok: float = Field(..., alias="outputPricePerMtok") - - # ✨ NEW: Cache pricing - cache_write_price_per_mtok: Optional[float] = Field( - None, - alias="cacheWritePricePerMtok", - description="Cache write pricing (Bedrock only)" - ) - cache_read_price_per_mtok: Optional[float] = Field( - None, - alias="cacheReadPricePerMtok", - description="Cache read pricing (Bedrock only)" - ) - - currency: str = Field(default="USD") - snapshot_at: str = Field(..., alias="snapshotAt", description="ISO timestamp when pricing was captured") -``` - -### 3. Enhanced MessageMetadata (Update Required) - -**File**: `backend/src/apis/app_api/messages/models.py` - -```python -class MessageMetadata(BaseModel): - """Metadata associated with a single message""" - model_config = ConfigDict(populate_by_name=True, extra='allow') - - latency: Optional[LatencyMetrics] = Field(None) - token_usage: Optional[TokenUsage] = Field(None, alias="tokenUsage") - model_info: Optional[ModelInfo] = Field(None, alias="modelInfo") - attribution: Optional[Attribution] = Field(None) - - # ✨ NEW: Calculated cost (computed from usage + pricing snapshot) - cost: Optional[float] = Field( - None, - description="Total cost in USD for this message (computed from token usage and pricing)" - ) -``` - -### 4. NEW: UserCostSummary (Create) - -**File**: `backend/src/apis/app_api/costs/models.py` (new file) - -```python -from pydantic import BaseModel, Field, ConfigDict -from typing import Optional, Dict, Any -from datetime import datetime - - -class CostBreakdown(BaseModel): - """Detailed cost breakdown by token type""" - model_config = ConfigDict(populate_by_name=True) - - input_cost: float = Field(..., alias="inputCost", description="Cost from input tokens") - output_cost: float = Field(..., alias="outputCost", description="Cost from output tokens") - cache_write_cost: float = Field(0.0, alias="cacheWriteCost", description="Cost from cache writes") - cache_read_cost: float = Field(0.0, alias="cacheReadCost", description="Cost from cache reads") - total_cost: float = Field(..., alias="totalCost", description="Total cost (sum of all)") - - -class ModelCostSummary(BaseModel): - """Cost summary for a specific model""" - model_config = ConfigDict(populate_by_name=True) - - model_id: str = Field(..., alias="modelId") - model_name: str = Field(..., alias="modelName") - provider: str - - # Token usage - total_input_tokens: int = Field(..., alias="totalInputTokens") - total_output_tokens: int = Field(..., alias="totalOutputTokens") - total_cache_read_tokens: int = Field(0, alias="totalCacheReadTokens") - total_cache_write_tokens: int = Field(0, alias="totalCacheWriteTokens") - - # Cost - cost_breakdown: CostBreakdown = Field(..., alias="costBreakdown") - - # Stats - request_count: int = Field(..., alias="requestCount", description="Number of requests using this model") - - -class UserCostSummary(BaseModel): - """Aggregated cost summary for a user""" - model_config = ConfigDict(populate_by_name=True) - - user_id: str = Field(..., alias="userId") - - # Time range - period_start: str = Field(..., alias="periodStart", description="ISO timestamp of period start") - period_end: str = Field(..., alias="periodEnd", description="ISO timestamp of period end") - - # Aggregate costs - total_cost: float = Field(..., alias="totalCost", description="Total cost across all models") - - # Per-model breakdown - models: list[ModelCostSummary] = Field( - default_factory=list, - description="Cost breakdown by model" - ) - - # Overall token usage - total_requests: int = Field(..., alias="totalRequests") - total_input_tokens: int = Field(..., alias="totalInputTokens") - total_output_tokens: int = Field(..., alias="totalOutputTokens") - total_cache_savings: float = Field( - 0.0, - alias="totalCacheSavings", - description="Total cost saved from cache hits" - ) -``` - ---- - -## Cost Capture Strategy - -### Point of Capture: Stream Coordinator - -**Location**: `backend/src/agents/main_agent/streaming/stream_coordinator.py` - -The stream coordinator already stores message metadata after streaming completes. We enhance this to include pricing and cost calculation. - -#### Current Flow (Line 134-155) - -```python -# Store metadata after flush completes -if message_id is not None: - # Always update session metadata - await self._update_session_metadata(...) - - # Store message-level metadata only if we have usage or timing data - if accumulated_metadata.get("usage") or first_token_time: - await self._store_message_metadata( - session_id=session_id, - user_id=user_id, - message_id=message_id, - accumulated_metadata=accumulated_metadata, - stream_start_time=stream_start_time, - stream_end_time=stream_end_time, - first_token_time=first_token_time, - agent=main_agent_wrapper - ) -``` - -#### Enhanced Flow (Proposed) - -```python -# Store metadata after flush completes -if message_id is not None: - # Always update session metadata - await self._update_session_metadata(...) - - # Store message-level metadata with cost calculation - if accumulated_metadata.get("usage") or first_token_time: - # ✨ NEW: Get pricing snapshot at time of request - pricing_snapshot = await self._get_pricing_snapshot( - agent=main_agent_wrapper - ) - - # ✨ NEW: Calculate cost from usage + pricing - cost = self._calculate_message_cost( - usage=accumulated_metadata.get("usage", {}), - pricing=pricing_snapshot - ) - - await self._store_message_metadata( - session_id=session_id, - user_id=user_id, - message_id=message_id, - accumulated_metadata=accumulated_metadata, - stream_start_time=stream_start_time, - stream_end_time=stream_end_time, - first_token_time=first_token_time, - agent=main_agent_wrapper, - pricing_snapshot=pricing_snapshot, # ✨ NEW - cost=cost # ✨ NEW - ) -``` - -### Why This Approach? - -1. **Accuracy**: Captures pricing at exact time of inference -2. **Single Source of Truth**: Reuses existing metadata storage -3. **Historical Accuracy**: Pricing snapshot allows accurate historical cost calculation even after price changes -4. **Minimal Changes**: Builds on existing infrastructure -5. **Performance**: Cost calculated once at write time, not on every read - ---- - -## Storage Architecture - -### Overview - -**Development Environment**: Local file storage (existing implementation) -**Production Environment**: DynamoDB with optimized schema for cost tracking - -### Local Storage (Development Only) - -**Path**: `sessions/session_{id}/message-metadata.json` - -**Structure** (Enhanced with cost tracking): -```json -{ - "0": { - "latency": { "timeToFirstToken": 250, "endToEndLatency": 1500 }, - "tokenUsage": { - "inputTokens": 1000, - "outputTokens": 500, - "totalTokens": 1500, - "cacheReadInputTokens": 200, - "cacheWriteInputTokens": 100 - }, - "modelInfo": { - "modelId": "us.anthropic.claude-sonnet-4-5-20250929-v1:0", - "modelName": "Claude 3.5 Sonnet", - "modelVersion": "v2", - "pricingSnapshot": { - "inputPricePerMtok": 3.0, - "outputPricePerMtok": 15.0, - "cacheWritePricePerMtok": 3.75, - "cacheReadPricePerMtok": 0.30, - "currency": "USD", - "snapshotAt": "2025-01-15T10:30:00Z" - } - }, - "attribution": { - "userId": "user_123", - "sessionId": "abc-def-ghi", - "timestamp": "2025-01-15T10:30:00Z" - }, - "cost": 0.0234 - } -} -``` - -**Purpose**: Fast local development without AWS dependencies - ---- - -### Production Storage (DynamoDB) - -#### Architecture Overview - -**AgentCore Memory** (managed by AWS) handles session and message storage: -- Sessions managed via AgentCore Memory API -- Messages stored in AgentCore Memory -- Accessed via existing endpoints: `GET /sessions`, `GET /sessions/{id}/messages` - -**Our Cost Tracking Tables**: -1. **SessionsMetadata** - Message-level metadata (cost, tokens, latency) -2. **UserCostSummary** - Pre-aggregated costs for fast quota checks - -**Separation of Concerns**: -- AgentCore Memory = Session/message **content** (what was said) -- SessionsMetadata = Message **metadata** (cost, performance) -- UserCostSummary = Aggregated **cost summaries** (billing, quotas) - -**Environment Configuration** (`.env`): -```bash -# Message Metadata Storage (cost tracking per message) -# AgentCore Memory manages sessions/messages, we store additional metadata -DYNAMODB_SESSIONS_METADATA_TABLE_NAME=SessionsMetadata - -# Cost Summary Storage (separate table for aggregation) -DYNAMODB_COST_SUMMARY_TABLE_NAME=UserCostSummary # For quota checks and dashboards -``` - ---- - -#### Table 1: SessionsMetadata - -**Purpose**: Store message-level metadata (cost, tokens, latency) for messages managed by AgentCore Memory - -**Key Concept**: -- Sessions and messages are in AgentCore Memory (AWS managed) -- This table stores **metadata about those messages** (cost tracking) -- Linked via `sessionId` + `messageId` references - -**Schema**: - -```python -{ - # Primary Key - "PK": "USER#alice", # Partition key - "SK": "SESSION#abc123#MSG#00005", # Sort key (session + message reference) - - # References (to AgentCore Memory) - "userId": "alice", - "sessionId": "abc123", # Links to AgentCore Memory session - "messageId": 5, # Links to AgentCore Memory message - "timestamp": "2025-01-15T10:30:45.123Z", - "ttl": 1768118400, # Auto-delete after 365 days (matches AgentCore Memory retention) - - # Cost & Usage - "cost": 0.0234, # Decimal - "inputTokens": 1000, - "outputTokens": 500, - "cacheReadTokens": 200, - "cacheWriteTokens": 100, - "totalTokens": 1500, - - # Model Info - "modelId": "us.anthropic.claude-sonnet-4-5-20250929-v1:0", - "modelName": "Claude 3.5 Sonnet", - "provider": "bedrock", - - # Pricing Snapshot (for historical accuracy) - "pricingSnapshot": { - "inputPricePerMtok": 3.0, - "outputPricePerMtok": 15.0, - "cacheReadPricePerMtok": 0.30, - "cacheWritePricePerMtok": 3.75, - "currency": "USD", - "snapshotAt": "2025-01-15T10:30:45.123Z" - }, - - # Latency - "timeToFirstToken": 250, # milliseconds - "endToEndLatency": 1500, # milliseconds - - # Additional metadata - "organizationId": "org_abc", # Future: multi-tenant - "tags": { # Future: cost allocation - "project": "marketing-bot", - "department": "sales" - } -} -``` - -**Indexes**: - -**Primary Index**: -- `PK` = `USER#` (Partition Key) -- `SK` = `SESSION##MSG#` (Sort Key) - -**GSI 1: UserTimestampIndex** (for time-range queries) -- `GSI1PK` = `USER#` (Partition Key) -- `GSI1SK` = `` (Sort Key) -- **Projection**: ALL -- **Use Cases**: - - Get all message metadata in date range for cost reports - - Generate billing period summaries - - Analytics queries - -**GSI 2: ModelUsageIndex** (for model analytics - optional) -- `GSI2PK` = `MODEL#` (Partition Key) -- `GSI2SK` = `` (Sort Key) -- **Projection**: KEYS_ONLY + cost, tokens -- **Use Cases**: - - Track which models are most used - - Calculate total cost per model across all users - - Pricing optimization analysis - -**Access Patterns**: - -```python -# 1. Get message metadata for a specific message -get_item( - Key={ - "PK": "USER#alice", - "SK": "SESSION#abc123#MSG#00005" - } -) - -# 2. Get all message metadata for a session -query( - KeyConditionExpression="PK = :user AND begins_with(SK, :session_prefix)", - ExpressionAttributeValues={ - ":user": "USER#alice", - ":session_prefix": "SESSION#abc123#MSG#" - } -) - -# 3. Get user message metadata in date range (via GSI1) -query( - IndexName="UserTimestampIndex", - KeyConditionExpression="GSI1PK = :user AND GSI1SK BETWEEN :start AND :end", - ExpressionAttributeValues={ - ":user": "USER#alice", - ":start": "2025-01-01T00:00:00Z", - ":end": "2025-01-31T23:59:59Z" - } -) - -# 4. Write message metadata after streaming completes -put_item( - Item={ - "PK": "USER#alice", - "SK": "SESSION#abc123#MSG#00005", - "userId": "alice", - "sessionId": "abc123", # Reference to AgentCore Memory session - "messageId": 5, # Reference to AgentCore Memory message - "cost": 0.0234, - "inputTokens": 1000, - "outputTokens": 500, - # ... all metadata attributes - } -) - -# 5. Integration with existing endpoints -# Sessions are fetched via: GET /sessions (AgentCore Memory) -# Messages are fetched via: GET /sessions/{session_id}/messages (AgentCore Memory) -# Metadata is enriched from this table using sessionId + messageId as keys -``` - -**Integration with Existing Endpoints**: - -The metadata table complements your existing session/message endpoints: - -| Endpoint | Data Source | Purpose | -|----------|-------------|---------| -| `GET /sessions` | AgentCore Memory | List user sessions | -| `GET /sessions/{id}/metadata` | AgentCore Memory | Get session metadata (title, preferences) | -| `GET /sessions/{id}/messages` | AgentCore Memory | Get message content | -| `GET /costs/summary` | SessionsMetadata + UserCostSummary | Get cost data (NEW) | - -**Enrichment Pattern**: -```python -# Existing: Get messages from AgentCore Memory -messages = await agentcore_memory.get_messages(session_id) - -# New: Enrich with cost metadata -for message in messages: - metadata = await dynamodb.get_item( - Key={ - "PK": f"USER#{user_id}", - "SK": f"SESSION#{session_id}#MSG#{message.id}" - } - ) - message.cost = metadata.get("cost") - message.tokenUsage = metadata.get("tokenUsage") -``` - -**Performance Characteristics**: -- **Write**: Single-digit millisecond latency -- **Read (single item)**: Single-digit millisecond latency -- **Query (time range)**: 10-50ms for typical user (hundreds of messages) -- **Scalability**: Unlimited (auto-scales with partition key distribution) - ---- - -#### Table 2: UserCostSummary - -**Purpose**: Pre-aggregated cost summaries for fast quota checks and dashboards - -**Schema**: - -```python -{ - # Primary Key - "PK": "USER#alice", # Partition key - "SK": "PERIOD#2025-01", # Sort key (YYYY-MM for monthly) - - # Aggregate Costs - "totalCost": 125.50, # Decimal - "totalRequests": 1234, - "totalInputTokens": 5000000, - "totalOutputTokens": 2500000, - "totalCacheReadTokens": 1000000, - "totalCacheWriteTokens": 500000, - - # Cache Savings - "cacheSavings": 15.75, # How much saved by caching - - # Per-Model Breakdown - "modelBreakdown": { - "claude-sonnet-4-5": { - "cost": 85.30, - "requests": 890, - "inputTokens": 3500000, - "outputTokens": 1800000 - }, - "claude-haiku-4-5": { - "cost": 40.20, - "requests": 344, - "inputTokens": 1500000, - "outputTokens": 700000 - } - }, - - # Period Info - "periodStart": "2025-01-01T00:00:00Z", - "periodEnd": "2025-01-31T23:59:59Z", - "lastUpdated": "2025-01-15T10:30:45.123Z", - - # Quota Info (denormalized for fast checks) - "quotaLimit": 200.00, - "quotaRemaining": 74.50, - "quotaPercentUsed": 62.75 -} -``` - -**Indexes**: - -**Primary Index**: -- `PK` = `USER#` (Partition Key) -- `SK` = `PERIOD#` (Sort Key for monthly) or `PERIOD#` (for daily) - -**GSI 1: PeriodIndex** (for admin queries - optional) -- `GSI1PK` = `PERIOD#` (Partition Key) -- `GSI1SK` = `` (Sort Key) -- **Use Cases**: - - Find top spenders in a period - - Generate org-wide cost reports - -**Access Patterns**: - -```python -# 1. Get current month summary (for quota check) -get_item( - Key={ - "PK": "USER#alice", - "SK": "PERIOD#2025-01" - } -) -# Latency: <10ms (single-item read) ✅ - -# 2. Get user's historical costs -query( - KeyConditionExpression="PK = :user AND begins_with(SK, :prefix)", - ExpressionAttributeValues={ - ":user": "USER#alice", - ":prefix": "PERIOD#" - }, - ScanIndexForward=False, # Descending (newest first) - Limit=12 # Last 12 months -) - -# 3. Update summary (atomic increment) -update_item( - Key={"PK": "USER#alice", "SK": "PERIOD#2025-01"}, - UpdateExpression="ADD totalCost :cost, totalRequests :one, totalInputTokens :input, totalOutputTokens :output", - ExpressionAttributeValues={ - ":cost": Decimal("0.0234"), - ":one": 1, - ":input": 1000, - ":output": 500 - } -) -``` - -**Update Strategy**: - -After each request, update the summary table asynchronously: - -```python -async def _update_cost_summary(user_id: str, cost: float, usage: dict, timestamp: str): - """Update pre-aggregated cost summary (async, non-blocking)""" - - # Determine period key - dt = datetime.fromisoformat(timestamp) - period_key = f"PERIOD#{dt.strftime('%Y-%m')}" - - # Atomic increment (DynamoDB handles concurrency) - await dynamodb.update_item( - TableName="UserCostSummary", - Key={ - "PK": f"USER#{user_id}", - "SK": period_key - }, - UpdateExpression=""" - ADD totalCost :cost, - totalRequests :one, - totalInputTokens :input, - totalOutputTokens :output, - totalCacheReadTokens :cacheRead, - totalCacheWriteTokens :cacheWrite - SET lastUpdated = :now - """, - ExpressionAttributeValues={ - ":cost": Decimal(str(cost)), - ":one": 1, - ":input": usage.get("inputTokens", 0), - ":output": usage.get("outputTokens", 0), - ":cacheRead": usage.get("cacheReadInputTokens", 0), - ":cacheWrite": usage.get("cacheWriteInputTokens", 0), - ":now": timestamp - } - ) - - # Also update per-model breakdown (nested update) - # Implementation details omitted for brevity -``` - -**Performance Characteristics**: -- **Quota Check**: <10ms (single `GetItem`) -- **Dashboard Load**: <20ms (query last 12 months) -- **Update**: <10ms (atomic increment, non-blocking) -- **Concurrency**: Handled automatically by DynamoDB - ---- - -### Storage Abstraction Layer - -To support both local files (dev) and DynamoDB (prod), implement a storage interface: - -**File**: `backend/src/apis/app_api/storage/metadata_storage.py` - -```python -from abc import ABC, abstractmethod -from typing import Optional, List, Dict, Any -from datetime import datetime - - -class MetadataStorage(ABC): - """Abstract interface for message metadata storage""" - - @abstractmethod - async def store_message_metadata( - self, - user_id: str, - session_id: str, - message_id: int, - metadata: Dict[str, Any] - ) -> None: - """Store message metadata""" - pass - - @abstractmethod - async def get_user_cost_summary( - self, - user_id: str, - period: str # e.g., "2025-01" - ) -> Optional[Dict[str, Any]]: - """Get pre-aggregated cost summary for quota checks""" - pass - - @abstractmethod - async def get_user_messages_in_range( - self, - user_id: str, - start_date: datetime, - end_date: datetime - ) -> List[Dict[str, Any]]: - """Get all user messages in date range (for detailed reports)""" - pass - - -class LocalFileStorage(MetadataStorage): - """Local file storage for development""" - # Implementation using existing file-based approach - pass - - -class DynamoDBStorage(MetadataStorage): - """DynamoDB storage for production""" - # Implementation using boto3 DynamoDB client - pass - - -# Factory function -def get_metadata_storage() -> MetadataStorage: - """Get appropriate storage based on environment""" - import os - - if os.environ.get("ENVIRONMENT") == "production": - return DynamoDBStorage() - else: - return LocalFileStorage() -``` - -**Benefits**: -- Developers work locally without AWS -- Production uses scalable DynamoDB -- Easy testing (mock the interface) -- Future-proof (can add other backends) - ---- - -## Token Caching Considerations - -### Cache Token Pricing - -**Bedrock Models** (Claude via Bedrock): -- **Cache Write**: ~25% markup over input price -- **Cache Read**: ~90% discount from input price - -**Example** (Claude Sonnet 4.5): -- Input: $3.00 per million tokens -- Output: $15.00 per million tokens -- Cache Write: $3.75 per million tokens (25% markup) -- Cache Read: $0.30 per million tokens (90% discount) - -### Cache Token Detection - -Already implemented in `stream_processor.py:881-923`: - -```python -# Add cache token fields if present -cache_read = usage_obj.get("cacheReadInputTokens") -if cache_read is None: - cache_read = usage_obj.get("cache_read_input_tokens") - -cache_write = usage_obj.get("cacheWriteInputTokens") -if cache_write is None: - cache_write = usage_obj.get("cache_write_input_tokens") - -# Include cache fields if they exist (even if 0) -if cache_read is not None: - usage_data["cacheReadInputTokens"] = cache_read -if cache_write is not None: - usage_data["cacheWriteInputTokens"] = cache_write -``` - -### Cache Cost Impact - -**Without caching**: -``` -Cost = (1000 input tokens × $3.00/M) + (500 output tokens × $15.00/M) - = $0.003 + $0.0075 - = $0.0105 -``` - -**With caching** (200 cache reads, 100 cache writes): -``` -Standard input: 1000 - 200 - 100 = 700 tokens -Cache reads: 200 tokens -Cache writes: 100 tokens - -Cost = (700 × $3.00/M) + (200 × $0.30/M) + (100 × $3.75/M) + (500 × $15.00/M) - = $0.0021 + $0.00006 + $0.000375 + $0.0075 - = $0.010035 -``` - -**Savings**: ~4% in this example, but can be much higher with larger cache hits - ---- - -## Cost Calculation - -### Service Implementation - -**File**: `backend/src/apis/app_api/costs/calculator.py` (new file) - -```python -from typing import Dict, Optional -from .models import CostBreakdown - - -class CostCalculator: - """Calculate costs from token usage and pricing""" - - @staticmethod - def calculate_message_cost( - usage: Dict[str, int], - pricing: Dict[str, float] - ) -> tuple[float, CostBreakdown]: - """ - Calculate cost for a single message - - Args: - usage: Token usage dict with inputTokens, outputTokens, etc. - pricing: Pricing dict with inputPricePerMtok, etc. - - Returns: - Tuple of (total_cost, cost_breakdown) - """ - # Extract token counts (default to 0 if not present) - input_tokens = usage.get("inputTokens", 0) - output_tokens = usage.get("outputTokens", 0) - cache_read_tokens = usage.get("cacheReadInputTokens", 0) - cache_write_tokens = usage.get("cacheWriteInputTokens", 0) - - # Extract pricing (default to 0 if not present) - input_price = pricing.get("inputPricePerMtok", 0.0) - output_price = pricing.get("outputPricePerMtok", 0.0) - cache_read_price = pricing.get("cacheReadPricePerMtok", 0.0) - cache_write_price = pricing.get("cacheWritePricePerMtok", 0.0) - - # Calculate costs (per million tokens) - input_cost = (input_tokens / 1_000_000) * input_price - output_cost = (output_tokens / 1_000_000) * output_price - cache_read_cost = (cache_read_tokens / 1_000_000) * cache_read_price - cache_write_cost = (cache_write_tokens / 1_000_000) * cache_write_price - - total_cost = input_cost + output_cost + cache_read_cost + cache_write_cost - - breakdown = CostBreakdown( - inputCost=input_cost, - outputCost=output_cost, - cacheReadCost=cache_read_cost, - cacheWriteCost=cache_write_cost, - totalCost=total_cost - ) - - return total_cost, breakdown - - @staticmethod - def calculate_cache_savings( - cache_read_tokens: int, - input_price: float, - cache_read_price: float - ) -> float: - """ - Calculate cost savings from cache hits - - Without cache, these tokens would have been charged at input_price. - With cache, they're charged at cache_read_price. - - Args: - cache_read_tokens: Number of tokens read from cache - input_price: Standard input price per million tokens - cache_read_price: Cache read price per million tokens - - Returns: - Cost savings in USD - """ - if cache_read_tokens == 0: - return 0.0 - - standard_cost = (cache_read_tokens / 1_000_000) * input_price - cache_cost = (cache_read_tokens / 1_000_000) * cache_read_price - - return standard_cost - cache_cost -``` - -### Integration Point - -**File**: `backend/src/agents/main_agent/streaming/stream_coordinator.py` - -Add new methods: - -```python -async def _get_pricing_snapshot(self, agent: Any) -> Optional[Dict[str, Any]]: - """ - Get pricing snapshot from agent's model configuration - - Args: - agent: MainAgent wrapper instance - - Returns: - Pricing snapshot dict or None if unavailable - """ - if not agent or not hasattr(agent, 'model_config'): - return None - - model_config = agent.model_config - model_id = model_config.model_id - - # Get managed model pricing - # TODO: Import managed models service - from apis.app_api.admin.services.managed_models import get_model_by_model_id - - managed_model = await get_model_by_model_id(model_id) - if not managed_model: - logger.warning(f"No managed model found for {model_id}") - return None - - # Create pricing snapshot - from datetime import datetime, timezone - - snapshot = { - "inputPricePerMtok": managed_model.input_price_per_million_tokens, - "outputPricePerMtok": managed_model.output_price_per_million_tokens, - "currency": "USD", - "snapshotAt": datetime.now(timezone.utc).isoformat() - } - - # Add cache pricing if available (Bedrock only) - if managed_model.cache_write_price_per_million_tokens is not None: - snapshot["cacheWritePricePerMtok"] = managed_model.cache_write_price_per_million_tokens - if managed_model.cache_read_price_per_million_tokens is not None: - snapshot["cacheReadPricePerMtok"] = managed_model.cache_read_price_per_million_tokens - - return snapshot - - -def _calculate_message_cost( - self, - usage: Dict[str, Any], - pricing: Optional[Dict[str, Any]] -) -> Optional[float]: - """ - Calculate message cost from usage and pricing - - Args: - usage: Token usage dict - pricing: Pricing snapshot dict - - Returns: - Total cost in USD or None if pricing unavailable - """ - if not pricing: - return None - - from apis.app_api.costs.calculator import CostCalculator - - total_cost, _ = CostCalculator.calculate_message_cost(usage, pricing) - return total_cost -``` - ---- - -## Aggregation & Querying - -### Service Implementation - -**File**: `backend/src/apis/app_api/costs/aggregator.py` (new file) - -```python -from datetime import datetime, timezone -from typing import Optional -from decimal import Decimal -import boto3 - -from .models import UserCostSummary, ModelCostSummary, CostBreakdown -from apis.app_api.storage.metadata_storage import get_metadata_storage - - -class CostAggregator: - """Aggregate costs across sessions and time periods""" - - def __init__(self): - self.storage = get_metadata_storage() - - async def get_user_cost_summary( - self, - user_id: str, - period: str # e.g., "2025-01" for monthly - ) -> UserCostSummary: - """ - Get aggregated cost summary for a user (fast path using pre-aggregated data) - - This method queries the UserCostSummary table for O(1) performance. - - Args: - user_id: User identifier - period: Period identifier (YYYY-MM for monthly) - - Returns: - UserCostSummary with pre-aggregated costs - """ - # Get pre-aggregated summary from storage - summary = await self.storage.get_user_cost_summary(user_id, period) - - if not summary: - # No data for this period, return empty summary - return self._create_empty_summary(user_id, period) - - # Convert to UserCostSummary model - return UserCostSummary( - userId=user_id, - periodStart=summary["periodStart"], - periodEnd=summary["periodEnd"], - totalCost=float(summary["totalCost"]), - models=self._build_model_summaries(summary.get("modelBreakdown", {})), - totalRequests=summary["totalRequests"], - totalInputTokens=summary["totalInputTokens"], - totalOutputTokens=summary["totalOutputTokens"], - totalCacheSavings=float(summary.get("cacheSavings", 0.0)) - ) - - async def get_detailed_cost_report( - self, - user_id: str, - start_date: datetime, - end_date: datetime - ) -> UserCostSummary: - """ - Get detailed cost report by querying message-level data - - This method queries the MessageMetadata table for detailed breakdowns. - Use this for custom date ranges or when detailed per-message data is needed. - - Args: - user_id: User identifier - start_date: Start of period - end_date: End of period - - Returns: - UserCostSummary with detailed aggregations - """ - # Query message metadata in date range - messages = await self.storage.get_user_messages_in_range( - user_id, start_date, end_date - ) - - # Aggregate from message-level data - total_cost = 0.0 - total_requests = len(messages) - total_input_tokens = 0 - total_output_tokens = 0 - total_cache_savings = 0.0 - - model_stats = {} - - for message in messages: - # Extract cost and tokens - cost = float(message.get("cost", 0.0)) - total_cost += cost - - input_tokens = message.get("inputTokens", 0) - output_tokens = message.get("outputTokens", 0) - cache_read_tokens = message.get("cacheReadTokens", 0) - cache_write_tokens = message.get("cacheWriteTokens", 0) - - total_input_tokens += input_tokens - total_output_tokens += output_tokens - - # Calculate cache savings - if cache_read_tokens > 0: - pricing = message.get("pricingSnapshot", {}) - standard_cost = (cache_read_tokens / 1_000_000) * pricing.get("inputPricePerMtok", 0) - cache_cost = (cache_read_tokens / 1_000_000) * pricing.get("cacheReadPricePerMtok", 0) - total_cache_savings += (standard_cost - cache_cost) - - # Aggregate per-model - model_id = message.get("modelId", "unknown") - if model_id not in model_stats: - model_stats[model_id] = { - "modelName": message.get("modelName", "Unknown"), - "provider": message.get("provider", "unknown"), - "cost": 0.0, - "requests": 0, - "inputTokens": 0, - "outputTokens": 0, - "cacheReadTokens": 0, - "cacheWriteTokens": 0 - } - - stats = model_stats[model_id] - stats["cost"] += cost - stats["requests"] += 1 - stats["inputTokens"] += input_tokens - stats["outputTokens"] += output_tokens - stats["cacheReadTokens"] += cache_read_tokens - stats["cacheWriteTokens"] += cache_write_tokens - - # Build model summaries - models = [] - for model_id, stats in model_stats.items(): - breakdown = CostBreakdown( - inputCost=0.0, # TODO: Store breakdown in metadata - outputCost=0.0, - cacheReadCost=0.0, - cacheWriteCost=0.0, - totalCost=stats["cost"] - ) - - model_summary = ModelCostSummary( - modelId=model_id, - modelName=stats["modelName"], - provider=stats["provider"], - totalInputTokens=stats["inputTokens"], - totalOutputTokens=stats["outputTokens"], - totalCacheReadTokens=stats["cacheReadTokens"], - totalCacheWriteTokens=stats["cacheWriteTokens"], - costBreakdown=breakdown, - requestCount=stats["requests"] - ) - models.append(model_summary) - - return UserCostSummary( - userId=user_id, - periodStart=start_date.isoformat(), - periodEnd=end_date.isoformat(), - totalCost=total_cost, - models=models, - totalRequests=total_requests, - totalInputTokens=total_input_tokens, - totalOutputTokens=total_output_tokens, - totalCacheSavings=total_cache_savings - ) - - def _build_model_summaries(self, model_breakdown: dict) -> list: - """Build ModelCostSummary objects from breakdown dict""" - models = [] - for model_id, stats in model_breakdown.items(): - breakdown = CostBreakdown( - inputCost=0.0, # Stored in summary if needed - outputCost=0.0, - cacheReadCost=0.0, - cacheWriteCost=0.0, - totalCost=float(stats["cost"]) - ) - - models.append(ModelCostSummary( - modelId=model_id, - modelName=stats.get("modelName", "Unknown"), - provider=stats.get("provider", "unknown"), - totalInputTokens=stats.get("inputTokens", 0), - totalOutputTokens=stats.get("outputTokens", 0), - totalCacheReadTokens=stats.get("cacheReadTokens", 0), - totalCacheWriteTokens=stats.get("cacheWriteTokens", 0), - costBreakdown=breakdown, - requestCount=stats.get("requests", 0) - )) - - return models - - def _create_empty_summary(self, user_id: str, period: str) -> UserCostSummary: - """Create empty summary for period with no data""" - return UserCostSummary( - userId=user_id, - periodStart=f"{period}-01T00:00:00Z", - periodEnd=f"{period}-31T23:59:59Z", - totalCost=0.0, - models=[], - totalRequests=0, - totalInputTokens=0, - totalOutputTokens=0, - totalCacheSavings=0.0 - ) -``` - -### API Endpoints - -**File**: `backend/src/apis/app_api/costs/routes.py` (new file) - -```python -from fastapi import APIRouter, Depends, Query -from datetime import datetime -from typing import Optional - -from apis.shared.auth.dependencies import get_current_user -from apis.shared.auth.models import User -from .models import UserCostSummary -from .aggregator import CostAggregator - -router = APIRouter(prefix="/costs", tags=["costs"]) - - -@router.get("/summary", response_model=UserCostSummary) -async def get_cost_summary( - period: Optional[str] = Query(None, description="Period (YYYY-MM), defaults to current month"), - current_user: User = Depends(get_current_user) -): - """ - Get cost summary for the authenticated user (fast path) - - Uses pre-aggregated UserCostSummary table for <10ms response time. - - Args: - period: Optional period (YYYY-MM), defaults to current month - current_user: Authenticated user from JWT - - Returns: - UserCostSummary with pre-aggregated costs - - Example: - GET /costs/summary?period=2025-01 - """ - # Default to current month - if not period: - period = datetime.utcnow().strftime("%Y-%m") - - # Get pre-aggregated summary (O(1) lookup) - aggregator = CostAggregator() - summary = await aggregator.get_user_cost_summary( - user_id=current_user.user_id, - period=period - ) - - return summary - - -@router.get("/detailed-report", response_model=UserCostSummary) -async def get_detailed_report( - start_date: str = Query(..., description="ISO 8601 start date (YYYY-MM-DD)"), - end_date: str = Query(..., description="ISO 8601 end date (YYYY-MM-DD)"), - current_user: User = Depends(get_current_user) -): - """ - Get detailed cost report for custom date range - - Queries MessageMetadata table for detailed breakdown. - Use this for custom date ranges or when detailed per-message data is needed. - - Args: - start_date: Start date (ISO 8601) - end_date: End date (ISO 8601) - current_user: Authenticated user from JWT - - Returns: - UserCostSummary with detailed aggregations - - Example: - GET /costs/detailed-report?start_date=2025-01-01&end_date=2025-01-15 - """ - # Parse dates - start = datetime.fromisoformat(start_date) - end = datetime.fromisoformat(end_date) - - # Validate date range (max 90 days for performance) - if (end - start).days > 90: - raise HTTPException( - status_code=400, - detail="Date range cannot exceed 90 days" - ) - - # Get detailed report (queries message-level data) - aggregator = CostAggregator() - summary = await aggregator.get_detailed_cost_report( - user_id=current_user.user_id, - start_date=start, - end_date=end - ) - - return summary -``` - ---- - -## Future: Quota Implementation - -### Quota Models - -**File**: `backend/src/apis/app_api/costs/quota_models.py` (future) - -```python -from pydantic import BaseModel, Field, ConfigDict -from typing import Optional, Literal - - -class UserQuota(BaseModel): - """User quota configuration""" - model_config = ConfigDict(populate_by_name=True) - - user_id: str = Field(..., alias="userId") - - # Quota limits - monthly_cost_limit: float = Field(..., alias="monthlyCostLimit", description="Monthly spend limit in USD") - daily_cost_limit: Optional[float] = Field(None, alias="dailyCostLimit", description="Daily spend limit in USD") - - # Quota period - period: Literal["daily", "monthly"] = Field(default="monthly") - - # Actions on limit - action_on_limit: Literal["block", "warn", "notify"] = Field( - default="warn", - alias="actionOnLimit" - ) - - # Current usage - current_period_cost: float = Field(0.0, alias="currentPeriodCost") - period_start: str = Field(..., alias="periodStart") - period_end: str = Field(..., alias="periodEnd") - - -class QuotaCheckResult(BaseModel): - """Result of quota check""" - model_config = ConfigDict(populate_by_name=True) - - allowed: bool = Field(..., description="Whether request is allowed") - current_usage: float = Field(..., alias="currentUsage", description="Current period usage") - limit: float = Field(..., description="Quota limit") - remaining: float = Field(..., description="Remaining quota") - percentage_used: float = Field(..., alias="percentageUsed", description="Percentage of quota used") - message: Optional[str] = Field(None, description="Message to display to user") -``` - -### Pre-Request Quota Check - -```python -async def check_quota_before_request(user_id: str) -> QuotaCheckResult: - """ - Check if user has remaining quota before processing request - - This is a fast check using cached/aggregated data. - """ - # Get user quota config - quota = await get_user_quota(user_id) - - # Get current period usage - aggregator = CostAggregator() - summary = await aggregator.get_user_cost_summary( - user_id=user_id, - start_date=datetime.fromisoformat(quota.period_start), - end_date=datetime.fromisoformat(quota.period_end) - ) - - current_usage = summary.total_cost - limit = quota.monthly_cost_limit - remaining = limit - current_usage - percentage = (current_usage / limit) * 100 if limit > 0 else 0 - - # Determine if allowed - allowed = True - message = None - - if quota.action_on_limit == "block" and current_usage >= limit: - allowed = False - message = f"Monthly quota exceeded. Limit: ${limit:.2f}, Used: ${current_usage:.2f}" - elif quota.action_on_limit == "warn" and percentage >= 80: - message = f"You've used {percentage:.0f}% of your monthly quota (${current_usage:.2f}/${limit:.2f})" - - return QuotaCheckResult( - allowed=allowed, - currentUsage=current_usage, - limit=limit, - remaining=remaining, - percentageUsed=percentage, - message=message - ) -``` - ---- - -## Environment Configuration - -### Backend Configuration (.env) - -Add the following environment variables to `backend/src/.env`: - -```bash -# ============================================================================= -# DATABASE CONFIGURATION -# ============================================================================= - -# DynamoDB table for session metadata (message-level cost tracking) -# AgentCore Memory manages sessions and messages in the cloud -# This table stores additional metadata like cost, tokens, latency per message -# Local development uses file storage if not set -DYNAMODB_SESSIONS_METADATA_TABLE_NAME=SessionsMetadata - -# DynamoDB table for user cost summaries (separate table) -# Stores pre-aggregated costs for fast quota checks and dashboards -# Required for production cost tracking and quota enforcement -DYNAMODB_COST_SUMMARY_TABLE_NAME=UserCostSummary -``` - -**Usage in Code**: -```python -import os - -# Get table names from environment -SESSIONS_METADATA_TABLE = os.environ.get("DYNAMODB_SESSIONS_METADATA_TABLE_NAME", "SessionsMetadata") -COST_SUMMARY_TABLE = os.environ.get("DYNAMODB_COST_SUMMARY_TABLE_NAME", "UserCostSummary") - -# Use in DynamoDB operations -# Note: Sessions and messages are in AgentCore Memory, NOT DynamoDB -dynamodb.Table(SESSIONS_METADATA_TABLE).put_item(...) # Store metadata only -dynamodb.Table(COST_SUMMARY_TABLE).get_item(...) # Get cost summary -``` - -**Local Development**: -- If `DYNAMODB_SESSIONS_METADATA_TABLE_NAME` is not set → Use local file storage for metadata -- If `DYNAMODB_COST_SUMMARY_TABLE_NAME` is not set → Cost tracking disabled (dev mode) -- Sessions/messages use local AgentCore Memory storage - -**Production**: -- Both environment variables MUST be set -- AgentCore Memory handles sessions/messages (AWS managed) -- Our tables handle metadata and cost summaries -- Tables must be created via Infrastructure as Code (CloudFormation/CDK) - ---- - -## Implementation Plan - -### Phase 1: Data Model Updates & DynamoDB Setup (Week 1-2) - -**Priority: HIGH** - -1. **Update Data Models** - - Add `cache_write_price_per_million_tokens` to ManagedModel - - Add `cache_read_price_per_million_tokens` to ManagedModel - - Update `PricingSnapshot` model with cache pricing fields - - Add `cost` field to MessageMetadata - - Update admin UI to accept/display cache pricing - -2. **Create DynamoDB Tables** (Infrastructure) - - Create `SessionsMetadata` table (message-level cost/token/latency data) - - Primary key: PK (partition), SK (sort) - - GSI 1: UserTimestampIndex (for time-range queries) - - GSI 2: ModelUsageIndex (optional, for analytics) - - TTL enabled on `ttl` attribute (365-day retention, matches AgentCore Memory) - - Links to AgentCore Memory sessions via `sessionId` + `messageId` - - Create `UserCostSummary` table (separate table for cost aggregation) - - Primary key: PK (partition), SK (sort) - - GSI 1: PeriodIndex (optional, for admin queries) - - Set up IAM permissions for Lambda/ECS (read/write to tables) - - Set up IAM permissions for AgentCore Memory (already configured) - - Configure table capacity (on-demand recommended) - - Add environment variables to deployment configuration - -3. **Create Storage Abstraction Layer** - - Implement `MetadataStorage` interface - - Implement `LocalFileStorage` (development) - - Implement `DynamoDBStorage` (production) - - Add environment-based factory pattern - -**Files to Create**: -- `backend/src/apis/app_api/storage/metadata_storage.py` -- `backend/src/apis/app_api/storage/dynamodb_storage.py` -- Infrastructure: CloudFormation/CDK for DynamoDB tables - -**Files to Modify**: -- `backend/src/apis/app_api/admin/models.py` -- `backend/src/apis/app_api/messages/models.py` - -**Tests**: -- Pydantic model validation tests -- Storage abstraction interface tests -- Mock DynamoDB operations - ---- - -### Phase 2: Cost Calculation & Capture (Week 3) - -**Priority: HIGH** - -1. **Create Cost Calculator Service** - - Implement `calculate_message_cost()` - - Implement `calculate_cache_savings()` - - Handle multi-provider pricing (Bedrock, OpenAI, Gemini) - - Add comprehensive unit tests - -2. **Create Pricing Service** - - Implement `get_model_pricing()` with LRU cache - - Implement `create_pricing_snapshot()` - - Query managed models efficiently - -3. **Integrate into Stream Coordinator** - - Add `_get_pricing_snapshot()` method - - Add `_calculate_message_cost()` method - - Update `_store_message_metadata()` to: - - Calculate cost from usage + pricing - - Store to MessageMetadata table (DynamoDB/local files) - - Update UserCostSummary table (async, atomic increment) - - Test with real streaming requests - -**Files to Create**: -- `backend/src/apis/app_api/costs/calculator.py` -- `backend/src/apis/app_api/costs/pricing_service.py` - -**Files to Modify**: -- `backend/src/agents/main_agent/streaming/stream_coordinator.py` - -**Tests**: -- Cost calculation unit tests (various token combinations) -- Cache savings calculation tests -- Integration tests with mocked DynamoDB -- End-to-end streaming tests - ---- - -### Phase 3: Aggregation & API Endpoints (Week 4) - -**Priority: HIGH** - -1. **Create Cost Aggregator Service** - - Implement `get_user_cost_summary()` (fast path via UserCostSummary table) - - Implement `get_detailed_cost_report()` (query MessageMetadata table) - - Handle date range filtering with GSI - - Calculate cache savings - -2. **Create Cost API Endpoints** - - `GET /costs/summary?period=YYYY-MM` - Fast pre-aggregated summary - - `GET /costs/detailed-report?start_date&end_date` - Custom date ranges - - Add authentication/authorization - - Add request validation (max date range) - -3. **Frontend Cost Dashboard** - - Create cost summary component - - Display total costs, per-model breakdown - - Show cache savings visualization - - Add period selector (current month, last 30 days, etc.) - - Real-time cost updates - -**Files to Create**: -- `backend/src/apis/app_api/costs/aggregator.py` -- `backend/src/apis/app_api/costs/routes.py` -- `backend/src/apis/app_api/costs/models.py` -- `frontend/ai.client/src/app/costs/` (new feature module) - -**Tests**: -- Aggregation logic tests -- API endpoint integration tests -- Frontend component tests - ---- - -### Phase 4: Multi-Provider Pricing & Frontend Forms (Week 5) - -**Priority: MEDIUM** - -1. **Add OpenAI Pricing** - - Research current OpenAI pricing (GPT-4, GPT-3.5, etc.) - - Add to managed models database - - Update calculator to handle OpenAI-specific pricing - - No cache pricing for OpenAI (standard input/output only) - -2. **Add Gemini Pricing** - - Research current Gemini pricing - - Add to managed models database - - Update calculator to handle Gemini-specific pricing - -3. **Update Admin Model Form (Frontend)** - - **Location**: `frontend/ai.client/src/app/admin/manage-models/new/` - - **Requirements**: - - Add cache pricing fields: `cacheReadPricePerMillionTokens`, `cacheWritePricePerMillionTokens` - - **Show cache fields ONLY when `provider === 'bedrock'`** - - Hide cache fields for OpenAI and Gemini providers - - Validate cache pricing fields (must be positive numbers) - - Update form submission to include cache pricing in API request - - **Form Structure**: - ```typescript - interface ModelFormData { - modelId: string; - modelName: string; - provider: 'bedrock' | 'openai' | 'gemini'; - inputPricePerMillionTokens: number; - outputPricePerMillionTokens: number; - - // Cache pricing (Bedrock only) - cacheReadPricePerMillionTokens?: number; // Show if provider === 'bedrock' - cacheWritePricePerMillionTokens?: number; // Show if provider === 'bedrock' - - // Other fields... - } - ``` - - **UI Implementation**: - ```angular - - - - - - - - - @if (form.value.provider === 'bedrock') { -
-

Cache Pricing (Optional)

-

Bedrock supports prompt caching for reduced costs on repeated content.

- - - - -
- } - ``` - -4. **Pricing Management UI** - - Admin UI to update pricing - - Show pricing history/changelog - - Bulk import pricing from CSV/JSON - -**Files to Create**: -- `frontend/ai.client/src/app/admin/manage-models/new/model-form.component.ts` (update) -- `frontend/ai.client/src/app/admin/manage-models/new/model-form.component.html` (update) - -**Files to Modify**: -- `backend/src/apis/app_api/admin/services/managed_models.py` -- `backend/src/apis/app_api/admin/models.py` (ManagedModel with cache pricing) -- Admin UI components -- Cost calculator (multi-provider support) - -**Tests**: -- Multi-provider cost calculation tests -- Admin pricing update tests -- Frontend form validation tests (cache pricing shown/hidden based on provider) - ---- - -### Phase 5: Quota System (Week 6-7 - Optional) - -**Priority: LOW (Future Enhancement)** - -1. **Create Quota Infrastructure** - - `UserQuota` model (DynamoDB table) - - `QuotaCheckResult` model - - Quota configuration per user/org - -2. **Implement Quota Service** - - `check_quota_before_request()` (<50ms, reads UserCostSummary) - - `update_quota_usage()` (handled by existing summary updates) - - Quota reset logic (monthly/daily) - - Notification triggers (80%, 90%, 100%) - -3. **Integrate Quota Checks** - - Add quota check before streaming starts - - Block/warn based on quota config - - Return quota status in API responses - -4. **Admin Quota Management** - - Set user/org quotas - - View quota usage dashboard - - Generate quota reports - - Override quotas for specific users - -**Files to Create**: -- `backend/src/apis/app_api/costs/quota_models.py` -- `backend/src/apis/app_api/costs/quota_service.py` -- `backend/src/apis/shared/middleware/quota_middleware.py` -- DynamoDB table for UserQuota - -**Tests**: -- Quota check performance tests (<50ms target) -- Middleware integration tests -- Admin UI tests - ---- - -## Performance Characteristics - -### Production (DynamoDB) - -**Write Performance** (per request): -- Calculate cost: <1ms (pure math) -- Write to MessageMetadata: 5-10ms (single `PutItem`) -- Update UserCostSummary: 5-10ms (atomic `UpdateItem`, async) -- **Total overhead**: ~10-20ms (async, non-blocking for user) - -**Read Performance** (quota checks, dashboards): -- Quota check (UserCostSummary `GetItem`): <10ms ✅ -- Monthly summary (UserCostSummary `GetItem`): <10ms ✅ -- Historical costs (12 months via `Query`): <20ms ✅ -- Detailed report (custom date range via GSI): 20-100ms (depends on data volume) - -**Scalability**: -- **10,000 users**: Excellent (each user = separate partition key) -- **100,000 users**: Excellent (DynamoDB auto-scales) -- **1,000,000 users**: Excellent (partition key distribution ensures no hot keys) -- **Concurrent writes**: Unlimited (DynamoDB handles automatically) - -### Development (Local Files) - -**Write Performance**: -- Calculate cost: <1ms -- File write: 5-50ms (depends on session size) -- **Total**: Acceptable for development - -**Read Performance**: -- Monthly summary: 10-100ms (file I/O) -- Detailed report: 100-500ms (multiple file reads) -- **Total**: Acceptable for development, not production - -**Scalability**: -- Good for < 100 sessions -- Degrades with large session files -- **Production deployment must use DynamoDB** - ---- - -## Security & Privacy - -### Data Access Control - -- **User Data**: Users can only access their own cost data -- **Admin Data**: Admins can view all user costs (RBAC) -- **Authentication**: JWT-based authentication required - -### Pricing Data - -- **Visibility**: Pricing data is admin-only by default -- **Transparency**: Users can see their per-request costs -- **Historical Accuracy**: Pricing snapshots prevent retroactive cost changes - -### PII Considerations - -- Cost data includes `user_id` but not email/name -- Session titles may contain PII - ensure proper access control -- Cost reports should not expose message content - ---- - -## Monitoring & Alerting - -### Metrics to Track - -1. **Cost Metrics**: - - Total cost per user (daily, monthly) - - Cost per model/provider - - Cache hit rate and savings - - Average cost per request - -2. **Usage Metrics**: - - Total tokens processed - - Requests per user - - Most expensive sessions - -3. **System Metrics**: - - Cost calculation latency - - Aggregation query time - - Storage size growth - -### Alerts - -1. **User Alerts**: - - 80% quota threshold reached - - Daily spend anomaly detected - - Monthly quota exceeded - -2. **Admin Alerts**: - - Overall spend spike - - Missing pricing for new model - - Cost calculation failures - ---- - -## Testing Strategy - -### Unit Tests - -- Cost calculation with various token combinations -- Cache savings calculations -- Pricing snapshot creation -- Aggregation logic - -### Integration Tests - -- End-to-end streaming with cost capture -- Cost aggregation across multiple sessions -- Multi-provider cost calculations -- Quota enforcement - -### Load Tests - -- Cost calculation performance (1000 messages) -- Aggregation performance (100 sessions) -- Concurrent quota checks - -### Manual Testing Scenarios - -1. **Single Request**: Verify cost matches manual calculation -2. **With Caching**: Verify cache tokens reduce cost -3. **Multiple Models**: Switch models mid-session, verify per-model costs -4. **Date Ranges**: Filter costs by various date ranges -5. **Quota Limits**: Test block/warn behaviors - ---- - -## Documentation - -### Developer Documentation - -- Architecture overview (this spec) -- API endpoint documentation -- Cost calculation examples -- Database schema - -### User Documentation - -- How costs are calculated -- Understanding cache savings -- Quota system explanation -- Cost dashboard user guide - -### Admin Documentation - -- Setting up pricing -- Managing user quotas -- Generating cost reports -- Pricing update procedures - ---- - -## Open Questions & Decisions - -### 1. Pricing for New Models - -**Question**: How do we handle new models before pricing is configured? - -**Options**: -- A) Block requests until pricing is added -- B) Allow requests, store tokens, calculate cost later -- C) Use default/estimated pricing with warning - -**Recommendation**: Option B - Store usage, calculate when pricing available - ---- - -### 2. Free Tier / Credits - -**Question**: Should we support free credits or promotional quotas? - -**Options**: -- A) Add `credits` field to user quota -- B) Negative costs for promotional periods -- C) Separate credit tracking system - -**Recommendation**: Phase 6 feature, design separately - ---- - -### 3. Cost Rounding - -**Question**: How many decimal places for cost values? - -**Options**: -- A) Store full precision (float) -- B) Round to cents ($0.01) -- C) Round to 4 decimals ($0.0001) - -**Recommendation**: Store full precision, display 4 decimals, round on billing - ---- - -### 4. Aggregation Frequency - -**Question**: How often to pre-aggregate costs? - -**Options**: -- A) Real-time (calculate on demand) -- B) Hourly (background job) -- C) Daily (midnight UTC) - -**Recommendation**: Phase 1 - real-time, Phase 5 - daily pre-aggregation - ---- - -## Success Metrics - -### Phase 1-2 (Cost Capture) - -- ✅ 100% of streaming requests capture pricing snapshot -- ✅ 100% of messages have calculated cost -- ✅ Cache token costs correctly calculated -- ✅ < 50ms overhead for cost calculation - -### Phase 3 (Aggregation) - -- ✅ Cost summary API responds in < 1s for typical user -- ✅ Per-model breakdown matches sum of message costs -- ✅ Cache savings accurately calculated - -### Phase 5 (Quotas) - -- ✅ Quota checks complete in < 100ms -- ✅ Users blocked at quota limit (if configured) -- ✅ Notifications sent at 80% threshold - ---- - -## DynamoDB Best Practices & Cost Optimization - -### Table Capacity Planning - -**Recommended: On-Demand Mode** -- Auto-scales with traffic -- No capacity planning required -- Pay per request -- Ideal for variable workloads - -**Cost Estimate** (10,000 monthly active users): -``` -Assumptions: -- 10,000 users × 100 requests/month = 1M requests/month -- Average 2 writes per request (MessageMetadata + UserCostSummary) -- Average 10 reads per user/month (dashboards, quota checks) - -Writes: 2M writes × $1.25/M = $2.50/month -Reads: 100K reads × $0.25/M = $0.025/month -Storage: 10GB × $0.25/GB = $2.50/month - -Total: ~$5/month for 10K users ✅ -``` - -### Data Retention Strategy - -**Recommended: TTL for MessageMetadata** -```python -# Set TTL to auto-delete after 365 days (matches AgentCore Memory retention) -"ttl": int((datetime.utcnow() + timedelta(days=365)).timestamp()) -``` - -**Benefits**: -- Reduces storage costs -- Aligns with AgentCore Memory retention policy (365 days) -- Maintains compliance (GDPR right to deletion) -- Keeps recent data for detailed reports -- UserCostSummary persists indefinitely (small footprint) - -### Partition Key Distribution - -**Key Design**: `USER#` - -**Why This Works**: -- Each user = separate partition -- No hot partitions (even distribution) -- Scales linearly with users -- 10K users = 10K partitions ✅ - -**Avoid**: -- ❌ `PERIOD#2025-01` as PK (hot partition, all users in one key) -- ❌ `MODEL#claude` as PK (hot partition for popular models) - -### GSI Optimization - -**UserTimestampIndex**: -- Projection: ALL (for flexibility) -- Used infrequently (detailed reports only) -- Most queries use primary index - -**Alternative** (if GSI costs become significant): -- Projection: KEYS_ONLY + cost, tokens -- Reduces GSI storage by ~70% -- Requires additional `GetItem` calls for full data - -### Monitoring & Alarms - -**CloudWatch Metrics**: -``` -1. ConsumedReadCapacityUnits (should be low with on-demand) -2. ConsumedWriteCapacityUnits (should be low with on-demand) -3. UserErrors (should be 0) -4. SystemErrors (should be 0) -5. ConditionalCheckFailedRequests (atomic increments may retry) -``` - -**Alarms**: -- UserErrors > 10/minute → Investigate permissions/throttling -- Average latency > 100ms → Check GSI performance -- Storage > 100GB → Review TTL configuration - ---- - -## Conclusion - -This specification provides a production-ready, scalable approach to user cost tracking for 10,000+ users: - -### Key Strengths - -1. **Accurate Cost Tracking** - - Captures pricing at inference time (historical accuracy) - - Handles token caching with proper discount calculations - - Multi-provider support (Bedrock, OpenAI, Gemini) - -2. **High Performance** - - <10ms quota checks (critical for user experience) - - <20ms monthly dashboard loads - - ~10-20ms write overhead (async, non-blocking) - - Scales to 1M+ users without degradation - -3. **Production-Ready Architecture** - - AgentCore Memory for session/message storage (AWS managed) - - SessionsMetadata table for cost/token/latency tracking - - UserCostSummary table for pre-aggregated costs - - Storage abstraction for local development - - Atomic updates for concurrent requests - - Environment-based configuration via `.env` - -4. **Cost Efficient** - - ~$5/month for 10K users - - TTL-based data retention - - On-demand capacity (no over-provisioning) - - Minimal read/write operations - -5. **Future-Proof** - - Foundation for quota enforcement - - Supports multi-tenant organizations - - Cost allocation tags - - Detailed audit trail - -### Implementation Timeline - -- **Week 1-2**: Data models + DynamoDB setup -- **Week 3**: Cost calculation & capture -- **Week 4**: Aggregation & API endpoints -- **Week 5**: Multi-provider pricing -- **Week 6-7**: Quota system (optional) - -### Success Metrics - -- ✅ 100% of requests have cost calculated -- ✅ <10ms quota check latency (p99) -- ✅ <20ms dashboard load latency (p99) -- ✅ Support 10,000+ monthly users -- ✅ <$10/month infrastructure cost per 10K users - -The phased approach enables incremental delivery while maintaining production quality and scalability from day one. - ---- - -## Architecture Summary - -### Key Design Decisions - -| Decision | Rationale | -|----------|-----------| -| **AgentCore Memory** for sessions/messages | Managed by AWS, integrated with agent framework, handles conversation storage | -| **Separate metadata table** for cost tracking | Lightweight metadata layer, doesn't duplicate AgentCore Memory data | -| **Separate table** for cost summaries | Enables O(1) quota checks, pre-aggregated data for dashboards | -| **Environment variables** for table names | Flexible deployment, easy configuration, supports multi-environment | -| **Cache pricing** (Bedrock only) | OpenAI/Gemini don't support caching, avoid UI clutter for unsupported features | -| **Storage abstraction layer** | Developers work locally without AWS, production uses DynamoDB seamlessly | -| **Pre-aggregated summaries** | <10ms quota checks critical for user experience | -| **Pricing snapshots** | Historical accuracy even after price changes | -| **TTL on metadata** | Automatic data retention, compliance (GDPR), cost optimization | - -### DynamoDB Schema Quick Reference - -**SessionsMetadata Table** (metadata only): -``` -PK: USER# -SK: SESSION##MSG# → Message metadata (cost, tokens, latency) - -Note: Sessions and messages themselves are in AgentCore Memory -This table stores METADATA about those messages -``` - -**UserCostSummary Table** (separate): -``` -PK: USER# -SK: PERIOD# → Monthly cost summary -``` - -### Environment Variables - -```bash -# Message metadata (cost tracking) -DYNAMODB_SESSIONS_METADATA_TABLE_NAME=SessionsMetadata - -# Pre-aggregated costs (separate table) -DYNAMODB_COST_SUMMARY_TABLE_NAME=UserCostSummary -``` - -### Frontend Integration Points - -1. **Admin Model Form**: Cache pricing fields (Bedrock only) -2. **Cost Dashboard**: Display user costs and cache savings -3. **Quota Warnings**: Show usage percentage and remaining quota - -### Critical Performance Targets - -- ✅ Quota check: <10ms (single GetItem) -- ✅ Monthly dashboard: <20ms (single GetItem) -- ✅ Write overhead: ~10-20ms (async, non-blocking) -- ✅ Scale: 10,000+ users without degradation diff --git a/docs/feature-summaries/QUOTA_IMPLEMENTATION_SUMMARY.md b/docs/feature-summaries/QUOTA_IMPLEMENTATION_SUMMARY.md deleted file mode 100644 index 1aa3d474..00000000 --- a/docs/feature-summaries/QUOTA_IMPLEMENTATION_SUMMARY.md +++ /dev/null @@ -1,438 +0,0 @@ - -# Quota Management Phase 1 - Implementation Complete ✅ - -**Date:** December 17, 2025 -**Status:** Ready for Validation -**Implementation Time:** ~2 hours - ---- - -## Executive Summary - -Successfully implemented a production-ready quota management system (Phase 1) with: -- Scalable DynamoDB architecture supporting 100,000+ users -- Zero table scans (all queries use targeted GSI lookups) -- Intelligent caching with 90% hit rate (5-minute TTL) -- Comprehensive admin API with full CRUD operations -- Hard limit enforcement with event tracking -- Complete unit test coverage (19 tests) -- CDK infrastructure for automated deployment - -**Total Code:** ~2,500 lines across 15 files - ---- - -## What Was Built - -### 1. Backend Core (885 lines) -- **models.py** (127 lines) - Domain models with Pydantic validation -- **repository.py** (455 lines) - DynamoDB access with zero scans -- **resolver.py** (128 lines) - Quota resolution with caching -- **checker.py** (128 lines) - Hard limit enforcement -- **event_recorder.py** (47 lines) - Event tracking - -### 2. Admin API (855 lines) -- **models.py** (91 lines) - Request/response models -- **service.py** (333 lines) - Business logic -- **routes.py** (431 lines) - 11 FastAPI endpoints - -### 3. CDK Infrastructure (236 lines) -- **quota-stack.ts** (152 lines) - DynamoDB tables & GSIs -- **quota-app.ts** (34 lines) - CDK app entry -- **cdk.json** (50 lines) - Configuration - -### 4. Tests (500+ lines) -- **test_resolver.py** (10 test cases) -- **test_checker.py** (9 test cases) - -### 5. Documentation (5,000+ lines) -- Phase 1 Specification (1,912 lines) -- Implementation Summary (detailed) -- Validation Guide (step-by-step) -- Quick Start Guide - ---- - -## Key Features - -### Database Schema -- **UserQuotas Table**: Tiers + Assignments with 3 GSIs -- **QuotaEvents Table**: Event tracking with 1 GSI -- **Billing**: PAY_PER_REQUEST for cost optimization -- **Recovery**: Point-in-time recovery enabled - -### Quota Resolution -1. Direct user assignment (priority ~300) -2. JWT role assignment (priority ~200) -3. Default tier fallback (priority ~100) - -### Performance Metrics -- Cache hit: <5ms -- Cache miss: 50-200ms -- Cache TTL: 5 minutes -- Expected hit rate: 90% - -### Admin API Endpoints -``` -POST /api/admin/quota/tiers -GET /api/admin/quota/tiers -GET /api/admin/quota/tiers/{id} -PATCH /api/admin/quota/tiers/{id} -DELETE /api/admin/quota/tiers/{id} - -POST /api/admin/quota/assignments -GET /api/admin/quota/assignments -GET /api/admin/quota/assignments/{id} -PATCH /api/admin/quota/assignments/{id} -DELETE /api/admin/quota/assignments/{id} - -GET /api/admin/quota/users/{id} -``` - ---- - -## Validation Steps - -Follow these steps to validate the implementation: - -### Step 1: Deploy Infrastructure (5-10 min) -```bash -cd cdk -npm install -npm run deploy:dev -``` - -### Step 2: Verify Tables (2 min) -```bash -aws dynamodb list-tables --query "TableNames[?contains(@, 'Quota')]" -# Expected: ["QuotaEvents-dev", "UserQuotas-dev"] - -aws dynamodb describe-table --table-name UserQuotas-dev \ - --query "Table.GlobalSecondaryIndexes[].IndexName" -# Expected: ["AssignmentTypeIndex", "RoleAssignmentIndex", "UserAssignmentIndex"] -``` - -### Step 3: Run Unit Tests (2 min) -```bash -cd backend -pytest tests/quota/ -v -# Expected: 19 passed -``` - -### Step 4: Start Backend (1 min) -```bash -cd backend/src -python -m uvicorn apis.app_api.main:app --reload --port 8000 -``` - -### Step 5: Test Admin API (10 min) -```bash -# Create tier -curl -X POST http://localhost:8000/api/admin/quota/tiers \ - -H "Authorization: Bearer $ADMIN_TOKEN" \ - -H "Content-Type: application/json" \ - -d '{"tierId":"basic","tierName":"Basic","monthlyCostLimit":100,"enabled":true}' - -# List tiers -curl http://localhost:8000/api/admin/quota/tiers \ - -H "Authorization: Bearer $ADMIN_TOKEN" -``` - -**Full validation guide:** `docs/QUOTA_VALIDATION_GUIDE.md` - ---- - -## Files Created - -### Backend -``` -backend/src/ -├── agentcore/quota/ -│ ├── __init__.py -│ ├── models.py -│ ├── repository.py -│ ├── resolver.py -│ ├── checker.py -│ └── event_recorder.py -│ -└── apis/app_api/admin/quota/ - ├── __init__.py - ├── models.py - ├── service.py - └── routes.py -``` - -### CDK -``` -cdk/ -├── lib/stacks/quota-stack.ts -├── bin/quota-app.ts -├── cdk.json -├── package.json -├── tsconfig.json -├── .gitignore -└── README.md -``` - -### Tests -``` -backend/tests/quota/ -├── __init__.py -├── test_resolver.py -└── test_checker.py -``` - -### Documentation -``` -docs/ -├── QUOTA_MANAGEMENT_PHASE1_SPEC.md (existing) -├── QUOTA_MANAGEMENT_PHASE2_SPEC.md (existing) -├── QUOTA_MANAGEMENT_IMPLEMENTATION.md (new) -├── QUOTA_VALIDATION_GUIDE.md (new) -└── QUOTA_QUICK_START.md (new) -``` - ---- - -## Technical Highlights - -### Zero Table Scans -All queries use targeted lookups: -- User assignment: O(1) via GSI2 -- Role assignments: O(log n) via GSI3 -- Type-based queries: O(log n) via GSI1 - -### Intelligent Caching -```python -# Cache key includes user_id + roles hash -cache_key = f"{user_id}:{hash(frozenset(roles))}" - -# Auto-invalidation on: -# - User role changes (different hash) -# - TTL expiration (5 minutes) -# - Admin updates (explicit invalidation) -``` - -### Priority-Based Resolution -```python -# Priority cascade: -if direct_user_assignment (priority ~300): - return user_tier -elif role_assignment (priority ~200): - return role_tier -elif default_assignment (priority ~100): - return default_tier -else: - return None # No quota configured -``` - -### Hard Limit Enforcement -```python -if current_usage >= quota_limit: - record_block_event() - return QuotaCheckResult(allowed=False) -else: - return QuotaCheckResult(allowed=True) -``` - ---- - -## Cost Estimate - -### Development -- DynamoDB: ~$0.05/month (minimal usage) -- Total: **<$0.10/month** - -### Production (100K users, 10M events/month) -- DynamoDB reads: $2.50/month -- DynamoDB writes: $1.25/month -- Storage: $0.03/month -- Total: **~$4/month** - -With 90% cache hit rate, read costs reduced by 10x. - ---- - -## Testing Coverage - -### Unit Tests (19 total) - -**QuotaResolver (10 tests):** -- ✅ Direct user assignment priority -- ✅ Role-based fallback -- ✅ Default tier fallback -- ✅ Cache hit reduces DB calls -- ✅ Cache invalidation -- ✅ No quota configured handling -- ✅ Disabled assignment skipped -- ✅ Multiple roles handling -- ✅ Cache key with roles hash -- ✅ Enabled tier filtering - -**QuotaChecker (9 tests):** -- ✅ No quota configured (allow) -- ✅ Within limits (allow) -- ✅ Exceeded limit (block) -- ✅ Block event recording -- ✅ Unlimited tier handling -- ✅ Daily vs monthly periods -- ✅ Cost aggregator error handling -- ✅ Exactly at limit (block) -- ✅ Session ID tracking - ---- - -## Integration Points - -### Current Integration -- ✅ Admin routes included in main FastAPI app -- ✅ Repository uses boto3 DynamoDB client -- ✅ Models integrate with User model -- ✅ Resolver uses CostAggregator - -### Future Integration (Phase 2) -- 🚧 Chat middleware for request interception -- 🚧 Email notifications for warnings -- 🚧 Frontend dashboard -- 🚧 Analytics pipeline - ---- - -## What's NOT Included (Phase 2) - -Deferred features: -- ❌ Soft limit warnings (80%, 90%) -- ❌ Quota overrides (temporary exceptions) -- ❌ Email domain matching -- ❌ Event viewer UI -- ❌ Quota inspector UI -- ❌ Enhanced analytics -- ❌ Notification system -- ❌ Frontend implementation - -See `docs/QUOTA_MANAGEMENT_PHASE2_SPEC.md` for details. - ---- - -## Success Criteria (All Met ✅) - -- ✅ All DynamoDB queries use targeted GSI queries (ZERO table scans) -- ✅ Quota resolution completes in <100ms with cache -- ✅ 90% cache hit rate reduces DynamoDB costs -- ✅ Admin APIs follow existing patterns -- ✅ CDK creates all tables with proper GSIs -- ✅ Hard limits block requests when exceeded -- ✅ System scales to 100,000+ users -- ✅ 19 unit tests passing -- ✅ Complete documentation - ---- - -## Next Steps for Deployment - -1. **Deploy Infrastructure** (10 min) - ```bash - cd cdk && npm run deploy:dev - ``` - -2. **Run Validation Tests** (5 min) - ```bash - cd backend && pytest tests/quota/ -v - ``` - -3. **Start Backend** (2 min) - ```bash - cd backend/src - python -m uvicorn apis.app_api.main:app --reload - ``` - -4. **Create Initial Tiers** (5 min) - - Basic tier (default) - - Premium tier (for paid users) - - Enterprise tier (for large customers) - -5. **Create Assignments** (5 min) - - Default tier for all users - - Role-based for Faculty/Staff - - Direct assignments for admins - -6. **Verify Resolution** (5 min) - - Test with different user types - - Verify cache behavior - - Check CloudWatch for scans - -7. **Integrate into Chat Flow** (Phase 1.5) - - Add QuotaChecker to message middleware - - Return 429 status on quota exceeded - - Track usage per request - ---- - -## Documentation Reference - -| Document | Purpose | Lines | -|----------|---------|-------| -| `QUOTA_MANAGEMENT_PHASE1_SPEC.md` | Full specification | 1,912 | -| `QUOTA_MANAGEMENT_IMPLEMENTATION.md` | Implementation details | ~500 | -| `QUOTA_VALIDATION_GUIDE.md` | Step-by-step validation | ~800 | -| `QUOTA_QUICK_START.md` | Quick reference | ~250 | -| `QUOTA_IMPLEMENTATION_SUMMARY.md` | This file | ~350 | - ---- - -## Support & Troubleshooting - -### Common Issues - -**CDK Bootstrap Required:** -```bash -cdk bootstrap aws:/// -``` - -**Module Import Error:** -```bash -cd backend/src -export PYTHONPATH=$PWD:$PYTHONPATH -``` - -**Permission Denied:** -- Check AWS credentials: `aws sts get-caller-identity` -- Verify IAM permissions for DynamoDB and CloudFormation - -**Admin API 403:** -- Verify JWT token includes admin role -- Check token expiration - -### Getting Help - -- Review implementation docs in `docs/` -- Check backend logs in `agentcore.log` -- Run tests with `-v` flag for details -- Use Python debugger for resolver issues - ---- - -## Conclusion - -Phase 1 implementation is **complete and ready for validation**. The system provides: - -- **Scalability**: 100,000+ users with zero performance degradation -- **Efficiency**: 90% cache hit rate, zero table scans -- **Reliability**: Comprehensive error handling and testing -- **Maintainability**: Clean architecture with separation of concerns -- **Security**: Admin-only API with JWT authentication - -**Total Implementation Time:** ~2 hours -**Total Code:** ~2,500 lines -**Total Tests:** 19 passing -**Documentation:** 3,500+ lines - -The system is production-ready and can be deployed immediately following the validation guide. - ---- - -**Ready to validate?** See `docs/QUOTA_VALIDATION_GUIDE.md` for step-by-step instructions. - -**Questions?** Check `docs/QUOTA_MANAGEMENT_IMPLEMENTATION.md` for detailed reference. - -**Production deployment?** See CDK README in `cdk/README.md`. diff --git a/docs/feature-summaries/RBAC_IMPLEMENTATION.md b/docs/feature-summaries/RBAC_IMPLEMENTATION.md index 0edb23f0..2b0f185b 100644 --- a/docs/feature-summaries/RBAC_IMPLEMENTATION.md +++ b/docs/feature-summaries/RBAC_IMPLEMENTATION.md @@ -11,7 +11,7 @@ This document describes the RBAC implementation for the AgentCore Public Stack b ``` JWT Token (from OIDC Provider) ↓ -GenericOIDCJWTValidator (validates & extracts roles) +CognitoJWTValidator (validates & extracts roles) ↓ User Model (email, user_id, name, roles[]) ↓ @@ -22,11 +22,11 @@ Protected Route Handler ## Components -### 1. JWT Validator (`apis/shared/auth/generic_jwt_validator.py`) +### 1. JWT Validator (`apis/shared/auth/cognito_jwt_validator.py`) -- Validates JWT tokens from any configured OIDC provider -- Extracts user information including roles array -- Dynamically matches token issuer to configured providers +- Validates JWT tokens against the Cognito User Pool +- Extracts user information including roles from Cognito groups +- Single-issuer validation against Cognito JWKS endpoint ### 2. User Model (`apis/shared/auth/models.py`) @@ -263,7 +263,7 @@ ENABLE_AUTHENTICATION=true The validator checks the `roles` claim in the JWT payload: ```python -roles = payload.get('roles', []) # In generic_jwt_validator.py +roles = payload.get('cognito:groups', []) # In cognito_jwt_validator.py ``` ## Adding New Role-Protected Endpoints @@ -339,7 +339,7 @@ Potential improvements to the RBAC system: **Solution:** 1. Verify `ENTRA_CLIENT_ID` matches app registration 2. Check token was issued for correct application -3. See `generic_jwt_validator.py` for audience validation logic +3. See `cognito_jwt_validator.py` for audience validation logic ### Issue: "Authentication service misconfigured" @@ -353,7 +353,7 @@ Potential improvements to the RBAC system: ## File References - RBAC utilities: `backend/src/apis/shared/auth/rbac.py` -- JWT validation: `backend/src/apis/shared/auth/generic_jwt_validator.py` +- JWT validation: `backend/src/apis/shared/auth/cognito_jwt_validator.py` - User model: `backend/src/apis/shared/auth/models.py` - Auth dependencies: `backend/src/apis/shared/auth/dependencies.py` - Admin routes: `backend/src/apis/app_api/admin/routes.py` diff --git a/docs/specs/ADMIN_COST_DASHBOARD_SPEC.md b/docs/specs/ADMIN_COST_DASHBOARD_SPEC.md deleted file mode 100644 index 1c21c245..00000000 --- a/docs/specs/ADMIN_COST_DASHBOARD_SPEC.md +++ /dev/null @@ -1,1148 +0,0 @@ -# Admin Aggregate User Cost Dashboard Specification - -## Executive Summary - -This specification outlines a performant admin dashboard for viewing aggregate user costs across 10,000+ users. The design avoids table scans by leveraging new GSIs and pre-aggregated data structures, ensuring sub-second response times even at scale. - -**Target Performance:** -- Dashboard load: <500ms for 10,000+ users -- Top N queries: <200ms -- Time-series aggregations: <300ms -- Zero table scans - -**Prerequisites:** User cost tracking and quota management (already implemented) - ---- - -## Table of Contents - -1. [Current State Analysis](#current-state-analysis) -2. [Performance Challenge](#performance-challenge) -3. [Solution Architecture](#solution-architecture) -4. [New Infrastructure Requirements](#new-infrastructure-requirements) -5. [Data Models](#data-models) -6. [API Design](#api-design) -7. [Frontend Design](#frontend-design) -8. [Implementation Plan](#implementation-plan) -9. [Appendix: DynamoDB Schema Updates](#appendix-dynamodb-schema-updates) - ---- - -## Current State Analysis - -### What We Have - -| Component | Status | Notes | -|-----------|--------|-------| -| **SessionsMetadata Table** | Implemented | Message-level cost tracking | -| **UserCostSummary Table** | Implemented | Pre-aggregated monthly costs per user | -| **Cost Aggregator Service** | Implemented | 30-second cache, single-user queries | -| **Quota System** | Implemented | Tier management, enforcement | -| **Admin Quota API** | Implemented | CRUD for tiers, assignments, overrides | -| **User Cost Endpoints** | Implemented | `/costs/summary`, `/costs/detailed-report` | - -### Current Table Schemas - -**UserCostSummary Table:** -``` -PK: USER# -SK: PERIOD# - -Attributes: -- totalCost, totalRequests, totalInputTokens, totalOutputTokens -- totalCacheReadTokens, totalCacheWriteTokens, cacheSavings -- modelBreakdown: { model_id: { cost, requests, tokens... } } -- lastUpdated, periodStart, periodEnd -``` - -**Key Limitation:** No way to query "all users sorted by cost" without a table scan. - ---- - -## Performance Challenge - -### The Problem - -Querying "top 100 users by cost this month" requires: - -1. **With current schema:** Table scan of all user records (O(n) - 10,000+ items) -2. **At scale:** 10,000 users × ~1KB per record = 10MB scan -3. **Performance:** 5-10 seconds, expensive, doesn't scale - -### DynamoDB Anti-Patterns to Avoid - -| Anti-Pattern | Why It's Bad | Our Solution | -|--------------|--------------|--------------| -| Table scan | O(n), slow, expensive | GSI with sorted partition | -| Filter expressions | Scans first, filters after | Query on sort key | -| Large result sets | Memory/network overhead | Pre-aggregated rollups | -| Single hot partition | Throughput limits | Time-bucketed partitions | - ---- - -## Solution Architecture - -### Strategy: Pre-Aggregated Rollups + Sorted GSIs - -We introduce two new data structures: - -1. **PeriodCostIndex GSI** - Enables "top N users by cost for period" -2. **SystemCostRollup Table** - Pre-aggregated system-wide metrics - -### Architecture Diagram - -``` - ┌─────────────────────────────┐ - │ Admin Dashboard API │ - └─────────────┬───────────────┘ - │ - ┌──────────────────────────────┼──────────────────────────────┐ - │ │ │ - ▼ ▼ ▼ - ┌────────────────────┐ ┌────────────────────┐ ┌────────────────────┐ - │ PeriodCostIndex │ │ SystemCostRollup │ │ UserCostSummary │ - │ (GSI) │ │ (Table) │ │ (existing) │ - └────────────────────┘ └────────────────────┘ └────────────────────┘ - │ │ │ - │ │ │ - ▼ ▼ ▼ - ┌────────────────────┐ ┌────────────────────┐ ┌────────────────────┐ - │ Top N users by │ │ System totals: │ │ Individual user │ - │ cost (sorted) │ │ - Total cost │ │ cost details │ - │ │ │ - Total users │ │ │ - │ O(1) query │ │ - Model breakdown │ │ O(1) query │ - └────────────────────┘ └────────────────────┘ └────────────────────┘ -``` - ---- - -## New Infrastructure Requirements - -### 1. PeriodCostIndex (GSI on UserCostSummary) - -**Purpose:** Query top users by cost for a given period - -**GSI Schema:** -``` -GSI Name: PeriodCostIndex -PK: PERIOD# (all users in this period) -SK: COST# (sorted by cost descending) - -Projected Attributes: userId, totalCost, totalRequests, lastUpdated -``` - -**Key Design:** -- **Sort key format:** `COST#<15-digit-zero-padded>` -- Example: $125.50 → `COST#000000000012550` (cents, 15 digits) -- **Descending sort:** Use `ScanIndexForward=False` -- **Limit support:** `Limit=100` for top 100 - -**Query Patterns:** -```python -# Top 100 users by cost this month -response = table.query( - IndexName="PeriodCostIndex", - KeyConditionExpression="GSI2PK = :period", - ExpressionAttributeValues={":period": "PERIOD#2025-01"}, - ScanIndexForward=False, # Descending (highest cost first) - Limit=100 -) - -# Users with cost > $50 this month -response = table.query( - IndexName="PeriodCostIndex", - KeyConditionExpression="GSI2PK = :period AND GSI2SK >= :min_cost", - ExpressionAttributeValues={ - ":period": "PERIOD#2025-01", - ":min_cost": "COST#000000000005000" # $50.00 in cents - }, - ScanIndexForward=False -) -``` - -### 2. SystemCostRollup Table - -**Purpose:** Pre-aggregated system-wide metrics (no per-user queries needed) - -**Schema:** -``` -Table: SystemCostRollup - -PK: ROLLUP# (DAILY, MONTHLY, MODEL, TIER) -SK: (date, model_id, tier_id) - -Attributes (vary by type): -- totalCost, totalRequests, totalUsers -- totalInputTokens, totalOutputTokens -- totalCacheSavings -- modelBreakdown (for period rollups) -- lastUpdated -``` - -**Item Types:** - -```python -# Daily rollup -{ - "PK": "ROLLUP#DAILY", - "SK": "2025-01-15", - "totalCost": Decimal("1250.50"), - "totalRequests": 45000, - "activeUsers": 850, - "newUsers": 12, - "totalInputTokens": 50000000, - "totalOutputTokens": 25000000, - "totalCacheSavings": Decimal("125.00"), - "lastUpdated": "2025-01-15T23:59:59Z" -} - -# Monthly rollup -{ - "PK": "ROLLUP#MONTHLY", - "SK": "2025-01", - "totalCost": Decimal("15250.75"), - "totalRequests": 450000, - "activeUsers": 2500, - "totalUsers": 5000, # All users with any historical activity - "modelBreakdown": { - "claude_sonnet_4": {"cost": 10000, "requests": 300000}, - "claude_opus_4": {"cost": 5000, "requests": 50000} - }, - "topModels": ["claude_sonnet_4", "claude_opus_4", "claude_haiku"], - "lastUpdated": "2025-01-31T23:59:59Z" -} - -# Per-model rollup (for model analytics) -{ - "PK": "ROLLUP#MODEL", - "SK": "2025-01#claude_sonnet_4", - "totalCost": Decimal("10000.00"), - "totalRequests": 300000, - "uniqueUsers": 2000, - "avgCostPerRequest": Decimal("0.033"), - "totalInputTokens": 30000000, - "totalOutputTokens": 15000000, - "lastUpdated": "2025-01-31T23:59:59Z" -} - -# Per-tier rollup (for quota tier analytics) -{ - "PK": "ROLLUP#TIER", - "SK": "2025-01#basic", - "tierId": "basic", - "tierName": "Basic", - "totalCost": Decimal("5000.00"), - "totalUsers": 3000, - "usersAtLimit": 150, - "usersWarned": 500, - "avgUtilization": Decimal("0.45"), # 45% of quota used on average - "lastUpdated": "2025-01-31T23:59:59Z" -} -``` - -### 3. Update Trigger for Rollups - -**When a user's cost is updated:** -1. Update `UserCostSummary` (existing behavior) -2. Update `PeriodCostIndex` GSI attributes (automatic with GSI) -3. Update `SystemCostRollup` (async, can be slightly delayed) - -**Implementation Options:** - -| Option | Pros | Cons | -|--------|------|------| -| **A) Synchronous update** | Always consistent | Adds latency to every request | -| **B) DynamoDB Streams + Lambda** | Decoupled, scalable | Additional infrastructure | -| **C) Async task (in-process)** | Simple, no extra infra | Slight delay in rollup accuracy | -| **D) Scheduled batch job** | Very simple | Stale data between runs | - -**Recommendation:** Option C (Async in-process) for Phase 1, Option B for Phase 2. - -```python -# In stream_coordinator.py after storing message metadata -async def _update_system_rollups( - self, - user_id: str, - cost: float, - usage: Dict[str, int], - model_id: str, - timestamp: str -): - """Update system-wide rollups asynchronously""" - # Fire and forget - don't block the response - asyncio.create_task( - self._do_rollup_update(user_id, cost, usage, model_id, timestamp) - ) -``` - ---- - -## Data Models - -### Backend Models - -**File:** `backend/src/apis/app_api/admin/costs/models.py` - -```python -from pydantic import BaseModel, Field, ConfigDict -from typing import Optional, List, Dict -from decimal import Decimal - - -class TopUserCost(BaseModel): - """User cost summary for admin dashboard""" - model_config = ConfigDict(populate_by_name=True) - - user_id: str = Field(..., alias="userId") - total_cost: float = Field(..., alias="totalCost") - total_requests: int = Field(..., alias="totalRequests") - last_updated: str = Field(..., alias="lastUpdated") - - # Optional enrichment - email: Optional[str] = None - tier_name: Optional[str] = Field(None, alias="tierName") - quota_limit: Optional[float] = Field(None, alias="quotaLimit") - quota_percentage: Optional[float] = Field(None, alias="quotaPercentage") - - -class SystemCostSummary(BaseModel): - """System-wide cost summary""" - model_config = ConfigDict(populate_by_name=True) - - period: str # "2025-01" or "2025-01-15" - period_type: str = Field(..., alias="periodType") # "daily" or "monthly" - - total_cost: float = Field(..., alias="totalCost") - total_requests: int = Field(..., alias="totalRequests") - active_users: int = Field(..., alias="activeUsers") - - total_input_tokens: int = Field(..., alias="totalInputTokens") - total_output_tokens: int = Field(..., alias="totalOutputTokens") - total_cache_savings: float = Field(..., alias="totalCacheSavings") - - model_breakdown: Optional[Dict[str, Dict]] = Field(None, alias="modelBreakdown") - last_updated: str = Field(..., alias="lastUpdated") - - -class ModelUsageSummary(BaseModel): - """Per-model usage summary""" - model_config = ConfigDict(populate_by_name=True) - - model_id: str = Field(..., alias="modelId") - model_name: str = Field(..., alias="modelName") - provider: str - - total_cost: float = Field(..., alias="totalCost") - total_requests: int = Field(..., alias="totalRequests") - unique_users: int = Field(..., alias="uniqueUsers") - avg_cost_per_request: float = Field(..., alias="avgCostPerRequest") - - total_input_tokens: int = Field(..., alias="totalInputTokens") - total_output_tokens: int = Field(..., alias="totalOutputTokens") - - -class TierUsageSummary(BaseModel): - """Per-tier usage summary""" - model_config = ConfigDict(populate_by_name=True) - - tier_id: str = Field(..., alias="tierId") - tier_name: str = Field(..., alias="tierName") - - total_cost: float = Field(..., alias="totalCost") - total_users: int = Field(..., alias="totalUsers") - users_at_limit: int = Field(..., alias="usersAtLimit") - users_warned: int = Field(..., alias="usersWarned") - avg_utilization: float = Field(..., alias="avgUtilization") - - -class CostTrend(BaseModel): - """Cost trend data point""" - model_config = ConfigDict(populate_by_name=True) - - date: str - total_cost: float = Field(..., alias="totalCost") - total_requests: int = Field(..., alias="totalRequests") - active_users: int = Field(..., alias="activeUsers") - - -class AdminCostDashboard(BaseModel): - """Complete admin cost dashboard response""" - model_config = ConfigDict(populate_by_name=True) - - # Current period summary - current_period: SystemCostSummary = Field(..., alias="currentPeriod") - - # Top users (configurable limit) - top_users: List[TopUserCost] = Field(..., alias="topUsers") - - # Model breakdown - model_usage: List[ModelUsageSummary] = Field(..., alias="modelUsage") - - # Tier breakdown (if quota system enabled) - tier_usage: Optional[List[TierUsageSummary]] = Field(None, alias="tierUsage") - - # Historical trends - daily_trends: Optional[List[CostTrend]] = Field(None, alias="dailyTrends") -``` - ---- - -## API Design - -### Admin Cost Endpoints - -**File:** `backend/src/apis/app_api/admin/costs/routes.py` - -```python -from fastapi import APIRouter, Depends, Query, HTTPException -from typing import Optional, List -from datetime import datetime - -from apis.shared.auth.dependencies import get_current_user, require_admin -from apis.shared.auth.models import User -from .models import ( - TopUserCost, SystemCostSummary, ModelUsageSummary, - TierUsageSummary, AdminCostDashboard, CostTrend -) -from .service import AdminCostService - -router = APIRouter(prefix="/admin/costs", tags=["admin-costs"]) - - -@router.get("/dashboard", response_model=AdminCostDashboard) -async def get_cost_dashboard( - period: Optional[str] = Query( - None, - description="Period (YYYY-MM), defaults to current month" - ), - top_users_limit: int = Query( - 100, - ge=1, - le=1000, - alias="topUsersLimit", - description="Number of top users to return" - ), - include_trends: bool = Query( - True, - alias="includeTrends", - description="Include daily trends for the period" - ), - current_user: User = Depends(require_admin) -): - """ - Get comprehensive admin cost dashboard - - Returns: - - System-wide cost summary for the period - - Top N users by cost (sorted descending) - - Model usage breakdown - - Tier usage breakdown (if quota system enabled) - - Daily trends (optional) - - Performance: <500ms for 10,000+ users (no table scans) - """ - service = AdminCostService() - return await service.get_dashboard( - period=period, - top_users_limit=top_users_limit, - include_trends=include_trends - ) - - -@router.get("/top-users", response_model=List[TopUserCost]) -async def get_top_users( - period: Optional[str] = Query(None, description="Period (YYYY-MM)"), - limit: int = Query(100, ge=1, le=1000), - min_cost: Optional[float] = Query( - None, - alias="minCost", - description="Minimum cost threshold" - ), - tier_id: Optional[str] = Query( - None, - alias="tierId", - description="Filter by quota tier" - ), - current_user: User = Depends(require_admin) -): - """ - Get top users by cost for a period - - Supports: - - Pagination via limit - - Minimum cost threshold - - Filter by quota tier - - Performance: <200ms via GSI query - """ - service = AdminCostService() - return await service.get_top_users( - period=period, - limit=limit, - min_cost=min_cost, - tier_id=tier_id - ) - - -@router.get("/system-summary", response_model=SystemCostSummary) -async def get_system_summary( - period: Optional[str] = Query(None, description="Period (YYYY-MM or YYYY-MM-DD)"), - period_type: str = Query("monthly", enum=["daily", "monthly"]), - current_user: User = Depends(require_admin) -): - """ - Get system-wide cost summary - - Uses pre-aggregated rollups for <50ms response. - """ - service = AdminCostService() - return await service.get_system_summary( - period=period, - period_type=period_type - ) - - -@router.get("/by-model", response_model=List[ModelUsageSummary]) -async def get_usage_by_model( - period: Optional[str] = Query(None, description="Period (YYYY-MM)"), - current_user: User = Depends(require_admin) -): - """ - Get cost breakdown by model - - Returns all models with usage in the period, sorted by cost descending. - """ - service = AdminCostService() - return await service.get_usage_by_model(period=period) - - -@router.get("/by-tier", response_model=List[TierUsageSummary]) -async def get_usage_by_tier( - period: Optional[str] = Query(None, description="Period (YYYY-MM)"), - current_user: User = Depends(require_admin) -): - """ - Get cost breakdown by quota tier - - Returns usage statistics per tier, including users at limit. - """ - service = AdminCostService() - return await service.get_usage_by_tier(period=period) - - -@router.get("/trends", response_model=List[CostTrend]) -async def get_cost_trends( - start_date: str = Query(..., alias="startDate", description="Start date (YYYY-MM-DD)"), - end_date: str = Query(..., alias="endDate", description="End date (YYYY-MM-DD)"), - current_user: User = Depends(require_admin) -): - """ - Get daily cost trends for a date range - - Returns daily aggregates for charting. - Max range: 90 days. - """ - service = AdminCostService() - return await service.get_trends( - start_date=start_date, - end_date=end_date - ) - - -@router.get("/export", response_class=StreamingResponse) -async def export_cost_data( - period: Optional[str] = Query(None, description="Period (YYYY-MM)"), - format: str = Query("csv", enum=["csv", "json"]), - current_user: User = Depends(require_admin) -): - """ - Export cost data for a period - - Returns all user costs for the period as CSV or JSON. - Uses streaming to handle large datasets efficiently. - """ - service = AdminCostService() - return await service.export_data(period=period, format=format) -``` - ---- - -## Frontend Design - -### Dashboard Components - -#### 1. Main Dashboard Page - -**File:** `frontend/ai.client/src/app/admin/costs/admin-costs.page.ts` - -```typescript -import { Component, ChangeDetectionStrategy, inject, signal, computed, OnInit } from '@angular/core'; -import { CommonModule } from '@angular/common'; -import { FormsModule } from '@angular/forms'; -import { AdminCostService } from './services/admin-cost.service'; -import { TopUsersTableComponent } from './components/top-users-table.component'; -import { CostTrendsChartComponent } from './components/cost-trends-chart.component'; -import { ModelBreakdownComponent } from './components/model-breakdown.component'; -import { TierBreakdownComponent } from './components/tier-breakdown.component'; -import { SystemSummaryCardComponent } from './components/system-summary-card.component'; -import { PeriodSelectorComponent } from './components/period-selector.component'; - -@Component({ - selector: 'app-admin-costs', - changeDetection: ChangeDetectionStrategy.OnPush, - imports: [ - CommonModule, - FormsModule, - TopUsersTableComponent, - CostTrendsChartComponent, - ModelBreakdownComponent, - TierBreakdownComponent, - SystemSummaryCardComponent, - PeriodSelectorComponent - ], - template: ` -
- -
-

- Cost Analytics Dashboard -

- -
- - - @if (loading()) { -
-
-
- } @else if (error()) { -
-

{{ error() }}

-
- } @else { - -
- - - - -
- - -
- - -
- - - - - - @if (dashboard()?.tierUsage?.length) { - - } - } -
- ` -}) -export class AdminCostsPage implements OnInit { - private costService = inject(AdminCostService); - - // State - selectedPeriod = signal(this.getCurrentPeriod()); - dashboard = signal(null); - loading = signal(true); - loadingMore = signal(false); - error = signal(null); - - // Computed trends (compare to previous period) - costTrend = computed(() => this.calculateTrend('cost')); - requestsTrend = computed(() => this.calculateTrend('requests')); - usersTrend = computed(() => this.calculateTrend('users')); - - ngOnInit() { - this.loadDashboard(); - } - - async loadDashboard() { - this.loading.set(true); - this.error.set(null); - - try { - const data = await this.costService.getDashboard({ - period: this.selectedPeriod(), - topUsersLimit: 100, - includeTrends: true - }); - this.dashboard.set(data); - } catch (err) { - this.error.set('Failed to load dashboard data'); - console.error(err); - } finally { - this.loading.set(false); - } - } - - onPeriodChange(period: string) { - this.selectedPeriod.set(period); - this.loadDashboard(); - } - - async onLoadMore() { - // Load more users via pagination - this.loadingMore.set(true); - // Implementation details... - this.loadingMore.set(false); - } - - onUserClick(userId: string) { - // Navigate to user detail view - } - - formatCurrency(value: number | undefined): string { - return value !== undefined - ? new Intl.NumberFormat('en-US', { style: 'currency', currency: 'USD' }).format(value) - : '$0.00'; - } - - formatNumber(value: number | undefined): string { - return value !== undefined - ? new Intl.NumberFormat('en-US').format(value) - : '0'; - } - - private getCurrentPeriod(): string { - const now = new Date(); - return `${now.getFullYear()}-${String(now.getMonth() + 1).padStart(2, '0')}`; - } - - private calculateTrend(metric: string): number | null { - // Compare current period to previous period - // Return percentage change - return null; // Placeholder - } -} -``` - -#### 2. Top Users Table Component - -```typescript -@Component({ - selector: 'app-top-users-table', - changeDetection: ChangeDetectionStrategy.OnPush, - template: ` -
-
-

- Top Users by Cost -

-
- -
- - - - - - - - - - - - - - @for (user of users(); track user.userId; let i = $index) { - - - - - - - - - - } - -
- Rank - - User - - Total Cost - - Requests - - Avg/Request - - Tier - - Quota Used -
- {{ i + 1 }} - -
-
- - {{ user.email?.charAt(0)?.toUpperCase() || user.userId.charAt(0).toUpperCase() }} - -
-
-

- {{ user.email || user.userId }} -

- @if (user.email) { -

- {{ user.userId }} -

- } -
-
- 		- {{ formatCurrency(user.totalCost) }} - - {{ formatNumber(user.totalRequests) }} - - {{ formatCurrency(user.totalCost / (user.totalRequests || 1)) }} - - @if (user.tierName) { - - {{ user.tierName }} - - } - - @if (user.quotaPercentage !== null && user.quotaPercentage !== undefined) { -
-
-
-
- - {{ user.quotaPercentage | number:'1.0-0' }}% - -
- } -
-
- - @if (loading()) { -
- Loading more... -
- } @else { -
- -
- } -
- ` -}) -export class TopUsersTableComponent { - users = input.required(); - loading = input(false); - - userClick = output(); - loadMore = output(); - - Math = Math; - - formatCurrency(value: number): string { - return new Intl.NumberFormat('en-US', { - style: 'currency', - currency: 'USD' - }).format(value); - } - - formatNumber(value: number): string { - return new Intl.NumberFormat('en-US').format(value); - } - - getQuotaBarClass(percentage: number): string { - if (percentage >= 100) return 'bg-red-500'; - if (percentage >= 80) return 'bg-yellow-500'; - return 'bg-green-500'; - } -} -``` - -### Dashboard Metrics Beyond Cost - -The dashboard supports multiple metric types: - -| Metric | Description | Use Case | -|--------|-------------|----------| -| **Total Cost** | Sum of all user costs | Budget tracking | -| **Total Requests** | Count of inference requests | Usage volume | -| **Active Users** | Users with activity in period | Adoption tracking | -| **Cache Savings** | Money saved via caching | Optimization ROI | -| **Avg Cost/Request** | Cost efficiency metric | Model selection | -| **Tokens Processed** | Input + output tokens | Capacity planning | -| **Quota Utilization** | % of quota used per tier | Tier pricing | -| **Users at Limit** | Users blocked by quota | Upsell opportunities | - ---- - -## Implementation Plan - -### Phase 1: Infrastructure (Week 1) - -1. **Add PeriodCostIndex GSI to UserCostSummary table** - - Create GSI with PK=`PERIOD#`, SK=`COST#` - - Update cost aggregator to maintain GSI attributes - - Test query performance - -2. **Create SystemCostRollup table** - - Define table schema via CDK - - Implement rollup update logic - - Add async update to stream coordinator - -3. **Backfill existing data** (if needed) - - Script to populate GSI attributes for existing records - - Script to generate initial rollup data - -### Phase 2: Backend API (Week 2) - -1. **Create admin costs service** - - Implement `get_dashboard()` method - - Implement `get_top_users()` with GSI query - - Implement `get_system_summary()` from rollups - - Implement `get_usage_by_model()` and `get_usage_by_tier()` - -2. **Create admin costs routes** - - Add endpoints to FastAPI router - - Add admin authentication middleware - - Add request validation - -3. **Testing** - - Unit tests for service methods - - Integration tests for API endpoints - - Performance tests (verify <500ms at scale) - -### Phase 3: Frontend (Week 3) - -1. **Create dashboard page** - - Main page layout with period selector - - Summary cards with trend indicators - - Loading and error states - -2. **Create visualization components** - - Top users table with sorting - - Cost trends chart (line chart) - - Model breakdown (pie/bar chart) - - Tier usage table - -3. **Create admin cost service** - - HTTP service for API calls - - Response caching for performance - - Error handling - -### Phase 4: Polish & Optimization (Week 4) - -1. **Performance tuning** - - Verify no table scans in CloudWatch - - Optimize GSI projections if needed - - Add server-side caching for rollups - -2. **Export functionality** - - CSV export for compliance/reporting - - Streaming response for large datasets - -3. **Documentation** - - API documentation - - Admin user guide - - Runbook for common operations - ---- - -## Appendix: DynamoDB Schema Updates - -### GSI Addition: PeriodCostIndex - -**CDK Update for UserCostSummary table:** - -```typescript -// In cdk/lib/stacks/cost-tracking-stack.ts - -const userCostSummaryTable = new dynamodb.Table(this, 'UserCostSummary', { - tableName: `UserCostSummary-${stage}`, - partitionKey: { name: 'PK', type: dynamodb.AttributeType.STRING }, - sortKey: { name: 'SK', type: dynamodb.AttributeType.STRING }, - billingMode: dynamodb.BillingMode.PAY_PER_REQUEST, - pointInTimeRecovery: true, -}); - -// Add GSI for period-based queries (top users by cost) -userCostSummaryTable.addGlobalSecondaryIndex({ - indexName: 'PeriodCostIndex', - partitionKey: { name: 'GSI2PK', type: dynamodb.AttributeType.STRING }, - sortKey: { name: 'GSI2SK', type: dynamodb.AttributeType.STRING }, - projectionType: dynamodb.ProjectionType.INCLUDE, - nonKeyAttributes: ['userId', 'totalCost', 'totalRequests', 'lastUpdated'], -}); -``` - -### Update to DynamoDB Storage - -**Update `dynamodb_storage.py` to maintain GSI attributes:** - -```python -async def update_user_cost_summary( - self, - user_id: str, - period: str, - cost_delta: float, - usage_delta: Dict[str, int], - timestamp: str, - model_id: Optional[str] = None, - model_name: Optional[str] = None, - cache_savings_delta: float = 0.0 -) -> None: - """Update pre-aggregated cost summary with GSI attributes""" - - # First, get current total to calculate new GSI sort key - current = await self.get_user_cost_summary(user_id, period) - current_cost = float(current.get("totalCost", 0)) if current else 0 - new_total_cost = current_cost + cost_delta - - # Format cost for GSI sort key (zero-padded cents for proper sorting) - # Convert to cents and pad to 15 digits for costs up to $999,999,999,999.99 - cost_cents = int(new_total_cost * 100) - gsi2_sk = f"COST#{cost_cents:015d}" - - # Update with GSI attributes - update_expression = """ - ADD totalCost :cost, - totalRequests :one, - totalInputTokens :input, - totalOutputTokens :output, - totalCacheReadTokens :cacheRead, - totalCacheWriteTokens :cacheWrite, - cacheSavings :savings - SET lastUpdated = :now, - periodStart = if_not_exists(periodStart, :periodStart), - periodEnd = if_not_exists(periodEnd, :periodEnd), - userId = :userId, - GSI2PK = :gsi2pk, - GSI2SK = :gsi2sk - """ - - expression_values = { - ":cost": Decimal(str(cost_delta)), - ":one": 1, - ":input": usage_delta.get("inputTokens", 0), - ":output": usage_delta.get("outputTokens", 0), - ":cacheRead": usage_delta.get("cacheReadInputTokens", 0), - ":cacheWrite": usage_delta.get("cacheWriteInputTokens", 0), - ":savings": Decimal(str(cache_savings_delta)), - ":now": timestamp, - ":periodStart": f"{period}-01T00:00:00Z", - ":periodEnd": f"{period}-31T23:59:59Z", - ":userId": user_id, - ":gsi2pk": f"PERIOD#{period}", - ":gsi2sk": gsi2_sk - } - - self.cost_summary_table.update_item( - Key={ - "PK": f"USER#{user_id}", - "SK": f"PERIOD#{period}" - }, - UpdateExpression=update_expression, - ExpressionAttributeValues=expression_values - ) -``` - -### SystemCostRollup Table - -**CDK definition:** - -```typescript -const systemCostRollupTable = new dynamodb.Table(this, 'SystemCostRollup', { - tableName: `SystemCostRollup-${stage}`, - partitionKey: { name: 'PK', type: dynamodb.AttributeType.STRING }, - sortKey: { name: 'SK', type: dynamodb.AttributeType.STRING }, - billingMode: dynamodb.BillingMode.PAY_PER_REQUEST, - pointInTimeRecovery: true, -}); - -// GSI for time-range queries on rollups -systemCostRollupTable.addGlobalSecondaryIndex({ - indexName: 'DateRangeIndex', - partitionKey: { name: 'GSI1PK', type: dynamodb.AttributeType.STRING }, - sortKey: { name: 'GSI1SK', type: dynamodb.AttributeType.STRING }, - projectionType: dynamodb.ProjectionType.ALL, -}); -``` - ---- - -## Success Criteria - -| Criterion | Target | Measurement | -|-----------|--------|-------------| -| Dashboard load time | <500ms | P95 latency | -| Top N users query | <200ms | P95 latency | -| Table scans | 0 | CloudWatch ConsumedReadCapacity | -| User scale | 10,000+ | Load test | -| Cache hit rate | >80% | Custom metric | -| Rollup freshness | <1 minute | LastUpdated delta | - ---- - -## Conclusion - -This specification provides a scalable, performant admin cost dashboard that: - -1. **Avoids table scans** via GSI-based queries and pre-aggregated rollups -2. **Scales to 10,000+ users** with consistent sub-second response times -3. **Provides rich analytics** beyond just cost (requests, users, models, tiers) -4. **Builds on existing infrastructure** (UserCostSummary table, quota system) -5. **Follows established patterns** (Pydantic models, FastAPI routes, Angular components) - -The phased implementation approach allows incremental delivery while maintaining the performance and scalability requirements from day one. diff --git a/docs/specs/APP_ROLES_RBAC_SPEC.md b/docs/specs/APP_ROLES_RBAC_SPEC.md deleted file mode 100644 index a046e201..00000000 --- a/docs/specs/APP_ROLES_RBAC_SPEC.md +++ /dev/null @@ -1,2053 +0,0 @@ -# Application Roles (AppRole) RBAC System Specification - -## Document Information - -| Field | Value | -|-------|-------| -| Version | 1.0 | -| Status | Draft | -| Created | 2025-01-XX | -| Author | AI Assistant | - ---- - -## Table of Contents - -1. [Executive Summary](#1-executive-summary) -2. [Problem Statement](#2-problem-statement) -3. [Design Goals](#3-design-goals) -4. [System Architecture](#4-system-architecture) -5. [Data Models](#5-data-models) -6. [DynamoDB Schema](#6-dynamodb-schema) -7. [Caching Strategy](#7-caching-strategy) -8. [Authorization Flow](#8-authorization-flow) -9. [Admin Access Control](#9-admin-access-control) -10. [API Design](#10-api-design) -11. [Frontend Admin UI](#11-frontend-admin-ui) -12. [Future Integrations](#12-future-integrations) -13. [Implementation Phases](#13-implementation-phases) -14. [Security Considerations](#14-security-considerations) -15. [Configuration](#15-configuration) - ---- - -## 1. Executive Summary - -This specification defines an **Application Role (AppRole) system** that provides a centralized, flexible way to manage permissions across the AgentCore platform. The system allows administrators to: - -- Create application-level roles that map to one or more JWT roles from the identity provider (Entra ID) -- Grant access to tools, models, and other resources through these AppRoles -- Support single-level role inheritance -- Maintain high-performance authorization through denormalized permissions and aggressive caching - -### Key Features - -- **JWT Role Mapping**: Map multiple identity provider roles to a single AppRole -- **Denormalized Permissions**: Pre-computed effective permissions for O(1) authorization -- **Bidirectional Sync**: Update permissions from either role or resource admin views -- **Single-Level Inheritance**: AppRoles can inherit from one or more parent roles -- **Cache-Friendly**: 5-10 minute TTL with manual invalidation support -- **Default Role Fallback**: Users without mapped roles receive a configurable default role - ---- - -## 2. Problem Statement - -### Current State - -The system currently has implicit, scattered role definitions: - -1. **JWT roles** come from Entra ID (e.g., `Faculty`, `Staff`, `DotNetDevelopers`) -2. **Backend code** references these roles directly in: - - Route protection: `require_roles("Admin", "SuperAdmin", "DotNetDevelopers")` - - Model RBAC: `available_to_roles: ["Faculty", "Developer"]` - - Future tool RBAC: `allowed_roles: ["Faculty", "Researcher"]` - -### Problems - -| Problem | Impact | -|---------|--------| -| No central role registry | Admins can't see what roles exist or their permissions | -| Scattered permissions | To see "Faculty" access, query tools, models, quotas separately | -| No role abstraction | Can't create app roles that combine multiple JWT roles | -| No inheritance | Can't say "PowerUser includes all Faculty permissions" | -| Hard-coded admin access | Changing admin requirements needs code deployment | - ---- - -## 3. Design Goals - -### 3.1 Performance Requirements - -| Operation | Target | Notes | -|-----------|--------|-------| -| Authorization check | < 5ms | O(R) where R = user's roles (typically 1-3) | -| Role lookup (cache hit) | < 1ms | In-memory cache | -| Role lookup (cache miss) | < 50ms | Single DynamoDB read | -| Permission merge | < 2ms | O(P) where P = total permissions | -| Role save (admin) | < 500ms | Includes permission recomputation | - -### 3.2 Design Principles - -1. **Read-heavy optimization**: Authorization checks happen on every request -2. **Write-rarely pattern**: Role definitions change infrequently (daily/weekly) -3. **Denormalization for speed**: Pre-compute effective permissions on save -4. **Cache-friendly**: Role definitions cached aggressively (5-10 min TTL) -5. **Eventual consistency**: Permission changes take effect after cache refresh - ---- - -## 4. System Architecture - -### 4.1 High-Level Architecture - -``` -┌──────────────────────────────────────────────────────────────────────────────┐ -│ Request Flow │ -├──────────────────────────────────────────────────────────────────────────────┤ -│ │ -│ User Request │ -│ │ │ -│ ▼ │ -│ ┌─────────────┐ ┌─────────────────┐ ┌───────────────────────────┐ │ -│ │ JWT Token │───▶│ Extract JWT │───▶│ Cache Lookup │ │ -│ │ (Entra ID) │ │ Roles │ │ (5 min TTL) │ │ -│ └─────────────┘ └─────────────────┘ └───────────┬───────────────┘ │ -│ │ │ -│ Cache Hit ◄─────────────────┤ │ -│ │ │ Cache Miss │ -│ │ ▼ │ -│ │ ┌───────────────────────┐ │ -│ │ │ DynamoDB Query │ │ -│ │ │ (JwtRoleMappingIndex) │ │ -│ │ └───────────┬───────────┘ │ -│ │ │ │ -│ ▼ ▼ │ -│ ┌─────────────────────────────────────────┐ │ -│ │ AppRole[] matching JWT roles │ │ -│ └───────────────────┬─────────────────────┘ │ -│ │ │ -│ ▼ │ -│ ┌─────────────────────────────────────────┐ │ -│ │ Merge effective_permissions │ │ -│ │ - Tools: Union (most permissive) │ │ -│ │ - Models: Union (most permissive) │ │ -│ │ - Quota: Highest priority tier wins │ │ -│ └───────────────────┬─────────────────────┘ │ -│ │ │ -│ ▼ │ -│ ┌─────────────────────────────────────────┐ │ -│ │ UserEffectivePermissions │ │ -│ │ (Cached for subsequent requests) │ │ -│ └───────────────────┬─────────────────────┘ │ -│ │ │ -│ ▼ │ -│ ┌─────────────────────────────────────────┐ │ -│ │ Authorize Request │ │ -│ │ (Check tool/model access) │ │ -│ └─────────────────────────────────────────┘ │ -│ │ -└──────────────────────────────────────────────────────────────────────────────┘ -``` - -### 4.2 Component Overview - -``` -┌─────────────────────────────────────────────────────────────────────────────┐ -│ Backend Components │ -├─────────────────────────────────────────────────────────────────────────────┤ -│ │ -│ ┌──────────────────┐ ┌──────────────────┐ ┌──────────────────┐ │ -│ │ AppRoleService │ │ AppRoleCache │ │ AppRoleRepository│ │ -│ │ │ │ │ │ │ │ -│ │ - resolve_user │◄─▶│ - get/set roles │◄─▶│ - DynamoDB CRUD │ │ -│ │ - check_access │ │ - invalidate │ │ - GSI queries │ │ -│ │ - sync_bidirect │ │ - TTL management │ │ │ │ -│ └──────────────────┘ └──────────────────┘ └──────────────────┘ │ -│ │ │ -│ ▼ │ -│ ┌──────────────────────────────────────────────────────────────────┐ │ -│ │ PermissionResolver │ │ -│ │ │ │ -│ │ - Resolves inheritance (single level) │ │ -│ │ - Computes effective_permissions on role save │ │ -│ │ - Merges permissions for multi-role users │ │ -│ └──────────────────────────────────────────────────────────────────┘ │ -│ │ -└─────────────────────────────────────────────────────────────────────────────┘ -``` - ---- - -## 5. Data Models - -### 5.1 AppRole Model - -```python -from dataclasses import dataclass, field -from typing import List, Optional -from datetime import datetime -from enum import Enum - - -@dataclass -class EffectivePermissions: - """Pre-computed permissions for fast authorization checks.""" - tools: List[str] = field(default_factory=list) # Tool IDs user can access - models: List[str] = field(default_factory=list) # Model IDs user can access - quota_tier: Optional[str] = None # Default quota tier for this role - # FUTURE: features: List[str] = field(default_factory=list) # Feature flags - - -@dataclass -class AppRole: - """ - Application-level role that maps JWT roles to permissions. - - Permissions are denormalized (pre-computed) on save for fast runtime lookups. - """ - # Primary identifiers - role_id: str # Unique identifier (e.g., "power_user", "researcher") - display_name: str # Human-readable name (e.g., "Power User") - description: str # Description for admin UI - - # JWT Mapping - jwt_role_mappings: List[str] # JWT roles that grant this app role - # e.g., ["Faculty", "Researcher", "GraduateStudent"] - - # Inheritance (single level only) - inherits_from: List[str] = field(default_factory=list) # Other app role IDs to inherit from - - # Denormalized permissions (computed on save) - effective_permissions: EffectivePermissions = field(default_factory=EffectivePermissions) - - # Direct permission grants (before inheritance resolution) - # These are used to compute effective_permissions - granted_tools: List[str] = field(default_factory=list) # Directly granted tool IDs - granted_models: List[str] = field(default_factory=list) # Directly granted model IDs - - # Metadata - priority: int = 0 # Higher priority role's quota tier wins in conflicts - is_system_role: bool = False # True for roles that cannot be deleted (e.g., system_admin) - enabled: bool = True # Disabled roles are ignored during resolution - - # Audit fields - created_at: str = "" # ISO 8601 timestamp - updated_at: str = "" # ISO 8601 timestamp - created_by: Optional[str] = None # Admin user_id who created this role - - -@dataclass -class UserEffectivePermissions: - """ - Merged permissions for a specific user based on all their AppRoles. - - This is computed at runtime and cached per-user. - """ - user_id: str - app_roles: List[str] # AppRole IDs that apply to this user - tools: List[str] # Union of all tool permissions - models: List[str] # Union of all model permissions - quota_tier: Optional[str] # Highest priority role's tier - resolved_at: str # ISO 8601 timestamp when this was computed -``` - -### 5.2 Example Role Configurations - -```python -# System Admin Role (hardcoded, cannot be deleted) -system_admin = AppRole( - role_id="system_admin", - display_name="System Administrator", - description="Full access to all system features including RBAC management", - jwt_role_mappings=[], # Configured via ADMIN_JWT_ROLES env var - inherits_from=[], - effective_permissions=EffectivePermissions( - tools=["*"], # Wildcard = all tools - models=["*"], # Wildcard = all models - quota_tier=None, # No quota limits - ), - priority=1000, - is_system_role=True, - enabled=True, -) - -# Default Role (fallback for unmapped JWT roles) -default_role = AppRole( - role_id="default", - display_name="Default User", - description="Minimal access for users without specific role mappings", - jwt_role_mappings=[], # Special: applies when no other roles match - inherits_from=[], - effective_permissions=EffectivePermissions( - tools=["calculator"], # Only basic tools - models=["claude-sonnet"], # Only one model - quota_tier="tier_basic", - ), - priority=0, - is_system_role=True, # Cannot be deleted, but can be modified - enabled=True, -) - -# Power User Role (typical configuration) -power_user = AppRole( - role_id="power_user", - display_name="Power User", - description="Advanced users with access to code execution and research tools", - jwt_role_mappings=["Faculty", "Researcher", "GraduateStudent"], - inherits_from=["basic_user"], # Inherits all basic_user permissions - granted_tools=["code_interpreter", "browser_navigate", "deep_research"], - granted_models=["claude-opus", "gpt-4o"], - effective_permissions=EffectivePermissions( - # Computed on save: basic_user tools + granted_tools - tools=["calculator", "web_search", "code_interpreter", "browser_navigate", "deep_research"], - models=["claude-sonnet", "claude-opus", "gpt-4o"], - quota_tier="tier_faculty", - ), - priority=100, - is_system_role=False, - enabled=True, -) -``` - ---- - -## 6. DynamoDB Schema - -### 6.1 Table: AppRoles - -This table will be created in `infrastructure/lib/app-api-stack.ts`. - -```typescript -// AppRoles Table - Role definitions and permission mappings -const appRolesTable = new dynamodb.Table(this, 'AppRolesTable', { - tableName: getResourceName(config, 'app-roles'), - partitionKey: { - name: 'PK', - type: dynamodb.AttributeType.STRING, - }, - sortKey: { - name: 'SK', - type: dynamodb.AttributeType.STRING, - }, - billingMode: dynamodb.BillingMode.PAY_PER_REQUEST, - pointInTimeRecovery: true, - removalPolicy: config.environment === 'prod' - ? cdk.RemovalPolicy.RETAIN - : cdk.RemovalPolicy.DESTROY, - encryption: dynamodb.TableEncryption.AWS_MANAGED, -}); - -// GSI1: JwtRoleMappingIndex - Fast lookup: "Given JWT role X, what AppRoles apply?" -// This is the critical index for authorization performance -appRolesTable.addGlobalSecondaryIndex({ - indexName: 'JwtRoleMappingIndex', - partitionKey: { - name: 'GSI1PK', - type: dynamodb.AttributeType.STRING, - }, - sortKey: { - name: 'GSI1SK', - type: dynamodb.AttributeType.STRING, - }, - projectionType: dynamodb.ProjectionType.ALL, -}); - -// GSI2: ToolRoleMappingIndex - Reverse lookup: "What AppRoles grant access to tool X?" -// Used for bidirectional sync when updating tool permissions -appRolesTable.addGlobalSecondaryIndex({ - indexName: 'ToolRoleMappingIndex', - partitionKey: { - name: 'GSI2PK', - type: dynamodb.AttributeType.STRING, - }, - sortKey: { - name: 'GSI2SK', - type: dynamodb.AttributeType.STRING, - }, - projectionType: dynamodb.ProjectionType.INCLUDE, - nonKeyAttributes: ['roleId', 'displayName', 'enabled'], -}); - -// GSI3: ModelRoleMappingIndex - Reverse lookup: "What AppRoles grant access to model X?" -// Used for bidirectional sync when updating model permissions -appRolesTable.addGlobalSecondaryIndex({ - indexName: 'ModelRoleMappingIndex', - partitionKey: { - name: 'GSI3PK', - type: dynamodb.AttributeType.STRING, - }, - sortKey: { - name: 'GSI3SK', - type: dynamodb.AttributeType.STRING, - }, - projectionType: dynamodb.ProjectionType.INCLUDE, - nonKeyAttributes: ['roleId', 'displayName', 'enabled'], -}); - -// Store table name in SSM -new ssm.StringParameter(this, 'AppRolesTableNameParameter', { - parameterName: `/${config.projectPrefix}/rbac/app-roles-table-name`, - stringValue: appRolesTable.tableName, - description: 'AppRoles table name for RBAC', - tier: ssm.ParameterTier.STANDARD, -}); - -new ssm.StringParameter(this, 'AppRolesTableArnParameter', { - parameterName: `/${config.projectPrefix}/rbac/app-roles-table-arn`, - stringValue: appRolesTable.tableArn, - description: 'AppRoles table ARN', - tier: ssm.ParameterTier.STANDARD, -}); - -// Grant permissions to ECS task -appRolesTable.grantReadWriteData(taskDefinition.taskRole); - -// Add table name to container environment -environment: { - // ... existing env vars ... - DYNAMODB_APP_ROLES_TABLE_NAME: appRolesTable.tableName, -} -``` - -### 6.2 Access Patterns - -| Pattern | Key Structure | Index | Use Case | -|---------|--------------|-------|----------| -| Get role by ID | `PK=ROLE#{role_id}`, `SK=DEFINITION` | Table | Admin edit role | -| List all roles | `PK=ROLE#*` | Scan (admin only) | Admin list view | -| JWT → AppRoles | `GSI1PK=JWT_ROLE#{jwt_role}`, `GSI1SK=ROLE#{role_id}` | JwtRoleMappingIndex | Authorization check | -| Tool → Roles | `GSI2PK=TOOL#{tool_id}`, `GSI2SK=ROLE#{role_id}` | ToolRoleMappingIndex | Bidirectional sync | -| Model → Roles | `GSI3PK=MODEL#{model_id}`, `GSI3SK=ROLE#{role_id}` | ModelRoleMappingIndex | Bidirectional sync | - -### 6.3 Item Structures - -#### Role Definition Item - -```json -{ - "PK": "ROLE#power_user", - "SK": "DEFINITION", - "roleId": "power_user", - "displayName": "Power User", - "description": "Advanced users with access to code execution and research tools", - "jwtRoleMappings": ["Faculty", "Researcher", "GraduateStudent"], - "inheritsFrom": ["basic_user"], - "grantedTools": ["code_interpreter", "browser_navigate", "deep_research"], - "grantedModels": ["claude-opus", "gpt-4o"], - "effectivePermissions": { - "tools": ["calculator", "web_search", "code_interpreter", "browser_navigate", "deep_research"], - "models": ["claude-sonnet", "claude-opus", "gpt-4o"], - "quotaTier": "tier_faculty" - }, - "priority": 100, - "isSystemRole": false, - "enabled": true, - "createdAt": "2025-01-15T10:30:00Z", - "updatedAt": "2025-01-15T14:22:00Z", - "createdBy": "123456789" -} -``` - -#### JWT Role Mapping Items (for GSI1) - -For each JWT role in `jwtRoleMappings`, create a mapping item: - -```json -{ - "PK": "ROLE#power_user", - "SK": "JWT_MAPPING#Faculty", - "GSI1PK": "JWT_ROLE#Faculty", - "GSI1SK": "ROLE#power_user", - "roleId": "power_user", - "enabled": true -} -``` - -#### Tool Permission Mapping Items (for GSI2) - -For each tool in `grantedTools`, create a mapping item: - -```json -{ - "PK": "ROLE#power_user", - "SK": "TOOL_GRANT#code_interpreter", - "GSI2PK": "TOOL#code_interpreter", - "GSI2SK": "ROLE#power_user", - "roleId": "power_user", - "displayName": "Power User", - "enabled": true -} -``` - -#### Model Permission Mapping Items (for GSI3) - -For each model in `grantedModels`, create a mapping item: - -```json -{ - "PK": "ROLE#power_user", - "SK": "MODEL_GRANT#claude-opus", - "GSI3PK": "MODEL#claude-opus", - "GSI3SK": "ROLE#power_user", - "roleId": "power_user", - "displayName": "Power User", - "enabled": true -} -``` - ---- - -## 7. Caching Strategy - -### 7.1 Cache Layers - -``` -┌─────────────────────────────────────────────────────────────────────────────┐ -│ Cache Architecture │ -├─────────────────────────────────────────────────────────────────────────────┤ -│ │ -│ Layer 1: User Permissions Cache (per-user, short TTL) │ -│ ┌────────────────────────────────────────────────────────────────────────┐ │ -│ │ Key: user:{user_id}:permissions │ │ -│ │ Value: UserEffectivePermissions │ │ -│ │ TTL: 5 minutes │ │ -│ │ Invalidation: On role change affecting user's JWT roles │ │ -│ └────────────────────────────────────────────────────────────────────────┘ │ -│ │ -│ Layer 2: Role Cache (per-role, medium TTL) │ -│ ┌────────────────────────────────────────────────────────────────────────┐ │ -│ │ Key: role:{role_id} │ │ -│ │ Value: AppRole (with effective_permissions) │ │ -│ │ TTL: 10 minutes │ │ -│ │ Invalidation: On role update │ │ -│ └────────────────────────────────────────────────────────────────────────┘ │ -│ │ -│ Layer 3: JWT Mapping Cache (per-JWT-role, medium TTL) │ -│ ┌────────────────────────────────────────────────────────────────────────┐ │ -│ │ Key: jwt_mapping:{jwt_role} │ │ -│ │ Value: List[role_id] │ │ -│ │ TTL: 10 minutes │ │ -│ │ Invalidation: On role JWT mapping change │ │ -│ └────────────────────────────────────────────────────────────────────────┘ │ -│ │ -└─────────────────────────────────────────────────────────────────────────────┘ -``` - -### 7.2 Cache Implementation - -```python -from typing import Dict, Optional, List -from datetime import datetime, timedelta -from dataclasses import dataclass -import asyncio -import logging - -logger = logging.getLogger(__name__) - - -@dataclass -class CacheEntry: - """Cache entry with TTL tracking.""" - value: any - expires_at: datetime - - @property - def is_expired(self) -> bool: - return datetime.utcnow() >= self.expires_at - - -class AppRoleCache: - """ - In-memory cache for AppRole data with TTL support. - - Cache invalidation occurs: - - Automatically when TTL expires - - Manually when admin updates roles (via invalidate methods) - - On application restart (cache is not persistent) - """ - - DEFAULT_USER_TTL = timedelta(minutes=5) - DEFAULT_ROLE_TTL = timedelta(minutes=10) - DEFAULT_MAPPING_TTL = timedelta(minutes=10) - - def __init__(self): - self._user_cache: Dict[str, CacheEntry] = {} - self._role_cache: Dict[str, CacheEntry] = {} - self._jwt_mapping_cache: Dict[str, CacheEntry] = {} - self._lock = asyncio.Lock() - - # User Permissions Cache - - async def get_user_permissions(self, user_id: str) -> Optional[UserEffectivePermissions]: - """Get cached user permissions.""" - entry = self._user_cache.get(f"user:{user_id}") - if entry and not entry.is_expired: - return entry.value - return None - - async def set_user_permissions( - self, - user_id: str, - permissions: UserEffectivePermissions, - ttl: timedelta = None - ): - """Cache user permissions.""" - ttl = ttl or self.DEFAULT_USER_TTL - self._user_cache[f"user:{user_id}"] = CacheEntry( - value=permissions, - expires_at=datetime.utcnow() + ttl - ) - - # Role Cache - - async def get_role(self, role_id: str) -> Optional[AppRole]: - """Get cached role.""" - entry = self._role_cache.get(f"role:{role_id}") - if entry and not entry.is_expired: - return entry.value - return None - - async def set_role(self, role: AppRole, ttl: timedelta = None): - """Cache role.""" - ttl = ttl or self.DEFAULT_ROLE_TTL - self._role_cache[f"role:{role.role_id}"] = CacheEntry( - value=role, - expires_at=datetime.utcnow() + ttl - ) - - # JWT Mapping Cache - - async def get_jwt_mapping(self, jwt_role: str) -> Optional[List[str]]: - """Get cached JWT role → AppRole IDs mapping.""" - entry = self._jwt_mapping_cache.get(f"jwt:{jwt_role}") - if entry and not entry.is_expired: - return entry.value - return None - - async def set_jwt_mapping(self, jwt_role: str, role_ids: List[str], ttl: timedelta = None): - """Cache JWT role mapping.""" - ttl = ttl or self.DEFAULT_MAPPING_TTL - self._jwt_mapping_cache[f"jwt:{jwt_role}"] = CacheEntry( - value=role_ids, - expires_at=datetime.utcnow() + ttl - ) - - # Invalidation - - async def invalidate_user(self, user_id: str): - """Invalidate cache for a specific user.""" - key = f"user:{user_id}" - if key in self._user_cache: - del self._user_cache[key] - logger.debug(f"Invalidated user cache: {user_id}") - - async def invalidate_role(self, role_id: str): - """Invalidate cache for a specific role and all affected users.""" - async with self._lock: - # Remove role cache - role_key = f"role:{role_id}" - if role_key in self._role_cache: - del self._role_cache[role_key] - - # Clear all user caches (they may be affected) - # In production, could be more targeted based on JWT mappings - self._user_cache.clear() - - logger.info(f"Invalidated role cache: {role_id}, cleared all user caches") - - async def invalidate_jwt_mapping(self, jwt_role: str): - """Invalidate JWT mapping cache.""" - key = f"jwt:{jwt_role}" - if key in self._jwt_mapping_cache: - del self._jwt_mapping_cache[key] - - # Clear affected user caches - self._user_cache.clear() - logger.debug(f"Invalidated JWT mapping cache: {jwt_role}") - - async def invalidate_all(self): - """Invalidate all caches (nuclear option).""" - async with self._lock: - self._user_cache.clear() - self._role_cache.clear() - self._jwt_mapping_cache.clear() - logger.info("Invalidated all AppRole caches") - - def get_stats(self) -> Dict: - """Get cache statistics for monitoring.""" - now = datetime.utcnow() - return { - "user_cache_size": len(self._user_cache), - "user_cache_expired": sum(1 for e in self._user_cache.values() if e.is_expired), - "role_cache_size": len(self._role_cache), - "role_cache_expired": sum(1 for e in self._role_cache.values() if e.is_expired), - "jwt_mapping_cache_size": len(self._jwt_mapping_cache), - "jwt_mapping_cache_expired": sum(1 for e in self._jwt_mapping_cache.values() if e.is_expired), - } -``` - -### 7.3 Admin UI Cache Reminder - -When permission changes are made, the admin UI should display: - -``` -⚠️ Changes saved. Updates will take effect within 5-10 minutes as caches refresh. -``` - -This reminder should appear on: -- Role create/update/delete confirmation -- Tool permission changes (when updating allowed_app_roles) -- Model permission changes (when updating allowed_app_roles) - ---- - -## 8. Authorization Flow - -### 8.1 Request Authorization Sequence - -```python -from typing import List, Set -from apis.shared.auth.models import User - - -class AppRoleService: - """ - Service for resolving and checking AppRole-based permissions. - """ - - def __init__(self, repository: AppRoleRepository, cache: AppRoleCache): - self.repository = repository - self.cache = cache - - async def resolve_user_permissions(self, user: User) -> UserEffectivePermissions: - """ - Resolve effective permissions for a user based on their JWT roles. - - This is the main entry point for authorization checks. - - Algorithm: - 1. Check user cache - 2. For each JWT role, find matching AppRoles - 3. Merge permissions (union for tools/models, highest priority for quota) - 4. Cache and return - """ - # Step 1: Check cache - cached = await self.cache.get_user_permissions(user.user_id) - if cached: - return cached - - # Step 2: Get all AppRoles that match user's JWT roles - matching_roles: List[AppRole] = [] - jwt_roles = user.roles or [] - - for jwt_role in jwt_roles: - # Check JWT mapping cache - role_ids = await self.cache.get_jwt_mapping(jwt_role) - - if role_ids is None: - # Cache miss - query database - role_ids = await self.repository.get_roles_for_jwt_role(jwt_role) - await self.cache.set_jwt_mapping(jwt_role, role_ids) - - # Get full role objects - for role_id in role_ids: - role = await self._get_role_with_cache(role_id) - if role and role.enabled: - matching_roles.append(role) - - # Step 3: If no roles matched, use default role - if not matching_roles: - default_role = await self._get_role_with_cache("default") - if default_role and default_role.enabled: - matching_roles = [default_role] - - # Step 4: Merge permissions - permissions = self._merge_permissions(user.user_id, matching_roles) - - # Step 5: Cache and return - await self.cache.set_user_permissions(user.user_id, permissions) - - return permissions - - async def _get_role_with_cache(self, role_id: str) -> Optional[AppRole]: - """Get role from cache or database.""" - cached = await self.cache.get_role(role_id) - if cached: - return cached - - role = await self.repository.get_role(role_id) - if role: - await self.cache.set_role(role) - return role - - def _merge_permissions( - self, - user_id: str, - roles: List[AppRole] - ) -> UserEffectivePermissions: - """ - Merge permissions from multiple AppRoles. - - Merge rules: - - Tools: Union (user gets access to all tools from all roles) - - Models: Union (user gets access to all models from all roles) - - Quota Tier: Highest priority role's tier wins - """ - if not roles: - return UserEffectivePermissions( - user_id=user_id, - app_roles=[], - tools=[], - models=[], - quota_tier=None, - resolved_at=datetime.utcnow().isoformat() + 'Z' - ) - - # Collect all tools and models (union) - all_tools: Set[str] = set() - all_models: Set[str] = set() - - for role in roles: - if role.effective_permissions: - # Handle wildcard - if "*" in role.effective_permissions.tools: - all_tools.add("*") - else: - all_tools.update(role.effective_permissions.tools) - - if "*" in role.effective_permissions.models: - all_models.add("*") - else: - all_models.update(role.effective_permissions.models) - - # Determine quota tier (highest priority wins) - sorted_roles = sorted(roles, key=lambda r: r.priority, reverse=True) - quota_tier = None - for role in sorted_roles: - if role.effective_permissions and role.effective_permissions.quota_tier: - quota_tier = role.effective_permissions.quota_tier - break - - return UserEffectivePermissions( - user_id=user_id, - app_roles=[r.role_id for r in roles], - tools=list(all_tools), - models=list(all_models), - quota_tier=quota_tier, - resolved_at=datetime.utcnow().isoformat() + 'Z' - ) - - async def can_access_tool(self, user: User, tool_id: str) -> bool: - """Check if user can access a specific tool.""" - permissions = await self.resolve_user_permissions(user) - - # Wildcard grants access to all - if "*" in permissions.tools: - return True - - return tool_id in permissions.tools - - async def can_access_model(self, user: User, model_id: str) -> bool: - """Check if user can access a specific model.""" - permissions = await self.resolve_user_permissions(user) - - # Wildcard grants access to all - if "*" in permissions.models: - return True - - return model_id in permissions.models - - async def get_accessible_tools(self, user: User) -> List[str]: - """Get list of tool IDs user can access.""" - permissions = await self.resolve_user_permissions(user) - return permissions.tools - - async def get_accessible_models(self, user: User) -> List[str]: - """Get list of model IDs user can access.""" - permissions = await self.resolve_user_permissions(user) - return permissions.models -``` - -### 8.2 FastAPI Integration - -```python -from fastapi import Depends, HTTPException, status -from typing import Callable - - -def require_tool_access(tool_id: str) -> Callable: - """ - FastAPI dependency that checks if user can access a specific tool. - - Usage: - @router.post("/tools/code-interpreter/execute") - async def execute_code( - user: User = Depends(require_tool_access("code_interpreter")) - ): - # User has been verified to have access - pass - """ - async def checker( - user: User = Depends(get_current_user), - app_role_service: AppRoleService = Depends(get_app_role_service) - ) -> User: - if not await app_role_service.can_access_tool(user, tool_id): - raise HTTPException( - status_code=status.HTTP_403_FORBIDDEN, - detail=f"Access denied to tool: {tool_id}" - ) - return user - - return checker - - -def require_model_access(model_id: str) -> Callable: - """ - FastAPI dependency that checks if user can access a specific model. - """ - async def checker( - user: User = Depends(get_current_user), - app_role_service: AppRoleService = Depends(get_app_role_service) - ) -> User: - if not await app_role_service.can_access_model(user, model_id): - raise HTTPException( - status_code=status.HTTP_403_FORBIDDEN, - detail=f"Access denied to model: {model_id}" - ) - return user - - return checker -``` - ---- - -## 9. Admin Access Control - -### 9.1 Hybrid Admin Role Strategy - -The system uses a **hardcoded super-admin role + configurable JWT roles** approach: - -1. **`system_admin` role**: A hardcoded AppRole that: - - Cannot be deleted or disabled - - Has wildcard access to all tools and models - - Has no quota limits - - Is granted via JWT roles configured in environment variables - -2. **Configuration via Environment**: - -```bash -# Environment variable to specify which JWT roles grant system admin access -ADMIN_JWT_ROLES=["DotNetDevelopers", "AgentCoreAdmin"] -``` - -### 9.2 Implementation - -```python -import os -import json -from typing import List - - -class SystemAdminConfig: - """ - Configuration for system administrator access. - - System admins have full access to all RBAC features and cannot be - locked out by misconfigured roles. - """ - - @staticmethod - def get_admin_jwt_roles() -> List[str]: - """ - Get JWT roles that grant system admin access. - - Configured via ADMIN_JWT_ROLES environment variable. - Defaults to ["DotNetDevelopers"] for backwards compatibility. - """ - roles_json = os.getenv("ADMIN_JWT_ROLES", '["DotNetDevelopers"]') - try: - roles = json.loads(roles_json) - if isinstance(roles, list): - return roles - except json.JSONDecodeError: - pass - return ["DotNetDevelopers"] - - @staticmethod - def is_system_admin(user_roles: List[str]) -> bool: - """Check if user has system admin access via JWT roles.""" - admin_roles = SystemAdminConfig.get_admin_jwt_roles() - return any(role in user_roles for role in admin_roles) - - -# Predefined system admin role (created on startup if not exists) -SYSTEM_ADMIN_ROLE = AppRole( - role_id="system_admin", - display_name="System Administrator", - description="Full access to all system features. This role cannot be deleted.", - jwt_role_mappings=[], # Determined by ADMIN_JWT_ROLES env var at runtime - inherits_from=[], - granted_tools=["*"], - granted_models=["*"], - effective_permissions=EffectivePermissions( - tools=["*"], - models=["*"], - quota_tier=None, # No quota limits - ), - priority=1000, - is_system_role=True, - enabled=True, -) - - -# FastAPI dependency for admin-only endpoints -async def require_system_admin( - user: User = Depends(get_current_user) -) -> User: - """ - Require system administrator access. - - This uses the hardcoded admin check, NOT the AppRole system, - to prevent lockout scenarios. - """ - if not SystemAdminConfig.is_system_admin(user.roles or []): - raise HTTPException( - status_code=status.HTTP_403_FORBIDDEN, - detail="System administrator access required" - ) - return user -``` - -### 9.3 Admin Protection Rules - -| Action | Protection | -|--------|-----------| -| View roles | `require_admin` (existing) | -| Create role | `require_system_admin` | -| Edit role | `require_system_admin` | -| Delete role | `require_system_admin` + not `is_system_role` | -| Edit `system_admin` role | Denied (display_name/description only) | -| Delete `system_admin` role | Denied | -| Edit `default` role | `require_system_admin` | -| Delete `default` role | Denied | - ---- - -## 10. API Design - -### 10.1 Admin API Endpoints - -Base path: `/api/admin/roles` - -| Method | Path | Description | Auth | -|--------|------|-------------|------| -| GET | `/` | List all roles | `require_admin` | -| GET | `/{role_id}` | Get role by ID | `require_admin` | -| POST | `/` | Create new role | `require_system_admin` | -| PATCH | `/{role_id}` | Update role | `require_system_admin` | -| DELETE | `/{role_id}` | Delete role | `require_system_admin` | -| POST | `/{role_id}/sync` | Recompute effective permissions | `require_system_admin` | -| GET | `/jwt-mappings` | List all JWT role mappings | `require_admin` | -| GET | `/cache/stats` | Get cache statistics | `require_system_admin` | -| POST | `/cache/invalidate` | Force cache invalidation | `require_system_admin` | - -### 10.2 Request/Response Models - -```python -from pydantic import BaseModel, Field -from typing import List, Optional - - -# Request Models - -class AppRoleCreate(BaseModel): - """Request body for creating a new AppRole.""" - role_id: str = Field(..., pattern=r"^[a-z][a-z0-9_]{2,49}$") - display_name: str = Field(..., min_length=1, max_length=100) - description: str = Field("", max_length=500) - jwt_role_mappings: List[str] = Field(default_factory=list) - inherits_from: List[str] = Field(default_factory=list) - granted_tools: List[str] = Field(default_factory=list) - granted_models: List[str] = Field(default_factory=list) - priority: int = Field(0, ge=0, le=999) - enabled: bool = True - - # FUTURE: quota_tier: Optional[str] = None - - -class AppRoleUpdate(BaseModel): - """Request body for updating an AppRole (partial update).""" - display_name: Optional[str] = Field(None, min_length=1, max_length=100) - description: Optional[str] = Field(None, max_length=500) - jwt_role_mappings: Optional[List[str]] = None - inherits_from: Optional[List[str]] = None - granted_tools: Optional[List[str]] = None - granted_models: Optional[List[str]] = None - priority: Optional[int] = Field(None, ge=0, le=999) - enabled: Optional[bool] = None - - # FUTURE: quota_tier: Optional[str] = None - - class Config: - # Use camelCase in JSON - populate_by_name = True - - -# Response Models - -class EffectivePermissionsResponse(BaseModel): - """Computed effective permissions.""" - tools: List[str] - models: List[str] - quota_tier: Optional[str] = None - # FUTURE: features: List[str] = [] - - -class AppRoleResponse(BaseModel): - """Response model for an AppRole.""" - role_id: str = Field(..., alias="roleId") - display_name: str = Field(..., alias="displayName") - description: str - jwt_role_mappings: List[str] = Field(..., alias="jwtRoleMappings") - inherits_from: List[str] = Field(..., alias="inheritsFrom") - granted_tools: List[str] = Field(..., alias="grantedTools") - granted_models: List[str] = Field(..., alias="grantedModels") - effective_permissions: EffectivePermissionsResponse = Field(..., alias="effectivePermissions") - priority: int - is_system_role: bool = Field(..., alias="isSystemRole") - enabled: bool - created_at: str = Field(..., alias="createdAt") - updated_at: str = Field(..., alias="updatedAt") - created_by: Optional[str] = Field(None, alias="createdBy") - - class Config: - populate_by_name = True - - -class AppRoleListResponse(BaseModel): - """Response model for listing roles.""" - roles: List[AppRoleResponse] - total: int - - -class CacheStatsResponse(BaseModel): - """Cache statistics response.""" - user_cache_size: int = Field(..., alias="userCacheSize") - user_cache_expired: int = Field(..., alias="userCacheExpired") - role_cache_size: int = Field(..., alias="roleCacheSize") - role_cache_expired: int = Field(..., alias="roleCacheExpired") - jwt_mapping_cache_size: int = Field(..., alias="jwtMappingCacheSize") - jwt_mapping_cache_expired: int = Field(..., alias="jwtMappingCacheExpired") - - class Config: - populate_by_name = True -``` - -### 10.3 Route Implementation - -```python -from fastapi import APIRouter, Depends, HTTPException, status -from typing import List - -router = APIRouter(prefix="/admin/roles", tags=["Admin - Roles"]) - - -@router.get("/", response_model=AppRoleListResponse) -async def list_roles( - enabled_only: bool = False, - admin: User = Depends(require_admin), - service: AppRoleAdminService = Depends(get_app_role_admin_service) -): - """List all application roles.""" - roles = await service.list_roles(enabled_only=enabled_only) - return AppRoleListResponse(roles=roles, total=len(roles)) - - -@router.get("/{role_id}", response_model=AppRoleResponse) -async def get_role( - role_id: str, - admin: User = Depends(require_admin), - service: AppRoleAdminService = Depends(get_app_role_admin_service) -): - """Get a role by ID.""" - role = await service.get_role(role_id) - if not role: - raise HTTPException(status_code=404, detail=f"Role '{role_id}' not found") - return role - - -@router.post("/", response_model=AppRoleResponse, status_code=201) -async def create_role( - role_data: AppRoleCreate, - admin: User = Depends(require_system_admin), - service: AppRoleAdminService = Depends(get_app_role_admin_service) -): - """ - Create a new application role. - - Requires system administrator access. - """ - try: - role = await service.create_role(role_data, admin) - return role - except ValueError as e: - raise HTTPException(status_code=400, detail=str(e)) - - -@router.patch("/{role_id}", response_model=AppRoleResponse) -async def update_role( - role_id: str, - updates: AppRoleUpdate, - admin: User = Depends(require_system_admin), - service: AppRoleAdminService = Depends(get_app_role_admin_service) -): - """ - Update an application role. - - Requires system administrator access. - System roles have limited editability. - """ - try: - role = await service.update_role(role_id, updates, admin) - if not role: - raise HTTPException(status_code=404, detail=f"Role '{role_id}' not found") - return role - except ValueError as e: - raise HTTPException(status_code=400, detail=str(e)) - - -@router.delete("/{role_id}", status_code=204) -async def delete_role( - role_id: str, - admin: User = Depends(require_system_admin), - service: AppRoleAdminService = Depends(get_app_role_admin_service) -): - """ - Delete an application role. - - Requires system administrator access. - System roles cannot be deleted. - """ - try: - success = await service.delete_role(role_id, admin) - if not success: - raise HTTPException(status_code=404, detail=f"Role '{role_id}' not found") - except ValueError as e: - raise HTTPException(status_code=400, detail=str(e)) - - -@router.post("/{role_id}/sync", response_model=AppRoleResponse) -async def sync_role_permissions( - role_id: str, - admin: User = Depends(require_system_admin), - service: AppRoleAdminService = Depends(get_app_role_admin_service) -): - """ - Force recomputation of effective permissions for a role. - - Useful after inheritance changes or to fix data inconsistencies. - """ - role = await service.sync_effective_permissions(role_id, admin) - if not role: - raise HTTPException(status_code=404, detail=f"Role '{role_id}' not found") - return role - - -@router.get("/cache/stats", response_model=CacheStatsResponse) -async def get_cache_stats( - admin: User = Depends(require_system_admin), - cache: AppRoleCache = Depends(get_app_role_cache) -): - """Get cache statistics.""" - return cache.get_stats() - - -@router.post("/cache/invalidate", status_code=204) -async def invalidate_cache( - admin: User = Depends(require_system_admin), - cache: AppRoleCache = Depends(get_app_role_cache) -): - """Force invalidation of all role caches.""" - await cache.invalidate_all() -``` - ---- - -## 11. Frontend Admin UI - -### 11.1 Navigation Structure - -Add new admin section: - -``` -/admin -├── /roles # Role Management (new) -│ ├── / # Role list -│ ├── /new # Create role -│ └── /edit/:roleId # Edit role -├── /manage-models # Existing - add AppRole multi-select -├── /quota # Existing -└── ... -``` - -### 11.2 Role List Page - -**Route**: `/admin/roles` - -**Features**: -- Table listing all roles with columns: - - Display Name - - Role ID - - JWT Mappings (pill badges) - - Status (enabled/disabled) - - Priority - - System Role (badge) - - Actions (Edit, Delete) -- Filter by enabled/disabled -- Search by name/ID -- Sort by priority, name, created date -- "Create Role" button - -**Wireframe**: - -``` -┌─────────────────────────────────────────────────────────────────────────────┐ -│ Application Roles [+ Create Role] │ -├─────────────────────────────────────────────────────────────────────────────┤ -│ ┌─────────────────────────────────────┐ ┌──────────────┐ │ -│ │ 🔍 Search roles... │ │ All Statuses ▼│ │ -│ └─────────────────────────────────────┘ └──────────────┘ │ -├─────────────────────────────────────────────────────────────────────────────┤ -│ Display Name │ Role ID │ JWT Mappings │ Pri │ Status │ -├───────────────────┼──────────────┼───────────────────────┼─────┼───────────┤ -│ System Admin │ system_admin │ DotNetDevelopers │ 1000│ ✓ Enabled │ -│ 🔒 System │ [Edit] │ -├───────────────────┼──────────────┼───────────────────────┼─────┼───────────┤ -│ Power User │ power_user │ Faculty Researcher │ 100 │ ✓ Enabled │ -│ │ │ GraduateStudent │ │ [Edit][🗑]│ -├───────────────────┼──────────────┼───────────────────────┼─────┼───────────┤ -│ Basic User │ basic_user │ Staff All-Employees │ 50 │ ✓ Enabled │ -│ │ │ │ │ [Edit][🗑]│ -├───────────────────┼──────────────┼───────────────────────┼─────┼───────────┤ -│ Default User │ default │ (fallback) │ 0 │ ✓ Enabled │ -│ 🔒 System │ [Edit] │ -└─────────────────────────────────────────────────────────────────────────────┘ -``` - -### 11.3 Role Create/Edit Form - -**Route**: `/admin/roles/new` or `/admin/roles/edit/:roleId` - -**Form Sections**: - -1. **Basic Information** - - Role ID (create only, read-only on edit) - - Display Name - - Description - - Priority (0-999) - - Enabled toggle - -2. **JWT Role Mappings** - - Multi-select chips for known JWT roles - - Option to add custom JWT role names - - Helper text: "Users with these identity provider roles will be granted this app role" - -3. **Inheritance** - - Multi-select dropdown of other AppRoles - - Shows inherited permissions preview - - Helper text: "This role will inherit all permissions from selected roles" - -4. **Tool Permissions** - - Multi-select list of available tools - - Grouped by category (Built-in, Local, MCP) - - Shows both directly granted and inherited tools - -5. **Model Permissions** - - Multi-select list of available models - - Grouped by provider (Bedrock, OpenAI, Gemini) - - Shows both directly granted and inherited models - -6. **Computed Permissions Preview** (read-only) - - Shows final effective_permissions - - Updated in real-time as form changes - -**Wireframe**: - -``` -┌─────────────────────────────────────────────────────────────────────────────┐ -│ ← Back to Roles │ -│ │ -│ Create Application Role │ -├─────────────────────────────────────────────────────────────────────────────┤ -│ │ -│ BASIC INFORMATION │ -│ ┌─────────────────────────────────────────────────────────────────────────┐ │ -│ │ Role ID * │ │ -│ │ ┌─────────────────────────────────────┐ │ │ -│ │ │ power_user │ │ │ -│ │ └─────────────────────────────────────┘ │ │ -│ │ Lowercase letters, numbers, and underscores only │ │ -│ │ │ │ -│ │ Display Name * │ │ -│ │ ┌─────────────────────────────────────┐ │ │ -│ │ │ Power User │ │ │ -│ │ └─────────────────────────────────────┘ │ │ -│ │ │ │ -│ │ Description │ │ -│ │ ┌─────────────────────────────────────────────────────────────────────┐ │ │ -│ │ │ Advanced users with access to code execution and research tools │ │ │ -│ │ └─────────────────────────────────────────────────────────────────────┘ │ │ -│ │ │ │ -│ │ Priority Enabled │ │ -│ │ ┌──────────┐ [✓] │ │ -│ │ │ 100 │ │ │ -│ │ └──────────┘ │ │ -│ │ Higher priority role's quota tier wins when user has multiple roles │ │ -│ └─────────────────────────────────────────────────────────────────────────┘ │ -│ │ -│ JWT ROLE MAPPINGS │ -│ ┌─────────────────────────────────────────────────────────────────────────┐ │ -│ │ Users with these identity provider roles will be granted this app role │ │ -│ │ │ │ -│ │ ┌─────────────────────────────────────────────────────────────────────┐ │ │ -│ │ │ [Faculty ×] [Researcher ×] [GraduateStudent ×] [+ Add role] │ │ │ -│ │ └─────────────────────────────────────────────────────────────────────┘ │ │ -│ │ │ │ -│ │ Available JWT roles: │ │ -│ │ [ ] Admin [ ] Staff [✓] Faculty │ │ -│ │ [✓] Researcher [ ] PSSTUCURTERM [✓] GraduateStudent │ │ -│ │ [ ] DotNetDevelopers [ ] All-Employees [ ] AWS-BoiseStateAI │ │ -│ └─────────────────────────────────────────────────────────────────────────┘ │ -│ │ -│ INHERITS FROM │ -│ ┌─────────────────────────────────────────────────────────────────────────┐ │ -│ │ This role will inherit all permissions from selected roles │ │ -│ │ │ │ -│ │ ┌─────────────────────────────────────────┐ │ │ -│ │ │ Select roles to inherit from... ▼│ │ │ -│ │ └─────────────────────────────────────────┘ │ │ -│ │ │ │ -│ │ Selected: [basic_user ×] │ │ -│ │ │ │ -│ │ Inherited permissions preview: │ │ -│ │ • Tools: calculator, web_search │ │ -│ │ • Models: claude-sonnet │ │ -│ └─────────────────────────────────────────────────────────────────────────┘ │ -│ │ -│ TOOL PERMISSIONS │ -│ ┌─────────────────────────────────────────────────────────────────────────┐ │ -│ │ Grant access to tools (in addition to inherited) │ │ -│ │ │ │ -│ │ Built-in Tools │ │ -│ │ [✓] code_interpreter [✓] browser_navigate [ ] browser_screenshot │ │ -│ │ │ │ -│ │ Local Tools │ │ -│ │ [✓] deep_research [ ] weather [ ] visualization │ │ -│ │ │ │ -│ │ MCP Tools │ │ -│ │ [ ] wikipedia [ ] arxiv [✓] financial_analysis │ │ -│ └─────────────────────────────────────────────────────────────────────────┘ │ -│ │ -│ MODEL PERMISSIONS │ -│ ┌─────────────────────────────────────────────────────────────────────────┐ │ -│ │ Grant access to models (in addition to inherited) │ │ -│ │ │ │ -│ │ AWS Bedrock │ │ -│ │ [ ] claude-sonnet [✓] claude-opus [ ] nova-pro │ │ -│ │ │ │ -│ │ OpenAI │ │ -│ │ [✓] gpt-4o [ ] gpt-4o-mini [ ] o1 │ │ -│ │ │ │ -│ │ Google │ │ -│ │ [ ] gemini-pro [ ] gemini-flash │ │ -│ └─────────────────────────────────────────────────────────────────────────┘ │ -│ │ -│ ┌─────────────────────────────────────────────────────────────────────────┐ │ -│ │ EFFECTIVE PERMISSIONS (computed) │ │ -│ │ │ │ -│ │ Tools: calculator, web_search, code_interpreter, browser_navigate, │ │ -│ │ deep_research, financial_analysis │ │ -│ │ │ │ -│ │ Models: claude-sonnet, claude-opus, gpt-4o │ │ -│ │ │ │ -│ │ Quota Tier: (from inherited basic_user or configure separately) │ │ -│ └─────────────────────────────────────────────────────────────────────────┘ │ -│ │ -│ ⚠️ Changes will take effect within 5-10 minutes as caches refresh. │ -│ │ -│ [Cancel] [Save Role] │ -└─────────────────────────────────────────────────────────────────────────────┘ -``` - -### 11.4 Model Admin Integration - -Update the existing model create/edit form to include AppRole multi-select: - -**Location**: `/admin/manage-models/new` and `/admin/manage-models/edit/:id` - -**Addition**: - -``` -┌─────────────────────────────────────────────────────────────────────────────┐ -│ ACCESS CONTROL │ -│ ┌─────────────────────────────────────────────────────────────────────────┐ │ -│ │ Select which application roles can access this model │ │ -│ │ │ │ -│ │ ┌─────────────────────────────────────────┐ │ │ -│ │ │ Select roles... ▼│ │ │ -│ │ └─────────────────────────────────────────┘ │ │ -│ │ │ │ -│ │ Selected: [power_user ×] [researcher ×] [basic_user ×] │ │ -│ │ │ │ -│ │ ⚠️ Changes will take effect within 5-10 minutes as caches refresh. │ │ -│ └─────────────────────────────────────────────────────────────────────────┘ │ -``` - -### 11.5 Angular Component Example - -```typescript -import { - Component, - ChangeDetectionStrategy, - input, - output, - computed, - inject, - signal -} from '@angular/core'; -import { CommonModule } from '@angular/common'; -import { ReactiveFormsModule, FormBuilder, Validators } from '@angular/forms'; -import { NgIcon, provideIcons } from '@ng-icons/core'; -import { heroShieldCheck, heroUsers, heroCog } from '@ng-icons/heroicons/outline'; -import { AppRoleService } from './services/app-role.service'; -import { AppRole, AppRoleCreate } from './models/app-role.model'; - -@Component({ - selector: 'app-role-form', - changeDetection: ChangeDetectionStrategy.OnPush, - imports: [CommonModule, ReactiveFormsModule, NgIcon], - providers: [provideIcons({ heroShieldCheck, heroUsers, heroCog })], - template: ` -
- -
-

Basic Information

- -
-
- - - @if (!isEdit()) { -

- Lowercase letters, numbers, and underscores only -

- } -
- -
- - -
- -
-
- - -
- -
- - -
-
-
-
- - -
-

- - JWT Role Mappings -

- -

- Users with these identity provider roles will be granted this app role -

- -
- @for (role of selectedJwtRoles(); track role) { - - {{ role }} - - - } -
- -
- @for (role of availableJwtRoles(); track role) { - - } -
-
- - -
-

- - Effective Permissions (computed) -

- -
-

- Tools: - {{ effectivePermissions()?.tools?.join(', ') || 'None' }} -

-

- Models: - {{ effectivePermissions()?.models?.join(', ') || 'None' }} -

-
-
- - -
-

- Changes will take effect within 5-10 minutes as caches refresh. -

-
- - -
- - -
-
- ` -}) -export class RoleFormComponent { - // Inputs - role = input(null); - isEdit = computed(() => !!this.role()); - - // Outputs - saved = output(); - cancelled = output(); - - // State - saving = signal(false); - selectedJwtRoles = signal([]); - - // Services - private fb = inject(FormBuilder); - private roleService = inject(AppRoleService); - - // Form - form = this.fb.group({ - roleId: ['', [Validators.required, Validators.pattern(/^[a-z][a-z0-9_]{2,49}$/)]], - displayName: ['', [Validators.required, Validators.maxLength(100)]], - description: ['', Validators.maxLength(500)], - priority: [0, [Validators.min(0), Validators.max(999)]], - enabled: [true], - }); - - // Available JWT roles (would come from service in real implementation) - availableJwtRoles = signal([ - 'Admin', 'Faculty', 'Staff', 'Researcher', - 'PSSTUCURTERM', 'GraduateStudent', 'DotNetDevelopers', - 'All-Employees Entra Sync', 'AWS-BoiseStateAI' - ]); - - // Computed effective permissions - effectivePermissions = computed(() => { - // In real implementation, this would call the service to compute - return this.role()?.effectivePermissions; - }); - - toggleJwtRole(role: string): void { - this.selectedJwtRoles.update(roles => { - if (roles.includes(role)) { - return roles.filter(r => r !== role); - } - return [...roles, role]; - }); - } - - removeJwtRole(role: string): void { - this.selectedJwtRoles.update(roles => roles.filter(r => r !== role)); - } - - onSubmit(): void { - if (this.form.valid) { - const formValue = this.form.getRawValue(); - this.saved.emit({ - ...formValue, - jwtRoleMappings: this.selectedJwtRoles(), - inheritsFrom: [], - grantedTools: [], - grantedModels: [], - } as AppRoleCreate); - } - } -} -``` - ---- - -## 12. Future Integrations - -This section documents how the AppRole system will integrate with other systems in future phases. - -### 12.1 Tool RBAC Integration - - - -**Planned Integration Points**: - -1. **Tool Definition Enhancement**: - ```python - @dataclass - class ToolDefinition: - tool_id: str - name: str - description: str - allowed_app_roles: List[str] = field(default_factory=list) # New field - ``` - -2. **Agent Tool Filtering** (`agent.py:277-318`): - ```python - async def _filter_tools_for_user(self, user: User, tools: List[Tool]) -> List[Tool]: - """Filter tools based on user's AppRole permissions.""" - permissions = await self.app_role_service.resolve_user_permissions(user) - - if "*" in permissions.tools: - return tools # Wildcard = all tools - - return [t for t in tools if t.tool_id in permissions.tools] - ``` - -### 12.2 Model RBAC Integration - - - -**Current State**: `ManagedModels` already has `available_to_roles: List[str]` which stores JWT role names. - -**Planned Migration**: -1. Add `allowed_app_roles: List[str]` field to ManagedModel -2. Deprecate `available_to_roles` (keep for backwards compat during transition) -3. Update model access check to use AppRoleService - -### 12.3 Quota Integration - - - -**Planned Priority Order**: -1. Direct user assignment (highest) -2. **AppRole** ← New -3. JWT role -4. Email pattern -5. Email domain -6. Default tier (lowest) - ---- - -## 13. Implementation Phases - -### Phase 1: Core AppRole System (This Spec) - -**Duration**: ~2-3 weeks - -**Deliverables**: -1. DynamoDB table creation in CDK -2. AppRole data models and repository -3. Caching layer implementation -4. AppRoleService with permission resolution -5. Admin API endpoints -6. Frontend role management UI -7. System admin protection -8. Default role fallback - -**Out of Scope**: -- Tool RBAC integration -- Model RBAC integration (keep existing `available_to_roles`) -- Quota integration - -### Phase 2: Model Integration - -**Dependencies**: Phase 1 complete - -**Deliverables**: -1. Add `allowed_app_roles` to ManagedModel -2. Update model service to use AppRoleService -3. Update model admin UI with AppRole multi-select -4. Bidirectional sync for model-role relationships -5. Deprecation path for `available_to_roles` - -### Phase 3: Tool RBAC Integration - -**Dependencies**: Phase 1 complete - -**Deliverables**: -1. Tool definition enhancement with `allowed_app_roles` -2. Agent tool filtering via AppRoleService -3. Tool admin UI (if applicable) -4. Bidirectional sync for tool-role relationships - -### Phase 4: Quota Integration - -**Dependencies**: Phase 1 complete - -**Deliverables**: -1. Add "app_role" assignment type -2. Update quota resolver with AppRole priority -3. Update quota assignment UI -4. Migration of existing JWT role assignments (optional) - ---- - -## 14. Security Considerations - -### 14.1 Access Control - -| Risk | Mitigation | -|------|-----------| -| Privilege escalation via role creation | Only system admins can create/edit roles | -| Lockout via role misconfiguration | System admin role cannot be disabled/deleted | -| JWT role spoofing | JWT validation happens before role resolution | -| Cache poisoning | Cache is in-memory, not externally accessible | - -### 14.2 Audit Logging - -All role modifications should be logged: - -```python -logger.info( - f"AppRole modified", - extra={ - "event": "app_role_modified", - "action": "create|update|delete", - "role_id": role_id, - "admin_user_id": admin.user_id, - "admin_email": admin.email, - "changes": changes_dict, - "timestamp": datetime.utcnow().isoformat() - } -) -``` - -### 14.3 Input Validation - -- Role IDs: Alphanumeric + underscore, 3-50 chars, lowercase -- JWT role names: Non-empty strings, max 100 chars -- Tool/Model IDs: Validated against existing entities -- Priority: Integer 0-999 - ---- - -## 15. Configuration - -### 15.1 Environment Variables - -```bash -# Required for DynamoDB table -DYNAMODB_APP_ROLES_TABLE_NAME=bsu-agentcore-app-roles - -# Admin access configuration -ADMIN_JWT_ROLES=["DotNetDevelopers", "AgentCoreAdmin"] - -# Cache configuration (optional, defaults shown) -APP_ROLE_USER_CACHE_TTL_MINUTES=5 -APP_ROLE_ROLE_CACHE_TTL_MINUTES=10 -APP_ROLE_MAPPING_CACHE_TTL_MINUTES=10 -``` - -### 15.2 CDK Configuration - -Add to `infrastructure/lib/app-api-stack.ts`: - -```typescript -// Add to container environment -environment: { - // ... existing env vars ... - DYNAMODB_APP_ROLES_TABLE_NAME: appRolesTable.tableName, - ADMIN_JWT_ROLES: JSON.stringify(config.appApi.adminJwtRoles || ["DotNetDevelopers"]), -} -``` - -### 15.3 README Documentation - -Add to project README: - -```markdown -## Admin Access Configuration - -System administrator access is controlled via the `ADMIN_JWT_ROLES` environment variable. -Users with any of the specified JWT roles from your identity provider will have full -access to the RBAC admin features. - -### Default Configuration - -```bash -ADMIN_JWT_ROLES=["DotNetDevelopers"] -``` - -### Adding Additional Admin Roles - -To grant admin access to additional JWT roles: - -```bash -ADMIN_JWT_ROLES=["DotNetDevelopers", "AgentCoreAdmin", "ITSecurityTeam"] -``` - -### Important Notes - -1. The `system_admin` AppRole is protected and cannot be deleted -2. Admin access is determined by JWT roles, not by the AppRole system itself (prevents lockout) -3. Changes to `ADMIN_JWT_ROLES` require application restart -``` - ---- - -## Appendix A: Migration Checklist - -When implementing this spec, use this checklist: - -- [ ] Create DynamoDB table in `app-api-stack.ts` -- [ ] Add table name to container environment variables -- [ ] Create `backend/src/apis/shared/rbac/` directory structure -- [ ] Implement `AppRole` data models -- [ ] Implement `AppRoleRepository` -- [ ] Implement `AppRoleCache` -- [ ] Implement `AppRoleService` -- [ ] Implement `AppRoleAdminService` -- [ ] Add admin routes to FastAPI -- [ ] Create `require_system_admin` dependency -- [ ] Seed `system_admin` and `default` roles on startup -- [ ] Create Angular `app-role.service.ts` -- [ ] Create Angular role list component -- [ ] Create Angular role form component -- [ ] Add routes to `app.routes.ts` -- [ ] Add admin dashboard card for roles -- [ ] Update README with admin configuration -- [ ] Write unit tests for repository -- [ ] Write unit tests for service -- [ ] Write integration tests for API - ---- - -## Appendix B: Glossary - -| Term | Definition | -|------|-----------| -| **AppRole** | Application-level role that maps JWT roles to permissions | -| **JWT Role** | Role claim from identity provider (Entra ID) token | -| **Effective Permissions** | Pre-computed, denormalized permissions for fast authorization | -| **System Role** | AppRole that cannot be deleted (e.g., `system_admin`, `default`) | -| **Bidirectional Sync** | Keeping role→resource and resource→role mappings in sync | -| **Cache TTL** | Time-to-live for cached data before automatic refresh | - ---- - -*End of Specification* diff --git a/docs/specs/CONTEXT_SUMMARIZATION_SPEC.md b/docs/specs/CONTEXT_SUMMARIZATION_SPEC.md deleted file mode 100644 index b541eef4..00000000 --- a/docs/specs/CONTEXT_SUMMARIZATION_SPEC.md +++ /dev/null @@ -1,566 +0,0 @@ -# Context Summarization Implementation Spec - -## Overview - -Implement intelligent conversation context management using Strands Agents' `SummarizingConversationManager`. This feature automatically summarizes older messages when context limits are approached, preserving essential information while reducing token usage and costs. - -## Goals - -1. **Automatic Context Compression**: Reduce context size when token limits are reached -2. **Cost Optimization**: Use Nova Micro as a dedicated, cost-effective summarization model -3. **User Transparency**: Notify users when summarization occurs via SSE events and UI indicators -4. **Configurability**: Allow administrators to tune summarization behavior via environment variables - -## Technical Design - -### 1. Backend Implementation - -#### 1.1 Environment Variables - -Add the following environment variables to configure summarization: - -| Variable | Type | Default | Description | -|----------|------|---------|-------------| -| `SUMMARIZATION_ENABLED` | bool | `true` | Feature toggle for context summarization | -| `SUMMARIZATION_MODEL_ID` | str | `us.amazon.nova-micro-v1:0` | Model ID for the summarization agent | -| `SUMMARIZATION_SUMMARY_RATIO` | float | `0.3` | Percentage of messages to summarize (0.1-0.8) | -| `SUMMARIZATION_PRESERVE_RECENT` | int | `10` | Minimum recent messages to always preserve | - -#### 1.2 Summarization Agent Configuration - -**File:** `backend/src/agents/main_agent/core/summarization_config.py` (new) - -```python -from dataclasses import dataclass -from typing import Optional -import os - -@dataclass -class SummarizationConfig: - """Configuration for context summarization""" - enabled: bool = True - model_id: str = "us.amazon.nova-micro-v1:0" - summary_ratio: float = 0.3 - preserve_recent_messages: int = 10 - - @classmethod - def from_env(cls) -> "SummarizationConfig": - """Load configuration from environment variables""" - return cls( - enabled=os.getenv("SUMMARIZATION_ENABLED", "true").lower() == "true", - model_id=os.getenv("SUMMARIZATION_MODEL_ID", "us.amazon.nova-micro-v1:0"), - summary_ratio=float(os.getenv("SUMMARIZATION_SUMMARY_RATIO", "0.3")), - preserve_recent_messages=int(os.getenv("SUMMARIZATION_PRESERVE_RECENT", "10")) - ) -``` - -#### 1.3 Agent Factory Integration - -**File:** `backend/src/agents/main_agent/core/agent_factory.py` - -Modify `create_agent()` to use `SummarizingConversationManager`: - -```python -from strands.agent.conversation_manager import SummarizingConversationManager -from strands import Agent -from .summarization_config import SummarizationConfig - -def create_agent(...) -> Agent: - summarization_config = SummarizationConfig.from_env() - - conversation_manager = None - if summarization_config.enabled: - # Create dedicated summarization agent with Nova Micro - summarization_agent = Agent( - model_id=summarization_config.model_id, - # Minimal config - no tools needed for summarization - ) - - conversation_manager = SummarizingConversationManager( - summary_ratio=summarization_config.summary_ratio, - preserve_recent_messages=summarization_config.preserve_recent_messages, - summarization_agent=summarization_agent - ) - - return Agent( - model_id=model_config.model_id, - conversation_manager=conversation_manager, - # ... existing config - ) -``` - -#### 1.4 Summarization Event Detection - -The `SummarizingConversationManager` modifies the message history when summarization occurs. We need to detect this and emit events. - -**Approach:** Hook into the conversation manager or compare message counts before/after agent invocation. - -**File:** `backend/src/agents/main_agent/streaming/stream_coordinator.py` - -Add summarization detection logic: - -```python -async def detect_summarization( - messages_before: list, - messages_after: list, - session_id: str, - user_id: str -) -> Optional[SummarizationEvent]: - """ - Detect if summarization occurred by comparing message lists. - - Returns SummarizationEvent if summarization was detected, None otherwise. - """ - # Check for summary message (first assistant message with summary content) - # SummarizingConversationManager replaces old messages with a summary - - if len(messages_after) < len(messages_before): - # Messages were compressed - tokens_before = estimate_tokens(messages_before) - tokens_after = estimate_tokens(messages_after) - - # Find the summary text (typically first message after summarization) - summary_text = extract_summary_text(messages_after) - - return SummarizationEvent( - session_id=session_id, - user_id=user_id, - messages_before_count=len(messages_before), - messages_after_count=len(messages_after), - tokens_before=tokens_before, - tokens_after=tokens_after, - tokens_removed=tokens_before - tokens_after, - summary_text=summary_text, - timestamp=datetime.now(timezone.utc).isoformat() - ) - - return None -``` - -#### 1.4 SSE Event Model - -**File:** `backend/src/apis/shared/summarization.py` (new) - -```python -from pydantic import BaseModel, Field -from typing import Optional -import json - -class ContextSummarizedEvent(BaseModel): - """SSE event emitted when context summarization occurs""" - type: str = "context_summarized" - session_id: str = Field(..., alias="sessionId") - tokens_before: int = Field(..., alias="tokensBefore", description="Token count before summarization") - tokens_after: int = Field(..., alias="tokensAfter", description="Token count after summarization") - tokens_removed: int = Field(..., alias="tokensRemoved", description="Tokens removed by summarization") - messages_summarized: int = Field(..., alias="messagesSummarized", description="Number of messages summarized") - context_compression_ratio: float = Field(..., alias="contextCompressionRatio", description="Compression ratio (0-1)") - message: str = Field(..., description="User-friendly message") - - def to_sse_format(self) -> str: - """Format as Server-Sent Event""" - return f"event: context_summarized\ndata: {json.dumps(self.model_dump(by_alias=True))}\n\n" - - @classmethod - def create( - cls, - session_id: str, - tokens_before: int, - tokens_after: int, - messages_summarized: int - ) -> "ContextSummarizedEvent": - """Factory method with computed fields""" - tokens_removed = tokens_before - tokens_after - compression_ratio = tokens_removed / tokens_before if tokens_before > 0 else 0 - - return cls( - session_id=session_id, - tokens_before=tokens_before, - tokens_after=tokens_after, - tokens_removed=tokens_removed, - messages_summarized=messages_summarized, - context_compression_ratio=compression_ratio, - message=f"Context optimized: {tokens_removed:,} tokens compressed" - ) -``` - -#### 1.5 Chat Routes Integration - -**File:** `backend/src/apis/app_api/chat/routes.py` - -Emit the summarization event during streaming: - -```python -# After agent response, check for summarization -summarization_event = await detect_summarization( - messages_before=messages_snapshot, - messages_after=agent.messages, - session_id=session_id, - user_id=user_id -) - -if summarization_event: - # Emit SSE event - yield summarization_event.to_sse_format() -``` - -### 2. Frontend Implementation - -#### 2.1 SSE Event Handler - -**File:** `frontend/ai.client/src/app/session/services/chat/stream-parser.service.ts` - -Add handler for the new event type: - -```typescript -// Add to handleEvent switch statement -case 'context_summarized': - this.handleContextSummarized(data); - break; - -// Add handler method -private handleContextSummarized(data: unknown): void { - if (!data || typeof data !== 'object') return; - - const event = data as Partial; - - if (event.type !== 'context_summarized' || - typeof event.tokensBefore !== 'number' || - typeof event.tokensRemoved !== 'number') { - console.warn('Invalid context_summarized event:', data); - return; - } - - this.contextSummarizationService.setContextSummarized(event as ContextSummarizedEvent); -} -``` - -#### 2.2 Context Summarization Service - -**File:** `frontend/ai.client/src/app/services/summarization/context-summarization.service.ts` (new) - -```typescript -import { Injectable, signal, computed } from '@angular/core'; - -export interface ContextSummarizedEvent { - type: 'context_summarized'; - sessionId: string; - tokensBefore: number; - tokensAfter: number; - tokensRemoved: number; - messagesSummarized: number; - contextCompressionRatio: number; - message: string; -} - -@Injectable({ providedIn: 'root' }) -export class ContextSummarizationService { - // Signal for current summarization event - private contextSummarizedSignal = signal(null); - - // Signal for sessions that have been summarized (persists across messages) - private summarizedSessionsSignal = signal>(new Set()); - - // Public readonly signals - readonly contextSummarized = this.contextSummarizedSignal.asReadonly(); - readonly summarizedSessions = this.summarizedSessionsSignal.asReadonly(); - - // Computed: Should show the inline notification banner - readonly showNotificationBanner = computed(() => { - return this.contextSummarizedSignal() !== null; - }); - - // Computed: Check if a specific session has been summarized - readonly isSessionSummarized = (sessionId: string) => { - return this.summarizedSessionsSignal().has(sessionId); - }; - - // Computed: Formatted message for display - readonly displayMessage = computed(() => { - const event = this.contextSummarizedSignal(); - if (!event) return ''; - - const tokensK = Math.round(event.tokensRemoved / 1000); - const percent = Math.round(event.contextCompressionRatio * 100); - - if (tokensK >= 1) { - return `Context optimized: ~${tokensK}K tokens compressed (${percent}% reduction)`; - } - return `Context optimized: ${event.tokensRemoved.toLocaleString()} tokens compressed`; - }); - - /** - * Set a new context summarized event - */ - setContextSummarized(event: ContextSummarizedEvent): void { - this.contextSummarizedSignal.set(event); - - // Track that this session has been summarized - this.summarizedSessionsSignal.update(sessions => { - const updated = new Set(sessions); - updated.add(event.sessionId); - return updated; - }); - } - - /** - * Dismiss the notification banner (but keep session marked as summarized) - */ - dismissBanner(): void { - this.contextSummarizedSignal.set(null); - } - - /** - * Clear summarization state for a session (e.g., when starting new session) - */ - clearSession(sessionId: string): void { - this.summarizedSessionsSignal.update(sessions => { - const updated = new Set(sessions); - updated.delete(sessionId); - return updated; - }); - - // Also clear banner if it's for this session - if (this.contextSummarizedSignal()?.sessionId === sessionId) { - this.contextSummarizedSignal.set(null); - } - } -} -``` - -#### 2.3 UI Component - Inline Banner - -**File:** `frontend/ai.client/src/app/components/context-summarization-banner/context-summarization-banner.component.ts` (new) - -Following the pattern from `quota-warning-banner.component.ts`: - -```typescript -import { Component, inject, ChangeDetectionStrategy } from '@angular/core'; -import { NgIconComponent, provideIcons } from '@ng-icon/core'; -import { heroSparkles, heroXMark } from '@ng-icons/heroicons/outline'; -import { ContextSummarizationService } from '../../services/summarization/context-summarization.service'; - -@Component({ - selector: 'app-context-summarization-banner', - standalone: true, - imports: [NgIconComponent], - viewProviders: [provideIcons({ heroSparkles, heroXMark })], - changeDetection: ChangeDetectionStrategy.OnPush, - template: ` - @if (service.showNotificationBanner()) { -
- - {{ service.displayMessage() }} - -
- } - ` -}) -export class ContextSummarizationBannerComponent { - protected service = inject(ContextSummarizationService); - - dismiss(event: Event): void { - event.stopPropagation(); - this.service.dismissBanner(); - } -} -``` - -#### 2.4 Session Badge Indicator - -Add a small indicator to sessions that have been summarized. - -**File:** Modify session list item component - -```typescript -// In session list item template -@if (contextSummarizationService.isSessionSummarized(session.sessionId)) { - - - -} -``` - -#### 2.5 Types Definition - -**File:** `frontend/ai.client/src/app/session/services/chat/types.ts` - -Add the event type: - -```typescript -export interface ContextSummarizedEvent { - type: 'context_summarized'; - sessionId: string; - tokensBefore: number; - tokensAfter: number; - tokensRemoved: number; - messagesSummarized: number; - contextCompressionRatio: number; - message: string; -} -``` - -### 3. Infrastructure Changes - -#### 3.1 CDK Configuration - -**File:** `infrastructure/lib/app-api-stack.ts` - -Add environment variables to the ECS task definition: - -```typescript -// In container definition environment -SUMMARIZATION_ENABLED: config.appApi.summarizationEnabled?.toString() ?? 'true', -SUMMARIZATION_MODEL_ID: config.appApi.summarizationModelId ?? 'us.amazon.nova-micro-v1:0', -SUMMARIZATION_SUMMARY_RATIO: config.appApi.summarizationSummaryRatio?.toString() ?? '0.3', -SUMMARIZATION_PRESERVE_RECENT: config.appApi.summarizationPreserveRecent?.toString() ?? '10', -``` - -#### 3.2 Config Schema - -**File:** `infrastructure/lib/config.ts` - -Add configuration options: - -```typescript -interface AppApiConfig { - // ... existing fields - summarizationEnabled?: boolean; - summarizationModelId?: string; - summarizationSummaryRatio?: number; - summarizationPreserveRecent?: number; -} -``` - -## Data Flow - -``` -User sends message - │ - ▼ -Agent processes request - │ - ▼ -SummarizingConversationManager checks context size - │ - ├─ Context OK ─────────────────────────────────► Continue normally - │ - └─ Context exceeds limit - │ - ▼ - Summarization Agent (Nova Micro) - creates summary of old messages - │ - ▼ - Old messages replaced with summary - │ - ▼ - detect_summarization() compares before/after - │ - ▼ - Emit SSE event: context_summarized - │ - ▼ - Frontend: ContextSummarizationService - └─► Show inline banner - └─► Mark session as summarized -``` - -## SSE Event Format - -```json -{ - "type": "context_summarized", - "sessionId": "abc123", - "tokensBefore": 45000, - "tokensAfter": 32000, - "tokensRemoved": 13000, - "messagesSummarized": 8, - "contextCompressionRatio": 0.29, - "message": "Context optimized: 13,000 tokens compressed" -} -``` - -## Testing Strategy - -### Unit Tests - -1. `SummarizationConfig` - Environment variable parsing -2. `ContextSummarizedEvent` - SSE formatting, factory method -3. `detect_summarization()` - Summarization detection logic -4. `ContextSummarizationService` - Signal state management - -### Integration Tests - -1. End-to-end summarization flow with mock agent -2. SSE event emission and parsing -3. UI banner display and dismissal - -### Manual Testing - -1. Start a long conversation that exceeds context limits -2. Verify summarization event appears in SSE stream -3. Verify UI banner displays with correct message -4. Verify session shows summarization indicator - -## Rollout Plan - -1. **Phase 1**: Backend implementation with feature flag disabled - - Add environment variables - - Implement summarization config - - Add SSE event model - -2. **Phase 2**: Frontend implementation - - Add SSE event handler - - Create service and components - - Add session indicators - -3. **Phase 3**: Integration and testing - - End-to-end testing - - Performance validation - - Cost analysis with Nova Micro - -4. **Phase 4**: Gradual rollout - - Enable for internal users first - - Monitor summarization frequency and costs - - Full rollout with `SUMMARIZATION_ENABLED=true` - -## Success Metrics - -1. **Context Compression**: Average tokens removed per summarization event -2. **Cost Savings**: Reduction in overall token costs from context compression -3. **Summarization Quality**: User feedback on conversation coherence post-summarization -4. **System Reliability**: Error rate for summarization operations - -## Open Questions - -1. Should there be a manual trigger option for users to request summarization? -2. What should happen if the summarization agent fails? (Current: fail gracefully, continue without summarization) - -## Future Enhancements - -1. **Audit Storage**: If needed for debugging or compliance, add DynamoDB persistence for summarization events with schema `SUM#{timestamp}#{session_id}` - -## References - -- [Strands Agents - Conversation Management](https://strandsagents.com/latest/documentation/docs/user-guide/concepts/agents/conversation-management/) -- [Strands Agents - Agent API Reference](https://strandsagents.com/latest/documentation/docs/api-reference/agent/) -- [AWS Nova Micro Pricing](https://aws.amazon.com/bedrock/pricing/) diff --git a/docs/specs/FILE_MULTIMODAL_CHAT_SPEC.md b/docs/specs/FILE_MULTIMODAL_CHAT_SPEC.md deleted file mode 100644 index b51aa34c..00000000 --- a/docs/specs/FILE_MULTIMODAL_CHAT_SPEC.md +++ /dev/null @@ -1,808 +0,0 @@ -# Implementation Plan: Multimodal Document/Image Support in Chat Flow - -## Overview - -This plan details the implementation of multimodal support (documents and images) for the chat flow, enabling users to attach files to messages and have the AI agent analyze them. - -## Current State Analysis - -### What Already Exists - -| Component | Status | Location | -|-----------|--------|----------| -| File Upload Service (Frontend) | Complete | `frontend/.../services/file-upload/file-upload.service.ts` | -| Pre-signed URL Flow (Backend) | Complete | `backend/.../apis/app_api/files/` | -| S3 Storage & DynamoDB Metadata | Complete | `backend/.../apis/app_api/files/repository.py` | -| Multimodal Prompt Builder | Complete | `backend/.../agents/main_agent/multimodal/prompt_builder.py` | -| Image/Document Handlers | Complete | `backend/.../agents/main_agent/multimodal/` | -| Chat Input UI (Drag/Drop) | Complete | `frontend/.../session/components/chat-input/` | -| `InvocationRequest.files` field | Exists | `backend/.../apis/inference_api/chat/models.py` | - -### Missing Integration Points - -1. **Backend**: Chat endpoints don't fetch file content from S3 using `file_upload_ids` -2. **Frontend**: `file_upload_ids` are passed to backend but not processed -3. **Backend**: `/invocations` endpoint passes `files` to agent but expects base64-encoded `FileContent`, not upload IDs -4. **Images**: File upload service only allows documents (PDF, DOCX, etc.) - images not supported -5. **Session Load**: File metadata not restored when loading historical sessions (solved by Step 11) - ---- - -## Implementation Steps - -### Step 1: Extend Allowed File Types for Images - -**Goal**: Allow image uploads (PNG, JPEG, GIF, WebP) in addition to documents. - -**Files to Modify**: - -1. **Backend**: `backend/src/apis/app_api/files/models.py` - - Add image MIME types to `ALLOWED_MIME_TYPES`: - ```python - ALLOWED_MIME_TYPES = { - # Existing documents... - # Add images: - "image/png": "png", - "image/jpeg": "jpeg", - "image/gif": "gif", - "image/webp": "webp", - } - ``` - - Add image extensions to `ALLOWED_EXTENSIONS`: - ```python - ALLOWED_EXTENSIONS = { - # Existing... - ".png": "image/png", - ".jpg": "image/jpeg", - ".jpeg": "image/jpeg", - ".gif": "image/gif", - ".webp": "image/webp", - } - ``` - -2. **Frontend**: `frontend/ai.client/src/app/services/file-upload/file-upload.service.ts` - - Add image MIME types to `ALLOWED_MIME_TYPES` - - Add image extensions to `ALLOWED_EXTENSIONS` - ---- - -### Step 2: Create File Resolver Service (Backend) - -**Goal**: Fetch file content from S3 given upload IDs and convert to `FileContent` objects. - -**New File**: `backend/src/apis/app_api/files/file_resolver.py` - -```python -""" -File Resolver Service - -Resolves file upload IDs to FileContent objects with base64-encoded bytes. -Used by chat endpoints to fetch files from S3 before passing to agent. -""" - -import base64 -import logging -from typing import List, Optional - -import boto3 -from botocore.exceptions import ClientError - -from apis.inference_api.chat.models import FileContent -from apis.app_api.files.service import get_file_upload_service -from apis.app_api.files.models import FileStatus - -logger = logging.getLogger(__name__) - - -class FileResolverError(Exception): - """Error resolving file content.""" - pass - - -class FileResolver: - """ - Resolves file upload IDs to FileContent objects. - - Fetches file metadata from DynamoDB and content from S3, - then encodes as base64 for the agent. - """ - - def __init__(self, s3_client=None): - self._s3_client = s3_client or boto3.client("s3") - self._file_service = get_file_upload_service() - - async def resolve_files( - self, - user_id: str, - upload_ids: List[str], - max_files: int = 5 - ) -> List[FileContent]: - """ - Resolve upload IDs to FileContent objects. - - Args: - user_id: Owner user ID (for authorization) - upload_ids: List of upload IDs to resolve - max_files: Maximum files to process (Bedrock limit is 5) - - Returns: - List of FileContent objects with base64-encoded bytes - - Raises: - FileResolverError: If file not found or access denied - """ - resolved_files = [] - - for upload_id in upload_ids[:max_files]: - try: - file_content = await self._resolve_single_file(user_id, upload_id) - if file_content: - resolved_files.append(file_content) - except Exception as e: - logger.warning(f"Failed to resolve file {upload_id}: {e}") - # Continue with other files rather than failing entirely - continue - - return resolved_files - - async def _resolve_single_file( - self, - user_id: str, - upload_id: str - ) -> Optional[FileContent]: - """Resolve a single file upload ID.""" - - # Get file metadata - file_meta = await self._file_service.get_file(user_id, upload_id) - - if not file_meta: - logger.warning(f"File {upload_id} not found for user {user_id}") - return None - - if file_meta.status != FileStatus.READY: - logger.warning(f"File {upload_id} not ready: {file_meta.status}") - return None - - # Fetch content from S3 - try: - response = self._s3_client.get_object( - Bucket=file_meta.s3_bucket, - Key=file_meta.s3_key - ) - file_bytes = response["Body"].read() - except ClientError as e: - logger.error(f"Failed to fetch file {upload_id} from S3: {e}") - return None - - # Encode as base64 - base64_content = base64.b64encode(file_bytes).decode("utf-8") - - return FileContent( - filename=file_meta.filename, - content_type=file_meta.mime_type, - bytes=base64_content - ) - - -# Global instance -_resolver_instance: Optional[FileResolver] = None - - -def get_file_resolver() -> FileResolver: - """Get or create global FileResolver instance.""" - global _resolver_instance - if _resolver_instance is None: - _resolver_instance = FileResolver() - return _resolver_instance -``` - ---- - -### Step 3: Update Chat Request Models - -**Goal**: Add `file_upload_ids` field to request models. - -**File**: `backend/src/apis/inference_api/chat/models.py` - -```python -class InvocationRequest(BaseModel): - """Input for /invocations endpoint with multi-provider support""" - session_id: str - message: str - model_id: Optional[str] = None - temperature: Optional[float] = None - system_prompt: Optional[str] = None - caching_enabled: Optional[bool] = None - enabled_tools: Optional[List[str]] = None - files: Optional[List[FileContent]] = None # Direct file content (existing) - file_upload_ids: Optional[List[str]] = None # NEW: Upload IDs to resolve from S3 - provider: Optional[str] = None - max_tokens: Optional[int] = None -``` - ---- - -### Step 4: Integrate File Resolution into `/invocations` Endpoint - -**Goal**: Resolve `file_upload_ids` to `FileContent` objects before passing to agent. - -**File**: `backend/src/apis/inference_api/chat/routes.py` - -**Changes to `invocations()` function**: - -```python -from apis.app_api.files.file_resolver import get_file_resolver - -@router.post("/invocations") -async def invocations( - request: InvocationRequest, - current_user: User = Depends(get_current_user) -): - # ... existing code ... - - # Resolve file upload IDs to FileContent objects - files_to_send = request.files or [] - - if request.file_upload_ids: - logger.info(f"Resolving {len(request.file_upload_ids)} file upload IDs") - file_resolver = get_file_resolver() - resolved_files = await file_resolver.resolve_files( - user_id=user_id, - upload_ids=request.file_upload_ids, - max_files=5 # Bedrock document limit - ) - files_to_send.extend(resolved_files) - logger.info(f"Resolved {len(resolved_files)} files from upload IDs") - - # ... existing agent creation code ... - - # Pass resolved files to agent stream - async for event in agent.stream_async( - input_data.message, - session_id=input_data.session_id, - files=files_to_send if files_to_send else None # Use resolved files - ): - yield event -``` - ---- - -### Step 5: Update `/chat/stream` Endpoint - -**Goal**: Add file resolution to the legacy `/chat/stream` endpoint. - -**File**: `backend/src/apis/app_api/chat/routes.py` - -**Changes**: -1. Add `file_upload_ids` to `ChatRequest` model import handling -2. Resolve files before calling agent - -```python -from apis.app_api.files.file_resolver import get_file_resolver - -@router.post("/stream") -async def chat_stream( - request: ChatRequest, - current_user: User = Depends(get_current_user) -): - # ... existing RBAC and quota code ... - - # Resolve file upload IDs to FileContent objects - files_to_send = request.files or [] - - if hasattr(request, 'file_upload_ids') and request.file_upload_ids: - logger.info(f"Resolving {len(request.file_upload_ids)} file upload IDs") - file_resolver = get_file_resolver() - resolved_files = await file_resolver.resolve_files( - user_id=user_id, - upload_ids=request.file_upload_ids, - max_files=5 - ) - files_to_send.extend(resolved_files) - logger.info(f"Resolved {len(resolved_files)} files") - - # ... existing agent creation ... - - # Update stream call to pass files - stream_iterator = agent.stream_async( - request.message, - session_id=request.session_id, - files=files_to_send if files_to_send else None - ) -``` - -Also update `ChatRequest` model: - -```python -class ChatRequest(BaseModel): - """Chat request from client""" - session_id: str - message: str - files: Optional[List[FileContent]] = None - file_upload_ids: Optional[List[str]] = None # NEW - enabled_tools: Optional[List[str]] = None -``` - ---- - -### Step 6: Store Multimodal Content in Session History - -**Goal**: Persist user messages with file attachments to session history. - -**File**: `backend/src/agents/main_agent/session/turn_based_session_manager.py` - -**Changes**: -- When building user message for session, include document/image references -- Format: Include file names in a structured way that can be reconstructed - -```python -def _build_user_message_with_files( - self, - message: str, - files: Optional[List[FileContent]] -) -> dict: - """Build user message content blocks including file references.""" - content = [{"text": message}] - - if files: - # Add file reference markers (actual content handled by agent) - file_names = [f.filename for f in files] - content.append({ - "text": f"\n[Attached files: {', '.join(file_names)}]" - }) - - return { - "role": "user", - "content": content - } -``` - ---- - -### Step 7: Update Frontend Request Building - -**Goal**: Ensure frontend sends `file_upload_ids` in the correct format. - -**File**: `frontend/ai.client/src/app/session/services/chat/chat-request.service.ts` - -**Current Implementation** (already correct): -```typescript -// Add file upload IDs if present -if (fileUploadIds && fileUploadIds.length > 0) { - requestObject['file_upload_ids'] = fileUploadIds; -} -``` - -**Verification needed**: Confirm the field name matches backend expectation (`file_upload_ids`). - ---- - -### Step 8: Handle Multimodal Content in Stream Response - -**Goal**: Ensure image/document responses from agent are properly streamed. - -**Files to verify**: -1. `backend/src/agents/main_agent/streaming/stream_processor.py` - already handles tool results with images -2. `frontend/ai.client/src/app/session/services/chat/stream-parser.service.ts` - verify image block parsing - -The streaming infrastructure should already support multimodal responses via tool results (e.g., Code Interpreter returning charts). Verify no additional changes needed. - ---- - -### Step 9: Add Image Preview in Chat Input - -**Goal**: Show image previews (thumbnails) for uploaded images. - -**File**: `frontend/ai.client/src/app/components/file-card/file-card.component.ts` - -**Changes**: -- Detect if file is an image based on MIME type -- Show thumbnail preview instead of document icon for images -- Use FileReader to create data URL for preview - -```typescript -// Add to component -readonly isImage = computed(() => { - const type = this.pendingUpload()?.file.type || ''; - return type.startsWith('image/'); -}); - -readonly imagePreviewUrl = signal(null); - -ngOnInit() { - if (this.isImage()) { - const reader = new FileReader(); - reader.onload = (e) => { - this.imagePreviewUrl.set(e.target?.result as string); - }; - reader.readAsDataURL(this.pendingUpload()!.file); - } -} -``` - ---- - -### Step 10: Display Attached Files in Chat Messages - -**Goal**: Show file attachments in rendered chat messages. - -**File**: `frontend/ai.client/src/app/session/components/message/` (or appropriate message component) - -**Changes**: -- Parse message content for file references -- Display file chips/badges below message text -- For images, optionally show inline preview - ---- - -### Step 11: File Metadata Restoration on Session Load - -**Goal**: Restore file attachment metadata when loading historical sessions. - -#### Problem Statement - -When a user sends a message with file attachments: -1. Frontend has `FileAttachmentData` in memory (`uploadId`, `filename`, `mimeType`, `sizeBytes`) -2. Backend resolves `file_upload_ids` to file content and sends to Bedrock -3. AgentCore Memory stores the message text but **not** the file metadata - -When the user reloads the page or navigates back to a session: -1. Messages are loaded from AgentCore Memory -2. File metadata is **lost** - only textual references like `[Attached files: document.pdf]` remain -3. UI cannot display proper file chips/badges without metadata - -#### Solution: Fetch File Metadata from DynamoDB SessionIndex GSI - -The `user-files` DynamoDB table already has a `SessionIndex` GSI (`GSI1PK=CONV#{sessionId}`) that allows fetching all files for a session. When loading a session, the frontend fetches file metadata in parallel with messages. - -#### Backend Changes - -**File**: `backend/src/apis/app_api/files/routes.py` - -The endpoint already exists: `GET /files?sessionId={sessionId}` using `list_session_files()`. - -Verify it returns the necessary fields: -```python -@router.get("/", response_model=FileListResponse) -async def list_files( - session_id: Optional[str] = Query(None, alias="sessionId"), - current_user: User = Depends(get_current_user) -): - """ - List files for the current user. - - If sessionId is provided, returns files for that session only. - Otherwise returns all user files with pagination. - """ - user_id = current_user.user_id - - if session_id: - # Use SessionIndex GSI - no user_id check needed as files are - # already scoped to user via ownership - files = await file_service.list_session_files(session_id) - # Filter to only this user's files (security check) - files = [f for f in files if f.user_id == user_id] - return FileListResponse( - files=[FileResponse.from_metadata(f) for f in files] - ) - - # ... existing pagination logic for all user files ... -``` - -#### Frontend Changes - -**File**: `frontend/ai.client/src/app/services/file-upload/file-upload.service.ts` - -Add method to fetch session files: -```typescript -/** - * Fetch file metadata for a session. - * Used to restore file attachment data when loading historical sessions. - */ -async getSessionFiles(sessionId: string): Promise { - const response = await firstValueFrom( - this.http.get(`${this.apiUrl}/files`, { - params: { sessionId } - }) - ); - - return response.files.map(f => ({ - uploadId: f.uploadId, - filename: f.filename, - mimeType: f.mimeType, - sizeBytes: f.sizeBytes - })); -} -``` - -**File**: `frontend/ai.client/src/app/session/services/session/message-map.service.ts` - -Update `loadMessagesForSession()` to fetch and merge file metadata: - -```typescript -async loadMessagesForSession(sessionId: string): Promise { - // Check if messages already exist - const existingMessages = this.messageMap()[sessionId]; - if (existingMessages && existingMessages().length > 0) { - return; - } - - this._isLoadingSession.set(sessionId); - - try { - // Fetch messages and file metadata in parallel - const [messagesResponse, sessionFiles] = await Promise.all([ - this.sessionService.getMessages(sessionId), - this.fileUploadService.getSessionFiles(sessionId) - ]); - - // Create a lookup map: uploadId -> FileAttachmentData - const fileMetadataMap = new Map(); - for (const file of sessionFiles) { - fileMetadataMap.set(file.uploadId, file); - } - - // Process messages and enrich file attachments with metadata - const processedMessages = this.matchToolResultsToToolUses(messagesResponse.messages); - const enrichedMessages = this.enrichFileAttachments(processedMessages, fileMetadataMap); - - // Update the message map - this.messageMap.update(map => { - const updated = { ...map }; - if (!updated[sessionId]) { - updated[sessionId] = signal(enrichedMessages); - } else { - updated[sessionId].set(enrichedMessages); - } - return updated; - }); - } catch (error) { - console.error('Failed to load messages for session:', sessionId, error); - throw error; - } finally { - this._isLoadingSession.set(null); - } -} - -/** - * Enrich file attachment content blocks with metadata from DynamoDB. - * - * User messages may contain fileAttachment blocks with only uploadId. - * This method populates the full metadata (filename, mimeType, sizeBytes). - */ -private enrichFileAttachments( - messages: Message[], - fileMetadataMap: Map -): Message[] { - return messages.map(message => { - if (message.role !== 'user') { - return message; - } - - const enrichedContent = message.content.map(block => { - if (block.type === 'fileAttachment' && block.fileAttachment) { - const uploadId = block.fileAttachment.uploadId; - const fullMetadata = fileMetadataMap.get(uploadId); - - if (fullMetadata) { - return { - ...block, - fileAttachment: fullMetadata - }; - } - } - return block; - }); - - return { - ...message, - content: enrichedContent - }; - }); -} -``` - -#### Alternative: Parse Text References - -If AgentCore Memory doesn't store `fileAttachment` content blocks, messages may only contain text like `[Attached files: report.pdf, image.png]`. In this case: - -1. Parse the text reference to extract filenames -2. Match filenames to session files from DynamoDB -3. Reconstruct `fileAttachment` content blocks - -```typescript -/** - * Parse file references from message text and create fileAttachment blocks. - * Handles legacy messages that only have text references. - */ -private parseFileReferencesFromText( - messages: Message[], - fileMetadataMap: Map -): Message[] { - // Create filename -> metadata lookup - const filenameMap = new Map(); - for (const file of fileMetadataMap.values()) { - filenameMap.set(file.filename, file); - } - - return messages.map(message => { - if (message.role !== 'user') { - return message; - } - - const newContent: ContentBlock[] = []; - - for (const block of message.content) { - if (block.type === 'text' && block.text) { - // Check for file reference pattern - const match = block.text.match(/\[Attached files?: (.+)\]/); - - if (match) { - // Extract just the main text (before the file reference) - const mainText = block.text.replace(/\n?\[Attached files?: .+\]/, '').trim(); - if (mainText) { - newContent.push({ type: 'text', text: mainText }); - } - - // Parse filenames and create fileAttachment blocks - const filenames = match[1].split(',').map(f => f.trim()); - for (const filename of filenames) { - const metadata = filenameMap.get(filename); - if (metadata) { - newContent.push({ - type: 'fileAttachment', - fileAttachment: metadata - }); - } - } - } else { - newContent.push(block); - } - } else { - newContent.push(block); - } - } - - return { - ...message, - content: newContent.length > 0 ? newContent : message.content - }; - }); -} -``` - -#### Data Flow Summary - -``` -Session Load Flow: -┌─────────────────────────────────────────────────────────────────┐ -│ User navigates to /s/{sessionId} │ -└─────────────────────────────────────────────────────────────────┘ - │ - ▼ -┌─────────────────────────────────────────────────────────────────┐ -│ MessageMapService.loadMessagesForSession(sessionId) │ -│ │ -│ ┌──────────────────────┐ ┌──────────────────────┐ │ -│ │ GET /sessions/{id}/ │ │ GET /files?sessionId │ │ -│ │ messages │ │ ={sessionId} │ │ -│ │ │ │ │ │ -│ │ (AgentCore Memory) │ │ (DynamoDB GSI) │ │ -│ └──────────┬───────────┘ └──────────┬───────────┘ │ -│ │ │ │ -│ │ Promise.all() │ │ -│ └───────────┬───────────────┘ │ -│ │ │ -│ ▼ │ -│ ┌──────────────────────────────────────────────────────────┐ │ -│ │ enrichFileAttachments(messages, fileMetadataMap) │ │ -│ │ │ │ -│ │ - Match uploadId in fileAttachment blocks │ │ -│ │ - Populate filename, mimeType, sizeBytes │ │ -│ │ - OR parse text references and create blocks │ │ -│ └──────────────────────────────────────────────────────────┘ │ -└─────────────────────────────────────────────────────────────────┘ - │ - ▼ -┌─────────────────────────────────────────────────────────────────┐ -│ UI renders messages with proper file chips/badges │ -└─────────────────────────────────────────────────────────────────┘ -``` - ---- - -## Testing Strategy - -### Unit Tests - -1. **FileResolver**: Test file resolution with mocked S3/DynamoDB -2. **PromptBuilder**: Test multimodal prompt construction -3. **Image/Document Handlers**: Verify correct ContentBlock format -4. **enrichFileAttachments**: Test metadata merging with various scenarios -5. **parseFileReferencesFromText**: Test text parsing and block reconstruction - -### Integration Tests - -1. Upload image -> Send message -> Verify agent receives image -2. Upload PDF -> Send message -> Verify agent receives document -3. Upload 5+ files -> Verify limit enforcement -4. Upload to session A, try to use in session B -> Verify access denied -5. **File metadata restoration**: Load session with files -> Verify file metadata populated -6. **SessionIndex GSI query**: Verify `GET /files?sessionId=X` returns correct files - -### E2E Tests - -1. Complete flow: Upload PDF -> Ask question about it -> Verify response references content -2. Image analysis: Upload image -> Ask to describe -> Verify description -3. Mixed content: Upload image + document + text message -> Verify all processed -4. **Session reload with files**: Upload file -> Send message -> Reload page -> Verify file chips display correctly -5. **Navigate between sessions**: Session A (with files) -> Session B -> Session A -> Verify file metadata restored - ---- - -## Error Handling - -| Scenario | Handling | -|----------|----------| -| File not found in S3 | Skip file, log warning, continue with other files | -| File not owned by user | Skip file, log warning (security) | -| File not in READY status | Skip file, log info | -| S3 fetch timeout | Return error event in stream | -| Base64 encoding fails | Skip file, log error | -| Bedrock rejects file format | Stream error as assistant message | - ---- - -## Security Considerations - -1. **Authorization**: Always verify `user_id` matches file owner before fetching -2. **File Size**: S3 files are already validated on upload (4MB limit) -3. **Content Type Validation**: Trust MIME type stored at upload time -4. **Rate Limiting**: File resolution inherits request rate limits -5. **Temporary URLs**: Don't expose S3 pre-signed URLs in responses - ---- - -## Rollout Plan - -1. **Phase 1**: Backend file resolution (Steps 2-6) - - Deploy behind feature flag if needed - - Test with documents only first - -2. **Phase 2**: Image support (Steps 1, 9) - - Add image types to allowed list - - Add image preview in UI - -3. **Phase 3**: Message display & history (Steps 10-11) - - Show attachments in chat history - - Restore file metadata on session load - - Handle legacy messages with text-only file references - ---- - -## Dependencies - -- Existing file upload infrastructure (complete) -- S3 bucket with appropriate permissions -- DynamoDB tables for file metadata -- Bedrock models with document/image support - ---- - -## Estimated Complexity - -| Step | Complexity | LOC Estimate | -|------|------------|--------------| -| Step 1: Image types | Low | ~20 lines | -| Step 2: File resolver | Medium | ~100 lines | -| Step 3: Model update | Low | ~5 lines | -| Step 4: /invocations | Medium | ~30 lines | -| Step 5: /chat/stream | Medium | ~30 lines | -| Step 6: Session history | Low | ~20 lines | -| Step 7: Frontend verify | Low | ~5 lines | -| Step 8: Stream verify | Low | ~0 lines | -| Step 9: Image preview | Medium | ~40 lines | -| Step 10: Message display | Medium | ~50 lines | -| Step 11: File metadata restoration | Medium | ~80 lines | - -**Total**: ~380 lines of new code diff --git a/docs/specs/FILE_UPLOAD_FEATURE_SPEC.md b/docs/specs/FILE_UPLOAD_FEATURE_SPEC.md deleted file mode 100644 index 04a4f13d..00000000 --- a/docs/specs/FILE_UPLOAD_FEATURE_SPEC.md +++ /dev/null @@ -1,651 +0,0 @@ -# Feature Specification -## File Upload for Conversations -### boisestate.ai Platform - -| Field | Value | -|---------|-------------------------------| -| Version | 1.1 Draft | -| Date | January 1, 2026 | -| Author | Phil / Cloud Architecture Team | -| Status | Draft — Pending Review | - ---- - -## 1. Executive Summary - -This specification defines a file upload feature for boisestate.ai that enables users to attach Bedrock-compliant files to conversations. The feature leverages pre-signed URLs for secure, scalable uploads to S3, stores metadata in DynamoDB for browsing and management, and implements intelligent storage tiering for cost optimization. - -> **Note:** This feature uses "files" terminology to accommodate future expansion to images and other file types beyond documents. - ---- - -## 2. Scope - -### 2.1 In Scope - -- Document uploads (PDF, DOCX, TXT, HTML, CSV, XLS, XLSX, MD) to conversations -- Pre-signed URL upload flow with progress indication -- S3 storage with intelligent lifecycle tiering -- DynamoDB metadata storage with user browsing capabilities -- Drag-and-drop and file picker upload methods -- User storage quota enforcement (1GB per user) -- File deletion (manual and cascade on conversation delete) - -### 2.2 Out of Scope - -- Image uploads (future phase) -- Video/audio uploads -- Virus/malware scanning -- Text extraction for RAG/search -- File versioning -- Cross-region replication -- Upload cost tracking in cost accounting system - ---- - -## 3. Functional Requirements - -### 3.1 Upload Constraints - -| Constraint | Value | -|-------------------------|------------------------------| -| Maximum file size | 4 MB per file | -| Maximum files per message | 5 files | -| Per-user storage quota | 1 GB total | -| File retention | 365 days (matches session TTL) | - -### 3.2 Supported File Types - -Per AWS Bedrock documentation for document content blocks: - -| Extension | MIME Type | Notes | -|-----------|------------------------------------------------|-------------------------| -| .pdf | application/pdf | Most common document type | -| .docx | application/vnd.openxmlformats-officedocument.wordprocessingml.document | Microsoft Word | -| .txt | text/plain | Plain text | -| .html | text/html | HTML documents | -| .csv | text/csv | Spreadsheet data | -| .xls | application/vnd.ms-excel | Excel (legacy) | -| .xlsx | application/vnd.openxmlformats-officedocument.spreadsheetml.sheet | Excel | -| .md | text/markdown | Markdown files | - -### 3.3 Upload Behavior - -1. Uploads are eager — files upload immediately upon selection/drop -2. Chat submit button is disabled until all pending uploads complete -3. Upload progress indicator displays for each file -4. Failed uploads show error notification (existing error notification component) -5. Users can remove attached files before sending; removal deletes the S3 object -6. Maximum 5 files can be attached per message - ---- - -## 4. Technical Architecture - -### 4.1 System Overview - -The upload flow uses a two-phase approach: (1) client requests a pre-signed URL from the API, (2) client uploads directly to S3 using the pre-signed URL. This bypasses the API server for large file transfers, enabling horizontal scalability. - -### 4.2 Upload Sequence - -1. User selects or drops file(s) onto the chat-input component -2. Frontend validates file type and size client-side -3. Frontend calls `POST /api/files/presign` with file metadata -4. Backend validates quota, generates pre-signed URL, creates pending DynamoDB record -5. Frontend uploads file directly to S3 using pre-signed URL -6. Frontend calls `POST /api/files/{uploadId}/complete` on success -7. Backend updates DynamoDB record status to `ready` -8. File appears as attached in chat-input; submit button enables - -### 4.3 S3 Configuration - -#### 4.3.1 Bucket Structure - -``` -s3://{bucket}/user-files/{userId}/{sessionId}/{uploadId}/{filename} -``` - -This structure enables efficient access patterns: list all files for a user, list files for a session, and direct access by upload ID. - -#### 4.3.2 Lifecycle Rules - -Intelligent tiering optimizes storage costs while maintaining the 365-day retention requirement: - -| Age | Storage Class | Rationale | -|-------------|----------------------------|----------------------------------------| -| 0–30 days | S3 Standard | Frequent access during active conversations | -| 31–90 days | S3 Standard-IA | Infrequent access, lower storage cost | -| 91–365 days | S3 Glacier Instant Retrieval | Rare access, significant cost savings | -| >365 days | Delete | Matches session TTL | - -#### 4.3.3 Bucket Policy - -- Block all public access -- Require SSL/TLS for all requests -- Enable server-side encryption (SSE-S3) -- CORS configured for frontend origins - -### 4.4 DynamoDB Schema - -#### 4.4.1 Table: UserFiles - -| Attribute | Type | Description | -|----------------|--------|---------------------------------------| -| PK | String | `USER#{userId}` | -| SK | String | `FILE#{uploadId}` | -| GSI1PK | String | `CONV#{sessionId}` | -| GSI1SK | String | `FILE#{uploadId}` | -| uploadId | String | ULID — sortable unique ID | -| userId | String | Owning user ID | -| sessionId | String | Associated session/conversation | -| filename | String | Original filename | -| mimeType | String | File MIME type | -| sizeBytes | Number | File size in bytes | -| s3Key | String | Full S3 object key | -| s3Uri | String | `s3://{bucket}/{key}` for Bedrock | -| status | String | `pending` \| `ready` | -| createdAt | String | ISO 8601 timestamp | -| updatedAt | String | ISO 8601 timestamp | -| ttl | Number | Unix epoch for DynamoDB TTL (365 days) | - -#### 4.4.2 Access Patterns - -1. **List all files for a user (paginated):** Query `PK = USER#{userId}` -2. **List files for a session:** Query `GSI1PK = CONV#{sessionId}` (SessionIndex) -3. **Get single file:** GetItem `PK = USER#{userId}, SK = FILE#{uploadId}` -4. **Sort by date:** ULID in SK provides natural chronological ordering -5. **Sort by size/type:** Perform in application layer (acceptable for UI pagination) - -#### 4.4.3 User Quota Tracking - -A separate item tracks aggregate storage per user: - -``` -PK: USER#{userId}, SK: QUOTA -``` - -- `totalBytes`: Number — current usage in bytes -- `fileCount`: Number — total files -- Updated atomically via DynamoDB `UpdateExpression` with `ADD` - -### 4.5 Bedrock Integration - -Files are passed to Bedrock using S3 URIs, which is supported by most models and avoids base64 encoding overhead: - -```json -{ - "document": { - "format": "pdf", - "name": "report.pdf", - "source": { - "s3Location": { - "uri": "s3://bucket/key" - } - } - } -} -``` - -The API layer retrieves the `s3Uri` from DynamoDB and constructs the content block. IAM permissions must allow Bedrock to read from the S3 bucket. - -> **Note:** Verify S3 URI support for each model in use. Some models may require base64 encoding — implement a fallback if needed. - ---- - -## 5. API Specification - -### 5.1 POST /api/files/presign - -Request a pre-signed URL for uploading a file. - -**Request Body:** -```json -{ - "sessionId": "string", - "filename": "string", - "mimeType": "string", - "sizeBytes": 12345 -} -``` - -**Response (200 OK):** -```json -{ - "uploadId": "string", - "presignedUrl": "string", - "expiresAt": "ISO8601" -} -``` - -**Error Responses:** -- `400 Bad Request` — Invalid file type or size exceeds 4MB -- `403 Forbidden` — User quota exceeded -- `429 Too Many Requests` — Rate limit exceeded (if implemented) - -### 5.2 POST /api/files/{uploadId}/complete - -Mark an upload as complete after successful S3 upload. - -**Response (200 OK):** -```json -{ - "uploadId": "string", - "status": "ready", - "s3Uri": "string" -} -``` - -**Error Responses:** -- `404 Not Found` — Upload ID not found or not owned by user -- `409 Conflict` — Upload already completed or deleted - -### 5.3 DELETE /api/files/{uploadId} - -Delete a file. Used when user removes an attached file before sending, or manually deletes from file browser. - -**Response (204 No Content):** Success — no body returned. - -**Side Effects:** -- Deletes S3 object -- Deletes DynamoDB record -- Decrements user quota - -### 5.4 GET /api/files - -List files for the authenticated user. - -**Query Parameters:** -- `sessionId` (optional) — filter by session/conversation -- `limit` (optional, default 20, max 100) — page size -- `cursor` (optional) — pagination cursor -- `sortBy` (optional) — `date` (default), `size`, `type` -- `sortOrder` (optional) — `asc`, `desc` (default) - -**Response (200 OK):** -```json -{ - "files": [...], - "nextCursor": "string | null", - "totalCount": 123 -} -``` - -### 5.5 GET /api/files/quota - -Get current quota usage for the authenticated user. - -**Response (200 OK):** -```json -{ - "usedBytes": 524288000, - "maxBytes": 1073741824, - "fileCount": 42 -} -``` - ---- - -## 6. Frontend Specification - -### 6.1 Chat Input Component Updates - -1. Add drop zone overlay that appears on dragover with visual feedback (border highlight, icon change) -2. Extend existing attach button to support file types -3. Display attached files as cards above the text input (per Claude.ai reference screenshots) -4. File cards show: filename (truncated), file type badge, line count or size, remove (X) button -5. Disable submit button while any upload is in `pending` state -6. Show upload progress bar on each file card during upload - -### 6.2 File Card Component - -Based on the Claude.ai reference screenshots, each attached file displays as a card with: - -- Filename (truncated with ellipsis if long) -- Metadata line (e.g., "83 lines") -- File type badge (e.g., "DOCX", "MD", "PDF") -- For PDFs: thumbnail preview of first page *(future enhancement — comment in code)* -- Hover state with remove (X) button - -### 6.3 Conversation Message Display - -When a message includes files (after sending): - -- Display file cards inline with the user message (right-aligned) -- Cards are non-interactive (no remove button) once message is sent -- Clicking a card could open a preview modal *(future enhancement)* - -### 6.4 Error Handling - -- **Invalid file type:** Toast notification — "Unsupported file type. Supported: PDF, DOCX, TXT, HTML, CSV, XLS, XLSX, MD" -- **File too large:** Toast notification — "File exceeds 4MB limit" -- **Quota exceeded:** Toast notification — "Storage quota exceeded. Delete some files to upload more." -- **Upload failed:** Toast notification — "Upload failed. Please try again." (with retry option) -- **Too many files:** Toast notification — "Maximum 5 files per message" - ---- - -## 7. Security Considerations - -### 7.1 Pre-signed URL Security - -1. URLs expire after 15 minutes (sufficient for 4MB upload even on slow connections) -2. URLs are single-use via S3 condition on ETag (prevents replay) -3. URLs are scoped to specific S3 key (user cannot upload to arbitrary paths) -4. PUT-only permission (no GET, DELETE, or LIST via pre-signed URL) - -### 7.2 Content Validation - -- **MIME type validation:** Check Content-Type header matches expected type -- **Extension validation:** Verify file extension matches MIME type -- **Magic bytes validation:** *(Optional, adds complexity)* Inspect first bytes to confirm file type - -> **Recommendation:** Implement MIME type and extension validation. Magic bytes validation adds meaningful security but increases complexity — consider for v2 if abuse is observed. - -### 7.3 Access Control - -- All API endpoints require authentication via existing auth middleware -- Users can only access their own files (enforced via `PK = USER#{userId}`) -- Bedrock IAM role has read-only access to the files bucket -- No direct S3 access for users — all access mediated through API - -### 7.4 Data at Rest - -- **S3:** Server-side encryption enabled (SSE-S3) -- **DynamoDB:** Encryption at rest enabled (AWS managed key) - ---- - -## 8. Cost Analysis - -### 8.1 S3 Storage Costs (us-west-2, estimated) - -Assuming 27,000 users, 10% active monthly, average 50MB storage per active user: - -| Storage Class | Rate | Est. Monthly | -|------------------------------|------------|--------------| -| S3 Standard (0–30 days) | $0.023/GB | ~$31 | -| S3 Standard-IA (31–90 days) | $0.0125/GB | ~$17 | -| Glacier Instant (91–365 days)| $0.004/GB | ~$5 | - -**Total estimated S3 cost:** ~$50–100/month at scale, with intelligent tiering providing ~60% savings over Standard-only. - -### 8.2 DynamoDB Costs - -On-demand pricing recommended for unpredictable workloads: - -- Write: $1.25 per million writes -- Read: $0.25 per million reads -- Storage: $0.25/GB/month - -**Estimated:** <$20/month for metadata storage and operations. - ---- - -## 9. Quota Enforcement - -### 9.1 Quota Check Flow - -When a user attempts to upload a file, the system performs a quota check before generating a pre-signed URL: - -1. Frontend sends upload request with file size (`sizeBytes`) -2. Backend reads current quota from DynamoDB (`PK: USER#{userId}, SK: QUOTA`) -3. Backend calculates: `currentUsage + newFileSize` -4. If projected usage > 1GB (1,073,741,824 bytes), reject with `403 Forbidden` -5. If within quota, proceed with pre-signed URL generation - -### 9.2 User Experience When Quota Exceeded - -When a user reaches their 1GB limit, they receive clear feedback and actionable options: - -#### 9.2.1 Upload Rejection - -- API returns `403` with body: - ```json - { - "error": "QUOTA_EXCEEDED", - "message": "Storage quota exceeded", - "currentUsage": 1073741824, - "maxAllowed": 1073741824, - "requiredSpace": 4194304 - } - ``` -- Frontend displays toast: "Storage quota exceeded. You're using X of 1GB. Free up Y to upload this file." -- Toast includes action button: **"Manage Files"** — links to file browser - -#### 9.2.2 Proactive Quota Warnings - -- **At 80% usage (800MB):** Subtle indicator in file browser showing quota status -- **At 90% usage (900MB):** Warning banner in chat input area when attaching files -- **At 100%:** Upload button shows "Storage Full" state with link to manage files - -#### 9.2.3 File Browser for Quota Management - -Users can manage their storage through a file browser interface (accessible from profile/settings): - -- Display quota usage bar (used / 1GB) prominently at top -- List all uploaded files with size, date, conversation link -- Support multi-select for bulk deletion -- Sort by size (largest first) to help users identify space-saving opportunities -- Filter by date range to find old files for cleanup - -### 9.3 Quota Accounting - -#### 9.3.1 Incrementing Quota - -Quota is incremented when upload completes (`POST /api/files/{uploadId}/complete`): - -``` -UpdateExpression: ADD totalBytes :size, fileCount :one -``` - -This atomic operation ensures accurate counting even under concurrent uploads. - -#### 9.3.2 Decrementing Quota - -Quota is decremented when files are deleted: - -- Manual deletion via `DELETE /api/files/{uploadId}` -- Cascade deletion when conversation is deleted -- TTL expiration (DynamoDB Stream triggers Lambda to decrement quota) - -``` -UpdateExpression: ADD totalBytes :negativeSize, fileCount :negativeOne -``` - -#### 9.3.3 Quota Reconciliation - -A scheduled Lambda (weekly) reconciles quota by scanning actual S3 usage: - -- Lists all objects for each user prefix -- Sums actual bytes stored -- Updates quota record if discrepancy found (with CloudWatch alarm on drift) - -This handles edge cases like failed delete operations or missed stream events. - ---- - -## 10. CDK Infrastructure - -### 10.1 Stack Overview - -The file upload feature is integrated into the **AppApiStack** (not a separate stack) to simplify deployment and IAM grant management. The following resources are added: - -- S3 Bucket (`user-files`) with lifecycle rules and encryption -- DynamoDB Table (`user-files`) with GSI and TTL -- IAM grants for ECS task role -- Environment variables for container configuration - -### 10.2 Configuration - -Add to `cdk.context.json`: - -```json -{ - "fileUpload": { - "enabled": true, - "maxFileSizeBytes": 4194304, - "maxFilesPerMessage": 5, - "userQuotaBytes": 1073741824, - "retentionDays": 365 - } -} -``` - -Environment variable overrides: -- `CDK_FILE_UPLOAD_ENABLED` -- `CDK_FILE_UPLOAD_MAX_FILE_SIZE` -- `CDK_FILE_UPLOAD_MAX_FILES_PER_MESSAGE` -- `CDK_FILE_UPLOAD_USER_QUOTA` -- `CDK_FILE_UPLOAD_RETENTION_DAYS` -- `CDK_FILE_UPLOAD_CORS_ORIGINS` - -### 10.3 S3 Bucket Configuration - -```typescript -const userFilesBucket = new s3.Bucket(this, 'UserFilesBucket', { - bucketName: getResourceName(config, 'user-files', config.awsAccount), - encryption: s3.BucketEncryption.S3_MANAGED, - blockPublicAccess: s3.BlockPublicAccess.BLOCK_ALL, - enforceSSL: true, - versioned: false, - removalPolicy: config.environment === 'prod' - ? cdk.RemovalPolicy.RETAIN - : cdk.RemovalPolicy.DESTROY, - cors: [{ - allowedOrigins: fileUploadCorsOrigins, - allowedMethods: [s3.HttpMethods.PUT, s3.HttpMethods.HEAD], - allowedHeaders: ['Content-Type', 'Content-Length', 'x-amz-*'], - exposedHeaders: ['ETag'], - maxAge: 3600, - }], - lifecycleRules: [ - { id: 'transition-to-ia', transitions: [{ storageClass: s3.StorageClass.INFREQUENT_ACCESS, transitionAfter: cdk.Duration.days(30) }] }, - { id: 'transition-to-glacier', transitions: [{ storageClass: s3.StorageClass.GLACIER_INSTANT_RETRIEVAL, transitionAfter: cdk.Duration.days(90) }] }, - { id: 'expire-objects', expiration: cdk.Duration.days(config.fileUpload?.retentionDays || 365) }, - { id: 'abort-incomplete-multipart', abortIncompleteMultipartUploadAfter: cdk.Duration.days(1) }, - ], -}); -``` - -### 10.4 DynamoDB Table Configuration - -```typescript -const userFilesTable = new dynamodb.Table(this, 'UserFilesTable', { - tableName: getResourceName(config, 'user-files'), - partitionKey: { name: 'PK', type: dynamodb.AttributeType.STRING }, - sortKey: { name: 'SK', type: dynamodb.AttributeType.STRING }, - billingMode: dynamodb.BillingMode.PAY_PER_REQUEST, - pointInTimeRecovery: true, - timeToLiveAttribute: 'ttl', - stream: dynamodb.StreamViewType.NEW_AND_OLD_IMAGES, - encryption: dynamodb.TableEncryption.AWS_MANAGED, - removalPolicy: config.environment === 'prod' - ? cdk.RemovalPolicy.RETAIN - : cdk.RemovalPolicy.DESTROY, -}); - -// GSI: SessionIndex - Query files by session -userFilesTable.addGlobalSecondaryIndex({ - indexName: 'SessionIndex', - partitionKey: { name: 'GSI1PK', type: dynamodb.AttributeType.STRING }, - sortKey: { name: 'GSI1SK', type: dynamodb.AttributeType.STRING }, - projectionType: dynamodb.ProjectionType.ALL, -}); -``` - -### 10.5 Container Environment Variables - -The ECS container receives the following environment variables: - -| Variable | Description | -|----------|-------------| -| `DYNAMODB_USER_FILES_TABLE_NAME` | DynamoDB table name for file metadata | -| `S3_USER_FILES_BUCKET_NAME` | S3 bucket name for file storage | -| `FILE_UPLOAD_MAX_SIZE_BYTES` | Maximum file size in bytes | -| `FILE_UPLOAD_MAX_FILES_PER_MESSAGE` | Maximum files per message | -| `FILE_UPLOAD_USER_QUOTA_BYTES` | Per-user storage quota in bytes | - -### 10.6 IAM Permissions - -Granted automatically via CDK: - -```typescript -userFilesTable.grantReadWriteData(taskDefinition.taskRole); -userFilesBucket.grantReadWrite(taskDefinition.taskRole); -``` - -### 10.7 SSM Parameters - -Exported for cross-stack reference: - -| Parameter | Value | -|-----------|-------| -| `/{projectPrefix}/file-upload/bucket-name` | S3 bucket name | -| `/{projectPrefix}/file-upload/bucket-arn` | S3 bucket ARN | -| `/{projectPrefix}/file-upload/table-name` | DynamoDB table name | -| `/{projectPrefix}/file-upload/table-arn` | DynamoDB table ARN | - ---- - -## 11. Implementation Phases - -### Phase 1: Core Upload Flow (MVP) - -- [x] S3 bucket with lifecycle rules (in AppApiStack) -- [x] DynamoDB table and GSI (in AppApiStack) -- [ ] Pre-sign and complete API endpoints -- [ ] Frontend drag-and-drop and attach button -- [ ] File cards in chat input -- [ ] Basic validation (type, size) - -### Phase 2: Management & Polish - -- [ ] User quota tracking and enforcement -- [ ] Delete endpoint and cascade delete on conversation delete -- [ ] File browser UI for listing/sorting files -- [ ] Upload progress indicators - -### Phase 3: Future Enhancements (Out of Scope) - -- PDF thumbnail previews -- Image upload support -- Magic bytes validation -- Text extraction for search/RAG -- File preview modal - ---- - -## 12. Appendix - -### 12.1 Bedrock Document Block Reference - -From AWS Bedrock documentation, document content blocks support: - -- PDF, CSV, DOC, DOCX, XLS, XLSX, HTML, TXT, MD -- Maximum 4.5MB per document (we use 4MB for safety margin) -- Maximum 5 documents per request -- S3 URI format: `s3://bucket-name/object-key` - -### 12.2 IAM Policy (Bedrock Access to S3) - -```json -{ - "Effect": "Allow", - "Action": ["s3:GetObject"], - "Resource": "arn:aws:s3:::{bucket}/user-files/*" -} -``` - -### 12.3 Open Questions - -*No open questions at this time.* - ---- - -## 13. Sign-off - -| Role | Name | Date | -|------------------|------|------| -| Author | | | -| Technical Review | | | -| Product Owner | | | diff --git a/docs/specs/SESSION_DELETION_SPEC.md b/docs/specs/SESSION_DELETION_SPEC.md deleted file mode 100644 index c449f35e..00000000 --- a/docs/specs/SESSION_DELETION_SPEC.md +++ /dev/null @@ -1,1078 +0,0 @@ -# Session Deletion & Schema Refactoring Specification - -## Executive Summary - -This specification outlines a schema refactoring to enable session deletion while preserving cost accounting accuracy. The current `SessionsMetadata` table uses SK patterns that conflate session metadata with per-message cost data, creating performance issues and preventing clean session deletion. - -**Goal**: Allow users to delete conversations without disrupting quota enforcement, cost reports, or audit trails. - -**Approach**: Refactor SK patterns in the existing `SessionsMetadata` table to cleanly separate session records from cost records, enabling efficient queries and soft delete support. - -**Key Decision**: Use single-table design (no new tables) with updated SK prefixes for optimal operational simplicity. - -**Impact**: No user-facing or admin-facing functionality changes. Performance improvements for session listing. - ---- - -## Table of Contents - -1. [Problem Statement](#problem-statement) -2. [Current Architecture](#current-architecture) -3. [Proposed Architecture](#proposed-architecture) -4. [Schema Design](#schema-design) -5. [Session Deletion Flow](#session-deletion-flow) -6. [Impact Analysis](#impact-analysis) -7. [Implementation Plan](#implementation-plan) -8. [Implementation Details](#implementation-details) -9. [API Changes](#api-changes) -10. [Testing Strategy](#testing-strategy) - ---- - -## Problem Statement - -### Current Issues - -1. **Session and Message Records Mixed**: The `SessionsMetadata` table stores both: - - Session records: `SK = SESSION#{session_id}` - - Message cost records: `SK = SESSION#{session_id}#MSG#{message_id}` - - Both start with `SESSION#`, so `begins_with(SK, 'SESSION#')` matches both. Listing sessions requires filtering out message records in memory. - -2. **No Session Deletion**: Deleting a session would orphan cost records or break audit trails. - -3. **Performance Degradation**: A user with 100 sessions and 10,000 messages returns ~10,100 items when listing sessions, then filters 10,000 in memory. - -4. **No Server-Side Pagination**: Sessions must be sorted by `last_message_at` in memory because DynamoDB pagination follows SK order. - -### Business Requirements - -| Requirement | Priority | Notes | -|-------------|----------|-------| -| Users can delete conversations | HIGH | Privacy, cleanup | -| Deleted sessions don't appear in session list | HIGH | User expectation | -| Cost accounting remains accurate after deletion | HIGH | Billing integrity | -| Quota enforcement unaffected by deletion | HIGH | Quota uses pre-aggregated data | -| Audit trail preserved for compliance | MEDIUM | Financial records retention | -| Admin can view costs for deleted sessions | LOW | Investigation capability | - ---- - -## Current Architecture - -### SessionsMetadata Table (Current SK Patterns) - -``` -Table: SessionsMetadata -───────────────────────────────────────────────────────────────────────── -PK │ SK │ Type -───────────────────────────────────────────────────────────────────────── -USER#{user_id} │ SESSION#{session_id} │ Session metadata -USER#{user_id} │ SESSION#{session_id}#MSG#00001 │ Message cost -USER#{user_id} │ SESSION#{session_id}#MSG#00002 │ Message cost -USER#{user_id} │ SESSION#{session_id}#MSG#00003 │ Message cost -... -───────────────────────────────────────────────────────────────────────── -``` - -### Problems with Current Design - -```python -# Current list_user_sessions implementation (simplified) -async def _list_user_sessions_cloud(...): - # Query returns BOTH session and message records - response = table.query( - KeyConditionExpression="PK = :pk AND begins_with(SK, :prefix)", - ExpressionAttributeValues={ - ":pk": f"USER#{user_id}", - ":prefix": "SESSION#" # Matches both SESSION#{id} and SESSION#{id}#MSG# - } - ) - - sessions = [] - for item in response['Items']: - # Filter out message records in memory - if '#MSG#' in item.get('SK', ''): - continue # Skip message records - sessions.append(item) - - # Sort in memory (can't use DynamoDB for this) - sessions.sort(key=lambda x: x.last_message_at, reverse=True) - - return sessions[:limit] # Pagination is fake -``` - -**Complexity**: O(m + s) where m = messages, s = sessions - ---- - -## Proposed Architecture - -### Single-Table Design with New SK Prefixes - -Instead of creating new tables, we refactor the SK patterns in the existing `SessionsMetadata` table: - -``` -┌─────────────────────────────────────────────────────────────────────────┐ -│ CURRENT SK PATTERNS │ -├─────────────────────────────────────────────────────────────────────────┤ -│ SESSION#{session_id} ← Session metadata │ -│ SESSION#{session_id}#MSG#00001 ← Message cost │ -│ SESSION#{session_id}#MSG#00002 ← Message cost │ -│ │ -│ Problem: Both start with "SESSION#" - can't query sessions only │ -└─────────────────────────────────────────────────────────────────────────┘ - │ - ▼ -┌─────────────────────────────────────────────────────────────────────────┐ -│ NEW SK PATTERNS │ -├─────────────────────────────────────────────────────────────────────────┤ -│ S#ACTIVE#{last_message_at}#{session_id} ← Active session │ -│ S#DELETED#{deleted_at}#{session_id} ← Soft-deleted session │ -│ C#{timestamp}#{uuid} ← Message cost record │ -│ │ -│ Benefits: │ -│ - Query sessions: begins_with(SK, 'S#ACTIVE#') │ -│ - Query costs: begins_with(SK, 'C#') │ -│ - Sessions sorted by timestamp in SK │ -│ - No in-memory filtering or sorting needed │ -└─────────────────────────────────────────────────────────────────────────┘ -``` - -### Why Single-Table Design? - -| Factor | Single Table | Multiple Tables | -|--------|--------------|-----------------| -| **Query efficiency** | Same (with proper SK prefixes) | Same | -| **Operational complexity** | Lower (1 table to manage) | Higher (3 tables, 3 sets of alarms) | -| **Backup/restore** | Simpler (1 backup) | More complex | -| **Cost** | Slightly lower (fewer table overheads) | Slightly higher | -| **TTL handling** | Only cost records get `ttl` attribute | Clean separation | -| **Code clarity** | Requires SK prefix discipline | Natural separation | - -**Recommendation**: Single-table design for operational simplicity. The SK prefix approach provides the same query efficiency with less infrastructure overhead. - ---- - -## Schema Design - -### SessionsMetadata Table (Refactored SK Patterns) - -**Same table, new SK patterns:** - -``` -Table: SessionsMetadata (existing table, refactored) -───────────────────────────────────────────────────────────────────────── -PK │ SK │ Type -───────────────────────────────────────────────────────────────────────── -USER#{user_id} │ S#ACTIVE#{last_message_at}#{session_id} │ Active session -USER#{user_id} │ S#DELETED#{deleted_at}#{session_id} │ Deleted session -USER#{user_id} │ C#{timestamp}#{uuid} │ Message cost -───────────────────────────────────────────────────────────────────────── -``` - -### Session Record Attributes - -```python -{ - # Keys - "PK": "USER#alice", - "SK": "S#ACTIVE#2025-01-15T10:30:00Z#abc123", - - # GSI keys for direct session lookup - "GSI_PK": "SESSION#abc123", - "GSI_SK": "META", - - # Session data - "sessionId": "abc123", - "userId": "alice", - "title": "Conversation about weather", - "status": "active", - "createdAt": "2025-01-15T09:00:00Z", - "lastMessageAt": "2025-01-15T10:30:00Z", - "messageCount": 15, - - # User preferences - "starred": False, - "tags": ["weather", "planning"], - "preferences": { - "lastModel": "claude-sonnet-4-5", - "lastTemperature": 0.7, - "enabledTools": ["weather", "search"] - }, - - # Soft delete fields (only present when deleted) - "deleted": False, - "deletedAt": None - - # NOTE: No TTL attribute - sessions persist until soft-deleted -} -``` - -### Cost Record Attributes - -```python -{ - # Keys - "PK": "USER#alice", - "SK": "C#2025-01-15T10:30:45.123Z#550e8400-e29b-41d4-a716-446655440000", - - # GSI keys for per-session cost queries - "GSI_PK": "SESSION#abc123", - "GSI_SK": "C#2025-01-15T10:30:45.123Z", - - # Session reference - "sessionId": "abc123", - "messageId": 5, - - # Cost data - "cost": 0.0234, - "inputTokens": 1000, - "outputTokens": 500, - "cacheReadTokens": 200, - "cacheWriteTokens": 100, - - # Model info - "modelId": "us.anthropic.claude-sonnet-4-5-20250929-v1:0", - "modelName": "Claude 3.5 Sonnet", - "provider": "bedrock", - - # Pricing snapshot - "pricingSnapshot": { - "inputPricePerMtok": 3.0, - "outputPricePerMtok": 15.0, - "cacheReadPricePerMtok": 0.30, - "cacheWritePricePerMtok": 3.75, - "currency": "USD", - "snapshotAt": "2025-01-15T10:30:45Z" - }, - - # Latency - "timeToFirstToken": 250, - "endToEndLatency": 1500, - - # Attribution - "userId": "alice", - "timestamp": "2025-01-15T10:30:45.123Z", - - # TTL - ONLY cost records have this attribute - "ttl": 1768118400 # 365 days from creation -} -``` - -### SK Pattern Design Rationale - -| SK Pattern | Purpose | Benefits | -|------------|---------|----------| -| `S#ACTIVE#{last_message_at}#{session_id}` | Active sessions | Sorted by recency, clean prefix query | -| `S#DELETED#{deleted_at}#{session_id}` | Soft-deleted sessions | Separate from active, queryable for admin | -| `C#{timestamp}#{uuid}` | Cost records | Time-ordered, unique, supports TTL | - -### TTL Handling in Single Table - -DynamoDB TTL only deletes items that have the `ttl` attribute set: - -```python -# Session records: NO ttl attribute → persist indefinitely (until soft-deleted) -session_item = { - "PK": "USER#alice", - "SK": "S#ACTIVE#2025-01-15T10:30:00Z#abc123", - # No "ttl" attribute -} - -# Cost records: HAVE ttl attribute → auto-delete after 365 days -cost_item = { - "PK": "USER#alice", - "SK": "C#2025-01-15T10:30:45.123Z#uuid", - "ttl": int((datetime.now() + timedelta(days=365)).timestamp()) -} -``` - -### GSI: SessionLookupIndex - -For direct session access by ID and per-session cost queries: - -``` -GSI: SessionLookupIndex - PK: GSI_PK (e.g., SESSION#{session_id}) - SK: GSI_SK (e.g., META for sessions, C#{timestamp} for costs) - -Projection: ALL -``` - -**Access Patterns via GSI:** - -```python -# Get session by ID (without knowing status or timestamp) -response = table.query( - IndexName="SessionLookupIndex", - KeyConditionExpression="GSI_PK = :pk AND GSI_SK = :sk", - ExpressionAttributeValues={ - ":pk": f"SESSION#{session_id}", - ":sk": "META" - } -) - -# Get all costs for a specific session -response = table.query( - IndexName="SessionLookupIndex", - KeyConditionExpression="GSI_PK = :pk AND begins_with(GSI_SK, :prefix)", - ExpressionAttributeValues={ - ":pk": f"SESSION#{session_id}", - ":prefix": "C#" - } -) -``` - -### Access Patterns (Primary Table) - -```python -# 1. List active sessions (sorted by most recent) - O(page_size) -response = table.query( - KeyConditionExpression="PK = :pk AND begins_with(SK, :prefix)", - ExpressionAttributeValues={ - ":pk": f"USER#{user_id}", - ":prefix": "S#ACTIVE#" - }, - ScanIndexForward=False, # Descending order (most recent first) - Limit=20, - ExclusiveStartKey=pagination_token # Native DynamoDB pagination works! -) - -# 2. List deleted sessions (for admin/recovery) -response = table.query( - KeyConditionExpression="PK = :pk AND begins_with(SK, :prefix)", - ExpressionAttributeValues={ - ":pk": f"USER#{user_id}", - ":prefix": "S#DELETED#" - }, - ScanIndexForward=False, - Limit=20 -) - -# 3. Get user costs in date range (for detailed reports) -response = table.query( - KeyConditionExpression="PK = :pk AND SK BETWEEN :start AND :end", - ExpressionAttributeValues={ - ":pk": f"USER#{user_id}", - ":start": f"C#{start_date}", - ":end": f"C#{end_date}~" # ~ sorts after any timestamp - } -) -``` - ---- - -## Session Deletion Flow - -### Soft Delete Process - -```python -async def delete_session(user_id: str, session_id: str) -> None: - """ - Soft-delete a session while preserving cost records. - - Steps: - 1. Get current session to find its SK - 2. Transactionally move from S#ACTIVE# to S#DELETED# prefix - 3. Delete conversation content from AgentCore Memory - 4. Cost records (C# prefix) remain untouched - """ - now = datetime.now(timezone.utc) - - # 1. Get current session via GSI - session = await get_session_by_id(user_id, session_id) - if not session: - raise NotFoundError(f"Session {session_id} not found") - - if session.deleted: - return # Already deleted - - # 2. Build old and new SKs - old_sk = f"S#ACTIVE#{session.last_message_at}#{session_id}" - new_sk = f"S#DELETED#{now.isoformat()}#{session_id}" - - # 3. Transactional move: delete old + create new - dynamodb.transact_write_items( - TransactItems=[ - { - 'Delete': { - 'TableName': 'SessionsMetadata', - 'Key': { - 'PK': f'USER#{user_id}', - 'SK': old_sk - }, - 'ConditionExpression': 'attribute_exists(PK)' - } - }, - { - 'Put': { - 'TableName': 'SessionsMetadata', - 'Item': { - 'PK': f'USER#{user_id}', - 'SK': new_sk, - 'GSI_PK': f'SESSION#{session_id}', - 'GSI_SK': 'META', - 'sessionId': session_id, - 'userId': user_id, - 'title': session.title, - 'status': 'deleted', - 'createdAt': session.created_at, - 'lastMessageAt': session.last_message_at, - 'messageCount': session.message_count, - 'starred': session.starred, - 'tags': session.tags, - 'preferences': session.preferences, - 'deleted': True, - 'deletedAt': now.isoformat() - } - } - } - ] - ) - - # 4. Delete conversation content from AgentCore Memory (async) - # This removes the actual messages but NOT the cost records - await agentcore_memory.delete_session(session_id) - - logger.info(f"Soft-deleted session {session_id} for user {user_id}") -``` - -### What Happens to Each Data Type - -| Data Type | SK Pattern | After Deletion | -|-----------|------------|----------------| -| Session metadata | `S#ACTIVE#...` → `S#DELETED#...` | Moved to deleted prefix | -| Conversation content | AgentCore Memory | **Deleted** (user expectation) | -| Per-message costs | `C#...` | **Preserved** (audit trail, unchanged) | -| User cost summary | `UserCostSummary` table | **Unchanged** (pre-aggregated) | -| System rollups | `SystemCostRollup` table | **Unchanged** | - ---- - -## Impact Analysis - -### User Features - -| Feature | Before | After | Impact | -|---------|--------|-------|--------| -| List sessions | Filter in memory, sort in memory | Query `S#ACTIVE#` prefix | **Much faster** | -| Get session | Query by old SK | Query GSI by session ID | Same | -| Update session | Update item | Transact if `lastMessageAt` changes | Slightly more complex | -| Delete session | Not supported | Soft delete | **New feature** | -| View cost summary | `UserCostSummary` | `UserCostSummary` | Unchanged | -| Detailed cost report | Query `SESSION#...#MSG#` | Query `C#` prefix | Same | -| Quota enforcement | `UserCostSummary` | `UserCostSummary` | Unchanged | - -### Admin Features - -| Feature | Before | After | Impact | -|---------|--------|-------|--------| -| System summary | `SystemCostRollup` | `SystemCostRollup` | Unchanged | -| Top users by cost | `UserCostSummary` GSI | `UserCostSummary` GSI | Unchanged | -| Cost by model | Query `SESSION#...#MSG#` | Query `C#` prefix | Same | -| Cost trends | Query `SESSION#...#MSG#` | Query `C#` prefix | Same | -| Per-session costs | Query by session prefix | Query GSI `SESSION#{id}` + `C#` | Same | -| View deleted sessions | Not supported | Query `S#DELETED#` prefix | **New feature** | - -### Performance Comparison - -| Operation | Current | After Refactor | -|-----------|---------|----------------| -| List 20 sessions (user with 100 sessions, 10k messages) | O(10,100) query + O(100) filter + O(100) sort | **O(20) query** | -| Get session by ID | O(1) | O(1) via GSI | -| Delete session | N/A | O(1) transact write | -| Per-session costs | O(m) query | O(m) query via GSI | -| Quota check | O(1) | O(1) | - ---- - -## Implementation Plan - -Since the application is not yet in production, this is a **greenfield implementation** rather than a migration. - -### Phase 1: Add GSI to Existing Table - -Add the `SessionLookupIndex` GSI to `SessionsMetadata`: - -```bash -aws dynamodb update-table \ - --table-name SessionsMetadata \ - --attribute-definitions \ - AttributeName=GSI_PK,AttributeType=S \ - AttributeName=GSI_SK,AttributeType=S \ - --global-secondary-index-updates \ - "[{ - \"Create\": { - \"IndexName\": \"SessionLookupIndex\", - \"KeySchema\": [ - {\"AttributeName\":\"GSI_PK\",\"KeyType\":\"HASH\"}, - {\"AttributeName\":\"GSI_SK\",\"KeyType\":\"RANGE\"} - ], - \"Projection\": {\"ProjectionType\":\"ALL\"} - } - }]" -``` - -### Phase 2: Update Backend Code - -Refactor code to use new SK patterns: - -| File | Changes | -|------|---------| -| `backend/src/apis/app_api/sessions/services/metadata.py` | New SK patterns for sessions and costs | -| `backend/src/apis/app_api/sessions/routes.py` | Add `DELETE /sessions/{id}` endpoint | -| `backend/src/apis/app_api/costs/aggregator.py` | Query `C#` prefix instead of `SESSION#...#MSG#` | -| `backend/src/apis/app_api/admin/costs/routes.py` | Update queries for cost reports | - -### Phase 3: Frontend Changes - -Add delete functionality: - -| File | Changes | -|------|---------| -| `session.service.ts` | Add `deleteSession()` method | -| Session list component | Add delete button with confirmation | - ---- - -## Implementation Details - -### Updated store_session_metadata - -```python -# backend/src/apis/app_api/sessions/services/metadata.py - -async def _store_session_metadata_cloud( - session_id: str, - user_id: str, - session_metadata: SessionMetadata, - table_name: str -) -> None: - """ - Store session metadata with new SK pattern. - - Schema: - PK: USER#{user_id} - SK: S#ACTIVE#{last_message_at}#{session_id} - - GSI: SessionLookupIndex - GSI_PK: SESSION#{session_id} - GSI_SK: META - """ - dynamodb = boto3.resource('dynamodb') - table = dynamodb.Table(table_name) - - # Prepare item - item = session_metadata.model_dump(by_alias=True, exclude_none=True) - item = _convert_floats_to_decimal(item) - - last_message_at = session_metadata.last_message_at or datetime.now(timezone.utc).isoformat() - - # Build keys with new pattern - item['PK'] = f'USER#{user_id}' - item['SK'] = f'S#ACTIVE#{last_message_at}#{session_id}' - - # GSI keys for direct lookup - item['GSI_PK'] = f'SESSION#{session_id}' - item['GSI_SK'] = 'META' - - # Note: NO ttl attribute - sessions persist until soft-deleted - - table.put_item(Item=item) - logger.info(f"Stored session metadata: {session_id}") -``` - -### Updated store_message_metadata - -```python -async def _store_message_metadata_cloud( - session_id: str, - user_id: str, - message_id: int, - message_metadata: MessageMetadata, - table_name: str -) -> None: - """ - Store message metadata with new SK pattern. - - Schema: - PK: USER#{user_id} - SK: C#{timestamp}#{uuid} - - GSI: SessionLookupIndex - GSI_PK: SESSION#{session_id} - GSI_SK: C#{timestamp} - """ - import uuid as uuid_lib - from datetime import datetime, timezone, timedelta - - dynamodb = boto3.resource('dynamodb') - table = dynamodb.Table(table_name) - - metadata_dict = message_metadata.model_dump(by_alias=True, exclude_none=True) - metadata_decimal = _convert_floats_to_decimal(metadata_dict) - - timestamp = metadata_dict.get("attribution", {}).get( - "timestamp", - datetime.now(timezone.utc).isoformat() - ) - - # Generate unique SK - unique_id = str(uuid_lib.uuid4()) - - # TTL: 365 days (only cost records have TTL) - ttl = int((datetime.now(timezone.utc) + timedelta(days=365)).timestamp()) - - item = { - # Primary key with new pattern - "PK": f"USER#{user_id}", - "SK": f"C#{timestamp}#{unique_id}", - - # GSI keys for per-session queries - "GSI_PK": f"SESSION#{session_id}", - "GSI_SK": f"C#{timestamp}", - - # Session reference - "sessionId": session_id, - "messageId": message_id, - - # Attribution - "userId": user_id, - "timestamp": timestamp, - - # TTL - only cost records have this - "ttl": ttl, - - # Metadata - **metadata_decimal - } - - table.put_item(Item=item) - - # Update cost summary (unchanged) - await _update_cost_summary_async( - user_id=user_id, - timestamp=timestamp, - message_metadata=message_metadata - ) -``` - -### Updated list_user_sessions - -```python -async def _list_user_sessions_cloud( - user_id: str, - table_name: str, - limit: Optional[int] = None, - next_token: Optional[str] = None -) -> Tuple[list[SessionMetadata], Optional[str]]: - """ - List sessions with new SK pattern. - - Key improvements: - - No in-memory filtering (S#ACTIVE# only matches sessions) - - No in-memory sorting (SK includes timestamp) - - True server-side pagination - """ - dynamodb = boto3.resource('dynamodb') - table = dynamodb.Table(table_name) - - query_params = { - 'KeyConditionExpression': Key('PK').eq(f'USER#{user_id}') & Key('SK').begins_with('S#ACTIVE#'), - 'ScanIndexForward': False # Descending (most recent first) - } - - if limit: - query_params['Limit'] = limit - - if next_token: - query_params['ExclusiveStartKey'] = json.loads( - base64.b64decode(next_token).decode('utf-8') - ) - - response = table.query(**query_params) - - sessions = [] - for item in response.get('Items', []): - item = _convert_decimal_to_float(item) - # Remove DynamoDB keys - for key in ['PK', 'SK', 'GSI_PK', 'GSI_SK']: - item.pop(key, None) - sessions.append(SessionMetadata.model_validate(item)) - - # Generate next_token from LastEvaluatedKey - next_page_token = None - if 'LastEvaluatedKey' in response: - next_page_token = base64.b64encode( - json.dumps(response['LastEvaluatedKey']).encode('utf-8') - ).decode('utf-8') - - return sessions, next_page_token -``` - -### Session Service for Delete - -```python -# backend/src/apis/app_api/sessions/services/session_service.py - -class SessionService: - """Service for session CRUD operations.""" - - def __init__(self): - self.dynamodb = boto3.resource('dynamodb') - self.table_name = os.environ.get('DYNAMODB_SESSIONS_METADATA_TABLE_NAME', 'SessionsMetadata') - self.table = self.dynamodb.Table(self.table_name) - - async def get_session(self, user_id: str, session_id: str) -> Optional[SessionMetadata]: - """Get session by ID using GSI.""" - response = self.table.query( - IndexName='SessionLookupIndex', - KeyConditionExpression=Key('GSI_PK').eq(f'SESSION#{session_id}') & Key('GSI_SK').eq('META') - ) - - items = response.get('Items', []) - if not items: - return None - - item = _convert_decimal_to_float(items[0]) - - # Verify user ownership - if item.get('userId') != user_id: - return None - - # Remove DynamoDB keys - for key in ['PK', 'SK', 'GSI_PK', 'GSI_SK']: - item.pop(key, None) - - return SessionMetadata.model_validate(item) - - async def delete_session(self, user_id: str, session_id: str) -> bool: - """ - Soft-delete a session. - - Moves from S#ACTIVE# to S#DELETED# prefix. - Deletes conversation content from AgentCore Memory. - Preserves cost records (C# prefix). - """ - session = await self.get_session(user_id, session_id) - if not session: - return False - - if session.deleted: - return True # Already deleted - - now = datetime.now(timezone.utc) - - old_sk = f'S#ACTIVE#{session.last_message_at}#{session_id}' - new_sk = f'S#DELETED#{now.isoformat()}#{session_id}' - - # Build deleted item - deleted_item = { - 'PK': {'S': f'USER#{user_id}'}, - 'SK': {'S': new_sk}, - 'GSI_PK': {'S': f'SESSION#{session_id}'}, - 'GSI_SK': {'S': 'META'}, - 'sessionId': {'S': session_id}, - 'userId': {'S': user_id}, - 'title': {'S': session.title or ''}, - 'status': {'S': 'deleted'}, - 'createdAt': {'S': session.created_at}, - 'lastMessageAt': {'S': session.last_message_at}, - 'messageCount': {'N': str(session.message_count or 0)}, - 'deleted': {'BOOL': True}, - 'deletedAt': {'S': now.isoformat()} - } - - # Transactional move - self.dynamodb.meta.client.transact_write_items( - TransactItems=[ - { - 'Delete': { - 'TableName': self.table_name, - 'Key': { - 'PK': {'S': f'USER#{user_id}'}, - 'SK': {'S': old_sk} - } - } - }, - { - 'Put': { - 'TableName': self.table_name, - 'Item': deleted_item - } - } - ] - ) - - # Delete conversation content from AgentCore Memory - await self._delete_agentcore_memory(session_id) - - return True - - async def _delete_agentcore_memory(self, session_id: str) -> None: - """Delete conversation content from AgentCore Memory.""" - # Implementation depends on AgentCore Memory API - pass -``` - ---- - -## API Changes - -### New Endpoint: Delete Session - -```python -# backend/src/apis/app_api/sessions/routes.py - -@router.delete("/{session_id}", status_code=204) -async def delete_session( - session_id: str, - current_user: User = Depends(get_current_user) -): - """ - Delete a conversation. - - This soft-deletes the session metadata and permanently deletes - the conversation content from AgentCore Memory. - - Cost records are preserved for billing and audit purposes. - - Args: - session_id: Session identifier - current_user: Authenticated user - - Returns: - 204 No Content on success - - Raises: - 404: Session not found - """ - service = SessionService() - deleted = await service.delete_session( - user_id=current_user.user_id, - session_id=session_id - ) - - if not deleted: - raise HTTPException(status_code=404, detail="Session not found") - - return Response(status_code=204) -``` - -### Frontend Service Update - -```typescript -// frontend/ai.client/src/app/session/services/session/session.service.ts - -@Injectable({ providedIn: 'root' }) -export class SessionService { - private http = inject(HttpClient); - - /** - * Delete a conversation. - * - * This removes the conversation from the user's list and deletes - * the message content. Cost records are preserved. - */ - deleteSession(sessionId: string): Observable { - return this.http.delete(`${environment.apiUrl}/sessions/${sessionId}`); - } -} -``` - -### Frontend Component Update - -```typescript -@Component({ - selector: 'app-session-list-item', - changeDetection: ChangeDetectionStrategy.OnPush, - imports: [NgIcon], - providers: [provideIcons({ heroTrash })], - template: ` -
- {{ session().title }} - - -
- - @if (showConfirmDialog()) { - - } - ` -}) -export class SessionListItemComponent { - session = input.required(); - deleted = output(); - - private sessionService = inject(SessionService); - - showConfirmDialog = signal(false); - isDeleting = signal(false); - - onDelete(event: Event) { - event.stopPropagation(); - this.showConfirmDialog.set(true); - } - - confirmDelete() { - this.isDeleting.set(true); - - this.sessionService.deleteSession(this.session().sessionId) - .pipe(finalize(() => { - this.isDeleting.set(false); - this.showConfirmDialog.set(false); - })) - .subscribe({ - next: () => this.deleted.emit(this.session().sessionId), - error: (err) => console.error('Failed to delete session:', err) - }); - } -} -``` - ---- - -## Testing Strategy - -### Unit Tests - -```python -class TestSessionService: - - async def test_list_sessions_returns_only_active(self, mock_dynamodb): - """Listing sessions should not include deleted sessions.""" - service = SessionService() - - # Create active and deleted sessions - await create_session_with_sk("S#ACTIVE#2025-01-15T10:00:00Z#session1", ...) - await create_session_with_sk("S#DELETED#2025-01-15T11:00:00Z#session2", ...) - - sessions, _ = await service.list_sessions(user_id="alice") - - assert len(sessions) == 1 - assert sessions[0].session_id == "session1" - - async def test_delete_session_preserves_cost_records(self, mock_dynamodb): - """Deleting a session should not affect cost records (C# prefix).""" - # Create session and cost records - await create_session_with_sk("S#ACTIVE#...", ...) - await create_cost_record("C#2025-01-15T10:00:00Z#uuid1", session_id="abc") - await create_cost_record("C#2025-01-15T10:01:00Z#uuid2", session_id="abc") - - # Delete session - await service.delete_session(user_id="alice", session_id="abc") - - # Cost records should still exist - costs = await get_costs_for_session("abc") - assert len(costs) == 2 - - async def test_list_sessions_no_longer_returns_cost_records(self, mock_dynamodb): - """Cost records (C# prefix) should never appear in session listing.""" - # Create session and many cost records - await create_session_with_sk("S#ACTIVE#...", ...) - for i in range(100): - await create_cost_record(f"C#2025-01-15T10:{i:02d}:00Z#uuid{i}", ...) - - sessions, _ = await service.list_sessions(user_id="alice", limit=20) - - # Should only get the 1 session, not cost records - assert len(sessions) == 1 -``` - -### Performance Tests - -```python -async def test_list_sessions_performance_with_many_costs(self, mock_dynamodb): - """ - Verify O(page_size) performance even with many cost records. - - Old implementation: O(sessions + messages) with in-memory filtering - New implementation: O(page_size) direct query - """ - # Create 100 sessions with 100 cost records each = 10,000 total records - for i in range(100): - await create_session_with_sk(f"S#ACTIVE#...", session_id=f"session{i}") - for j in range(100): - await create_cost_record(f"C#...", session_id=f"session{i}") - - # Time the list operation - start = time.time() - sessions, _ = await service.list_sessions(user_id="alice", limit=20) - elapsed = time.time() - start - - assert len(sessions) == 20 - assert elapsed < 0.1 # Should be <100ms -``` - ---- - -## Rollback Plan - -Since this is pre-production, rollback is straightforward: - -1. **Revert code changes** via git -2. **Remove GSI** (optional - GSI doesn't break old code) -3. Old SK patterns continue to work - ---- - -## Success Metrics - -| Metric | Target | Measurement | -|--------|--------|-------------| -| Session listing latency | <100ms p99 | CloudWatch metrics | -| Session deletion latency | <500ms p99 | CloudWatch metrics | -| Cost accuracy after deletion | 100% | Automated tests | -| Quota accuracy after deletion | 100% | Automated tests | -| Zero data loss during deletion | 100% | Cost record comparison | - ---- - -## Open Questions - -### 1. Hard Delete vs Soft Delete Only - -**Current Decision**: Soft delete only (move to `S#DELETED#` prefix) - -**Recommendation**: Implement soft delete first. Add scheduled hard delete in future if storage costs become significant. - -### 2. Bulk Delete - -**Question**: Should users be able to delete multiple sessions at once? - -**Recommendation**: Phase 2 feature. Single delete first, then add bulk delete endpoint. - -### 3. Admin Restore Capability - -**Question**: Should admins be able to restore deleted sessions? - -**Recommendation**: Session metadata can be restored (move from `S#DELETED#` to `S#ACTIVE#`), but AgentCore Memory content cannot be recovered. Document this limitation. - ---- - -## Summary: SK Pattern Changes - -| Record Type | Old SK Pattern | New SK Pattern | -|-------------|----------------|----------------| -| Active session | `SESSION#{session_id}` | `S#ACTIVE#{last_message_at}#{session_id}` | -| Deleted session | N/A | `S#DELETED#{deleted_at}#{session_id}` | -| Message cost | `SESSION#{session_id}#MSG#{message_id}` | `C#{timestamp}#{uuid}` | - -**Key Benefits:** -- Clean prefix separation enables efficient queries -- Timestamp in session SK enables server-side sorted pagination -- Single table = simpler operations -- No new tables to create or manage -- TTL only affects cost records (sessions don't have `ttl` attribute) diff --git a/docs/specs/TOOL_RBAC_SPEC.md b/docs/specs/TOOL_RBAC_SPEC.md deleted file mode 100644 index 4f64111b..00000000 --- a/docs/specs/TOOL_RBAC_SPEC.md +++ /dev/null @@ -1,1508 +0,0 @@ -# Tool RBAC Specification (v2 - AppRole Integration) - -## Document Information - -| Field | Value | -|-------|-------| -| Version | 2.0 | -| Status | Draft | -| Created | 2025-01-XX | -| Updated | 2025-01-XX | -| Depends On | APP_ROLES_RBAC_SPEC.md | - ---- - -## Overview - -This specification defines an RBAC-based tool access system that **integrates with the existing AppRole system** (see `APP_ROLES_RBAC_SPEC.md`). The Tool Catalog provides administrators with: - -1. A centralized catalog of all available tools with metadata -2. Integration with AppRoles for role-based access control -3. Public tools available to all authenticated users -4. Default enabled/disabled states per tool -5. User-level preference overrides -6. Bidirectional sync between tool assignments and AppRole grants - -### Key Design Decision - -Tool access is managed through **AppRoles**, not direct JWT role mappings. This provides: -- Single point of role management -- Consistent permission resolution across tools and models -- Inheritance support (tools granted to parent roles flow to child roles) -- Pre-computed effective permissions for fast authorization - ---- - -## Current State - -### Backend -- Tools are defined in `backend/src/agentcore/local_tools/` and `backend/src/agentcore/builtin_tools/` -- `ToolFilter` class filters tools based on user-enabled preferences -- **AppRole system is implemented** with `grantedTools` and `effectivePermissions.tools` - -### Frontend -- Tools are hardcoded in `frontend/ai.client/src/app/session/services/tool/tool-settings.service.ts` -- Users can enable/disable tools manually -- **AppRole management UI exists** at `/admin/roles` - -### What This Spec Adds -- Tool Catalog: Centralized tool metadata (display names, categories, icons, status) -- Admin Tool Management UI -- Tool ↔ AppRole bidirectional sync -- User tool preferences stored in backend - ---- - -## Integration with AppRole System - -### How Tool Access Works - -``` -┌─────────────────────────────────────────────────────────────────────────────┐ -│ Tool Access Flow │ -├─────────────────────────────────────────────────────────────────────────────┤ -│ │ -│ 1. User requests tool list │ -│ │ -│ 2. AppRoleService.resolve_user_permissions(user) │ -│ └── Returns UserEffectivePermissions with tools: ["tool1", "tool2", *] │ -│ │ -│ 3. ToolCatalogService.get_accessible_tools(effective_permissions) │ -│ └── Filters catalog by: │ -│ - tool.is_public = true, OR │ -│ - tool.tool_id in effective_permissions.tools, OR │ -│ - "*" in effective_permissions.tools (wildcard = all) │ -│ │ -│ 4. Merge with user preferences │ -│ └── User can enable/disable tools they have access to │ -│ │ -│ 5. Return UserToolAccess[] to frontend │ -│ │ -└─────────────────────────────────────────────────────────────────────────────┘ -``` - -### Permission Sources - -| Source | Description | Example | -|--------|-------------|---------| -| Public Tool | `is_public=true` on tool | Calculator, Weather | -| AppRole Grant | Tool in role's `grantedTools` | Code Interpreter for "power_user" role | -| Inherited Grant | Tool granted via `inheritsFrom` chain | "researcher" inherits "basic_user" tools | -| Wildcard | `"*"` in effective permissions | System Admin has all tools | - ---- - -## Data Models - -### Tool Definition (Catalog Entry) - -```python -# backend/src/api/tools/models.py - -from pydantic import BaseModel, Field -from typing import List, Optional -from enum import Enum -from datetime import datetime - - -class ToolCategory(str, Enum): - """Categories for organizing tools in the UI.""" - SEARCH = "search" - DATA = "data" - VISUALIZATION = "visualization" - DOCUMENT = "document" - CODE = "code" - BROWSER = "browser" - COMMUNICATION = "communication" - UTILITY = "utility" - RESEARCH = "research" - FINANCE = "finance" - CUSTOM = "custom" - - -class ToolProtocol(str, Enum): - """Protocol used to invoke the tool.""" - LOCAL = "local" # Direct function call - AWS_SDK = "aws_sdk" # AWS Bedrock services - MCP_GATEWAY = "mcp" # MCP via AgentCore Gateway - A2A = "a2a" # Agent-to-Agent - - -class ToolStatus(str, Enum): - """Availability status of the tool.""" - ACTIVE = "active" - DEPRECATED = "deprecated" - DISABLED = "disabled" - COMING_SOON = "coming_soon" - - -class ToolDefinition(BaseModel): - """ - Catalog entry for a tool. - - NOTE: Access control is managed via AppRoles, not stored directly on tools. - The `allowed_app_roles` field is computed for display purposes only. - """ - # Identity - tool_id: str = Field(..., description="Unique identifier (e.g., 'get_current_weather')") - - # Display metadata - display_name: str = Field(..., description="Human-readable name (e.g., 'Weather Lookup')") - description: str = Field(..., description="Description of what the tool does") - category: ToolCategory = Field(default=ToolCategory.UTILITY) - icon: Optional[str] = Field(None, description="Icon identifier for UI (e.g., 'heroCloud')") - - # Technical metadata - protocol: ToolProtocol = Field(..., description="How the tool is invoked") - status: ToolStatus = Field(default=ToolStatus.ACTIVE) - requires_api_key: bool = Field(default=False, description="Whether tool requires external API key") - - # Access control - is_public: bool = Field( - default=False, - description="If true, tool is available to all authenticated users regardless of role" - ) - - # Computed field - which AppRoles grant this tool (for admin UI display) - allowed_app_roles: List[str] = Field( - default_factory=list, - description="AppRole IDs that grant access to this tool (computed from AppRoles)" - ) - - # Default behavior - enabled_by_default: bool = Field( - default=False, - description="If true, tool is enabled when user first accesses it" - ) - - # Audit - created_at: datetime = Field(default_factory=datetime.utcnow) - updated_at: datetime = Field(default_factory=datetime.utcnow) - created_by: Optional[str] = Field(None, description="User ID of admin who created this entry") - updated_by: Optional[str] = Field(None, description="User ID of admin who last updated this") - - class Config: - use_enum_values = True - - -class UserToolAccess(BaseModel): - """ - Computed tool access for a specific user. - Returned by the GET /tools endpoint. - """ - tool_id: str - display_name: str - description: str - category: ToolCategory - icon: Optional[str] - protocol: ToolProtocol - status: ToolStatus - - # Access info - granted_by: List[str] = Field( - ..., - description="List of sources that grant access (e.g., ['public', 'power_user', 'researcher'])" - ) - enabled_by_default: bool - - # Current user state - user_enabled: Optional[bool] = Field( - None, - description="User's explicit preference (None = use default)" - ) - is_enabled: bool = Field( - ..., - description="Computed: user_enabled if set, else enabled_by_default" - ) - - -class UserToolPreference(BaseModel): - """ - User's explicit tool preferences. - Stored per-user, overrides default enabled state. - """ - user_id: str - tool_preferences: dict[str, bool] = Field( - default_factory=dict, - description="Map of tool_id -> enabled state" - ) - updated_at: datetime = Field(default_factory=datetime.utcnow) -``` - ---- - -## DynamoDB Schema - -### Table: `{env}-agentcore-tool-catalog` - -Stores tool metadata only. Access control is managed in the AppRoles table. - -| Attribute | Type | Description | -|-----------|------|-------------| -| PK | String | Partition key | -| SK | String | Sort key | -| GSI1PK | String | GSI for category queries | -| GSI1SK | String | GSI sort key | - -#### Entity Patterns - -**Tool Definition:** -``` -PK: TOOL#{tool_id} -SK: METADATA -GSI1PK: CATEGORY#{category} -GSI1SK: TOOL#{tool_id} -data: { ...ToolDefinition fields } -``` - -**User Preferences:** -``` -PK: USER#{user_id} -SK: TOOL_PREFERENCES -data: { ...UserToolPreference fields } -``` - -### Relationship to AppRoles Table - -Tool grants are stored in the existing AppRoles table: - -``` -AppRole record: - roleId: "power_user" - grantedTools: ["code_interpreter", "browser_navigate", "deep_research"] - effectivePermissions.tools: ["calculator", "web_search", "code_interpreter", ...] -``` - -The Tool Catalog stores only metadata. Authorization uses the AppRole effective permissions. - ---- - -## API Endpoints - -### Public Endpoints (Authenticated Users) - -#### GET /api/tools - -Returns tools available to the current user based on their AppRole permissions. - -**Request:** -```http -GET /api/tools -Authorization: Bearer {jwt_token} -``` - -**Response:** -```json -{ - "tools": [ - { - "toolId": "get_current_weather", - "displayName": "Weather Lookup", - "description": "Get current weather for a location", - "category": "utility", - "icon": "heroCloud", - "protocol": "local", - "status": "active", - "grantedBy": ["public"], - "enabledByDefault": false, - "userEnabled": true, - "isEnabled": true - }, - { - "toolId": "code_interpreter", - "displayName": "Code Interpreter", - "description": "Execute Python code in a sandbox", - "category": "code", - "icon": "heroCodeBracket", - "protocol": "aws_sdk", - "status": "active", - "grantedBy": ["power_user"], - "enabledByDefault": false, - "userEnabled": null, - "isEnabled": false - } - ], - "categories": ["code", "utility"], - "appRolesApplied": ["power_user", "basic_user"] -} -``` - -**Access Logic:** -```python -async def get_user_tools(user: User) -> List[UserToolAccess]: - # 1. Get user's effective permissions from AppRoleService - permissions = await app_role_service.resolve_user_permissions(user) - - # 2. Get all active tools from catalog - all_tools = await tool_catalog_service.get_all_tools(status=ToolStatus.ACTIVE) - - # 3. Get user's preferences - user_prefs = await tool_catalog_service.get_user_preferences(user.user_id) - - accessible_tools = [] - - for tool in all_tools: - granted_by = [] - - # Check public access - if tool.is_public: - granted_by.append("public") - - # Check AppRole access (wildcard or specific) - if "*" in permissions.tools or tool.tool_id in permissions.tools: - # Add the AppRole IDs that grant this tool - granted_by.extend(permissions.app_roles) - - # Skip if no access - if not granted_by: - continue - - # Determine enabled state - user_enabled = user_prefs.tool_preferences.get(tool.tool_id) - is_enabled = user_enabled if user_enabled is not None else tool.enabled_by_default - - accessible_tools.append(UserToolAccess( - tool_id=tool.tool_id, - display_name=tool.display_name, - description=tool.description, - category=tool.category, - icon=tool.icon, - protocol=tool.protocol, - status=tool.status, - granted_by=list(set(granted_by)), - enabled_by_default=tool.enabled_by_default, - user_enabled=user_enabled, - is_enabled=is_enabled - )) - - return sorted(accessible_tools, key=lambda t: (t.category, t.display_name)) -``` - -#### PUT /api/tools/preferences - -Save user's tool preferences. - -**Request:** -```http -PUT /api/tools/preferences -Authorization: Bearer {jwt_token} -Content-Type: application/json - -{ - "preferences": { - "get_current_weather": true, - "ddg_web_search": false - } -} -``` - -**Validation:** -- Only accept tool_ids the user has access to -- Reject unknown tool_ids with 400 error - ---- - -### Admin Endpoints - -All admin endpoints require `require_admin` dependency. - -#### GET /api/admin/tools - -List all tools in the catalog with their role assignments. - -**Response:** -```json -{ - "tools": [ - { - "toolId": "code_interpreter", - "displayName": "Code Interpreter", - "description": "Execute Python code", - "category": "code", - "protocol": "aws_sdk", - "status": "active", - "isPublic": false, - "allowedAppRoles": ["power_user", "researcher"], - "enabledByDefault": false, - "createdAt": "2025-01-10T08:00:00Z", - "updatedAt": "2025-01-10T08:00:00Z" - } - ], - "total": 15 -} -``` - -The `allowedAppRoles` field is computed by querying which AppRoles have this tool in their `grantedTools` or `effectivePermissions.tools`. - -#### POST /api/admin/tools - -Create a new tool catalog entry. - -**Request:** -```http -POST /api/admin/tools -Content-Type: application/json - -{ - "toolId": "custom_research_tool", - "displayName": "Research Assistant", - "description": "Advanced research capabilities", - "category": "research", - "icon": "heroAcademicCap", - "protocol": "mcp", - "status": "active", - "isPublic": false, - "enabledByDefault": true -} -``` - -**Note:** This only creates the catalog entry. To grant access to AppRoles, use the role management endpoints or the bidirectional sync endpoints below. - -#### PUT /api/admin/tools/{tool_id} - -Update tool metadata. - -#### DELETE /api/admin/tools/{tool_id} - -Soft delete (sets status to "disabled") by default. - ---- - -### Bidirectional Sync Endpoints - -These endpoints maintain consistency between tool grants and AppRole definitions. - -#### GET /api/admin/tools/{tool_id}/roles - -Get AppRoles that grant access to this tool. - -**Response:** -```json -{ - "toolId": "code_interpreter", - "roles": [ - { - "roleId": "power_user", - "displayName": "Power User", - "grantType": "direct", - "enabled": true - }, - { - "roleId": "researcher", - "displayName": "Researcher", - "grantType": "inherited", - "inheritedFrom": "power_user", - "enabled": true - } - ] -} -``` - -#### PUT /api/admin/tools/{tool_id}/roles - -Set which AppRoles grant access to this tool. - -**Request:** -```http -PUT /api/admin/tools/code_interpreter/roles -Content-Type: application/json - -{ - "appRoleIds": ["power_user", "researcher", "developer"] -} -``` - -**Behavior:** -1. For each roleId in the request, add tool_id to that role's `grantedTools` -2. For roles NOT in the request, remove tool_id from their `grantedTools` -3. Trigger permission recomputation for affected roles -4. Invalidate caches - -This is equivalent to editing each AppRole individually but provides a tool-centric view. - -#### POST /api/admin/tools/{tool_id}/roles/add - -Add AppRoles to tool access (preserves existing). - -**Request:** -```http -POST /api/admin/tools/code_interpreter/roles/add -Content-Type: application/json - -{ - "appRoleIds": ["new_role"] -} -``` - -#### POST /api/admin/tools/{tool_id}/roles/remove - -Remove AppRoles from tool access. - -**Request:** -```http -POST /api/admin/tools/code_interpreter/roles/remove -Content-Type: application/json - -{ - "appRoleIds": ["old_role"] -} -``` - ---- - -## Service Implementation - -### ToolCatalogService - -```python -# backend/src/api/tools/service.py - -from typing import List, Optional -from api.tools.models import ToolDefinition, UserToolAccess, UserToolPreference -from api.tools.repository import ToolCatalogRepository -from api.rbac.service import AppRoleService -from api.rbac.models import AppRole -from shared.auth.models import User - - -class ToolCatalogService: - """ - Service for tool catalog operations. - - Tool access is determined by AppRoles. This service provides: - - Catalog management (CRUD for tool metadata) - - User preference management - - Access computation using AppRoleService - - Bidirectional sync between tools and AppRoles - """ - - def __init__( - self, - repository: ToolCatalogRepository, - app_role_service: AppRoleService, - app_role_admin_service: AppRoleAdminService - ): - self.repository = repository - self.app_role_service = app_role_service - self.app_role_admin_service = app_role_admin_service - - async def get_user_accessible_tools(self, user: User) -> List[UserToolAccess]: - """ - Get tools accessible to a user based on their AppRole permissions. - """ - # Get effective permissions from AppRoleService - permissions = await self.app_role_service.resolve_user_permissions(user) - - # Get all active tools - all_tools = await self.repository.list_tools(status="active") - - # Get user preferences - prefs = await self.repository.get_user_preferences(user.user_id) - - accessible = [] - for tool in all_tools: - granted_by = self._compute_granted_by(tool, permissions) - - if not granted_by: - continue - - user_enabled = prefs.tool_preferences.get(tool.tool_id) - is_enabled = user_enabled if user_enabled is not None else tool.enabled_by_default - - accessible.append(UserToolAccess( - tool_id=tool.tool_id, - display_name=tool.display_name, - description=tool.description, - category=tool.category, - icon=tool.icon, - protocol=tool.protocol, - status=tool.status, - granted_by=granted_by, - enabled_by_default=tool.enabled_by_default, - user_enabled=user_enabled, - is_enabled=is_enabled - )) - - return sorted(accessible, key=lambda t: (t.category.value, t.display_name)) - - def _compute_granted_by( - self, - tool: ToolDefinition, - permissions: UserEffectivePermissions - ) -> List[str]: - """Compute which sources grant access to this tool.""" - granted_by = [] - - if tool.is_public: - granted_by.append("public") - - if "*" in permissions.tools or tool.tool_id in permissions.tools: - granted_by.extend(permissions.app_roles) - - return list(set(granted_by)) - - async def get_roles_for_tool(self, tool_id: str) -> List[dict]: - """ - Get all AppRoles that grant access to a tool. - Uses the ToolRoleMappingIndex GSI on AppRoles table. - """ - return await self.app_role_admin_service.get_roles_granting_tool(tool_id) - - async def set_roles_for_tool( - self, - tool_id: str, - app_role_ids: List[str], - admin: User - ) -> None: - """ - Set which AppRoles grant access to a tool (bidirectional sync). - - This updates the grantedTools field on each affected AppRole. - """ - # Get current roles that grant this tool - current_roles = await self.get_roles_for_tool(tool_id) - current_role_ids = {r["roleId"] for r in current_roles if r["grantType"] == "direct"} - - new_role_ids = set(app_role_ids) - - # Roles to add tool to - to_add = new_role_ids - current_role_ids - - # Roles to remove tool from - to_remove = current_role_ids - new_role_ids - - # Update each role - for role_id in to_add: - await self.app_role_admin_service.add_tool_to_role(role_id, tool_id, admin) - - for role_id in to_remove: - await self.app_role_admin_service.remove_tool_from_role(role_id, tool_id, admin) - - async def sync_catalog_from_registry(self, dry_run: bool = True) -> dict: - """ - Discover tools from backend registry and sync to catalog. - - Returns summary of discovered, orphaned, and unchanged tools. - """ - from agentcore.local_tools import get_all_local_tools - from agentcore.builtin_tools import get_all_builtin_tools - - registered_tools = get_all_local_tools() + get_all_builtin_tools() - registered_ids = {t.name for t in registered_tools} - - catalog_tools = await self.repository.list_tools() - catalog_ids = {t.tool_id for t in catalog_tools} - - discovered = [] - for tool in registered_tools: - if tool.name not in catalog_ids: - discovered.append({ - "tool_id": tool.name, - "display_name": tool.name.replace("_", " ").title(), - "description": tool.description or "", - "protocol": self._infer_protocol(tool), - "action": "create" - }) - - orphaned = [] - for tool in catalog_tools: - if tool.tool_id not in registered_ids: - orphaned.append({ - "tool_id": tool.tool_id, - "action": "mark_deprecated" - }) - - unchanged = list(catalog_ids & registered_ids) - - if not dry_run: - for item in discovered: - await self.repository.create_tool(ToolDefinition(**item)) - for item in orphaned: - await self.repository.update_tool(item["tool_id"], {"status": "deprecated"}) - - return { - "discovered": discovered, - "orphaned": orphaned, - "unchanged": unchanged, - "dry_run": dry_run - } -``` - -### AppRoleAdminService Extensions - -Add these methods to the existing `AppRoleAdminService`: - -```python -# backend/src/api/rbac/admin_service.py (additions) - -class AppRoleAdminService: - # ... existing methods ... - - async def get_roles_granting_tool(self, tool_id: str) -> List[dict]: - """ - Query which AppRoles grant access to a specific tool. - Uses GSI2 (ToolRoleMappingIndex) for efficient lookup. - """ - # Query GSI2: GSI2PK=TOOL#{tool_id} - results = await self.repository.query_roles_by_tool(tool_id) - - roles = [] - for item in results: - role = await self.get_role(item["roleId"]) - if role: - # Determine if grant is direct or inherited - grant_type = "direct" if tool_id in role.granted_tools else "inherited" - inherited_from = None - - if grant_type == "inherited": - # Find which parent role provides this tool - for parent_id in role.inherits_from: - parent = await self.get_role(parent_id) - if parent and tool_id in parent.effective_permissions.tools: - inherited_from = parent_id - break - - roles.append({ - "roleId": role.role_id, - "displayName": role.display_name, - "grantType": grant_type, - "inheritedFrom": inherited_from, - "enabled": role.enabled - }) - - return roles - - async def add_tool_to_role( - self, - role_id: str, - tool_id: str, - admin: User - ) -> AppRole: - """ - Add a tool to a role's grantedTools. - Triggers permission recomputation. - """ - role = await self.get_role(role_id) - if not role: - raise ValueError(f"Role '{role_id}' not found") - - if tool_id not in role.granted_tools: - new_tools = role.granted_tools + [tool_id] - return await self.update_role(role_id, {"grantedTools": new_tools}, admin) - - return role - - async def remove_tool_from_role( - self, - role_id: str, - tool_id: str, - admin: User - ) -> AppRole: - """ - Remove a tool from a role's grantedTools. - Triggers permission recomputation. - """ - role = await self.get_role(role_id) - if not role: - raise ValueError(f"Role '{role_id}' not found") - - if tool_id in role.granted_tools: - new_tools = [t for t in role.granted_tools if t != tool_id] - return await self.update_role(role_id, {"grantedTools": new_tools}, admin) - - return role -``` - ---- - -## Frontend Integration - -### Updated ToolService - -Replace hardcoded tool list with API-driven approach: - -```typescript -// frontend/ai.client/src/app/services/tool/tool.service.ts - -import { Injectable, inject, signal, computed } from '@angular/core'; -import { HttpClient } from '@angular/common/http'; -import { firstValueFrom } from 'rxjs'; -import { environment } from '../../../environments/environment'; - -export interface Tool { - toolId: string; - displayName: string; - description: string; - category: string; - icon: string | null; - protocol: string; - status: string; - grantedBy: string[]; - enabledByDefault: boolean; - userEnabled: boolean | null; - isEnabled: boolean; -} - -export interface ToolsResponse { - tools: Tool[]; - categories: string[]; - appRolesApplied: string[]; -} - -@Injectable({ - providedIn: 'root' -}) -export class ToolService { - private http = inject(HttpClient); - private apiUrl = environment.apiUrl; - - // State - private _tools = signal([]); - private _loading = signal(false); - private _error = signal(null); - private _appRolesApplied = signal([]); - - // Public readonly signals - readonly tools = this._tools.asReadonly(); - readonly loading = this._loading.asReadonly(); - readonly error = this._error.asReadonly(); - readonly appRolesApplied = this._appRolesApplied.asReadonly(); - - // Computed - readonly enabledTools = computed(() => - this._tools().filter(t => t.isEnabled) - ); - - readonly enabledToolIds = computed(() => - this.enabledTools().map(t => t.toolId) - ); - - readonly toolsByCategory = computed(() => { - const grouped = new Map(); - for (const tool of this._tools()) { - const list = grouped.get(tool.category) || []; - list.push(tool); - grouped.set(tool.category, list); - } - return grouped; - }); - - /** - * Fetch available tools for the current user. - * Should be called on app init or after login. - */ - async loadTools(): Promise { - this._loading.set(true); - this._error.set(null); - - try { - const response = await firstValueFrom( - this.http.get(`${this.apiUrl}/tools`) - ); - this._tools.set(response.tools); - this._appRolesApplied.set(response.appRolesApplied); - } catch (err) { - this._error.set('Failed to load tools'); - console.error('Tool load error:', err); - } finally { - this._loading.set(false); - } - } - - /** - * Toggle a tool's enabled state. - */ - async toggleTool(toolId: string): Promise { - const tool = this._tools().find(t => t.toolId === toolId); - if (!tool) return; - - const newState = !tool.isEnabled; - - // Optimistic update - this._tools.update(tools => - tools.map(t => - t.toolId === toolId - ? { ...t, isEnabled: newState, userEnabled: newState } - : t - ) - ); - - try { - await this.savePreferences({ [toolId]: newState }); - } catch (err) { - // Revert on error - this._tools.update(tools => - tools.map(t => - t.toolId === toolId - ? { ...t, isEnabled: tool.isEnabled, userEnabled: tool.userEnabled } - : t - ) - ); - throw err; - } - } - - private async savePreferences(preferences: Record): Promise { - await firstValueFrom( - this.http.put(`${this.apiUrl}/tools/preferences`, { preferences }) - ); - } -} -``` - -### Admin Tool Management Component - -```typescript -// frontend/ai.client/src/app/admin/tools/tool-management.page.ts - -import { - Component, - inject, - signal, - computed, - ChangeDetectionStrategy, - OnInit -} from '@angular/core'; -import { CommonModule } from '@angular/common'; -import { ReactiveFormsModule } from '@angular/forms'; -import { NgIcon, provideIcons } from '@ng-icons/core'; -import { - heroPencil, - heroTrash, - heroPlus, - heroUserGroup, - heroArrowPath -} from '@ng-icons/heroicons/outline'; -import { AdminToolService, ToolDefinition } from './admin-tool.service'; -import { ToolRoleDialogComponent } from './tool-role-dialog.component'; - -@Component({ - selector: 'app-tool-management', - changeDetection: ChangeDetectionStrategy.OnPush, - imports: [CommonModule, ReactiveFormsModule, NgIcon, ToolRoleDialogComponent], - providers: [provideIcons({ heroPencil, heroTrash, heroPlus, heroUserGroup, heroArrowPath })], - template: ` -
-
-

Tool Catalog

-
- - -
-
- - -
- - - -
- - -
- - - - - - - - - - - - - @for (tool of filteredTools(); track tool.toolId) { - - - - - - - - - } - -
ToolCategoryAccessDefaultStatusActions
-
{{ tool.displayName }}
-
{{ tool.toolId }}
- 		- - {{ tool.category }} - - - @if (tool.isPublic) { - Public - } @else { - - {{ tool.allowedAppRoles.length }} roles - - } - - - {{ tool.enabledByDefault ? 'Enabled' : 'Disabled' }} - - - - {{ tool.status }} - - - - - -
-
- - - @if (selectedToolForRoles()) { - - } -
- ` -}) -export class ToolManagementPage implements OnInit { - private adminToolService = inject(AdminToolService); - - // Filters - statusFilter = signal(''); - categoryFilter = signal(''); - syncing = signal(false); - - // Dialogs - selectedToolForRoles = signal(null); - - // Data - tools = this.adminToolService.tools; - categories = computed(() => - [...new Set(this.tools().map(t => t.category))].sort() - ); - - filteredTools = computed(() => { - let result = this.tools(); - - const status = this.statusFilter(); - if (status) { - result = result.filter(t => t.status === status); - } - - const category = this.categoryFilter(); - if (category) { - result = result.filter(t => t.category === category); - } - - return result; - }); - - ngOnInit(): void { - this.adminToolService.loadTools(); - } - - getStatusClass(status: string): string { - switch (status) { - case 'active': return 'text-green-600 dark:text-green-400'; - case 'deprecated': return 'text-yellow-600 dark:text-yellow-400'; - case 'disabled': return 'text-red-600 dark:text-red-400'; - default: return 'text-gray-600 dark:text-gray-400'; - } - } - - openCreateDialog(): void { - // Open dialog to create new tool - } - - openEditDialog(tool: ToolDefinition): void { - // Open dialog to edit tool - } - - openRoleDialog(tool: ToolDefinition): void { - this.selectedToolForRoles.set(tool); - } - - async onRolesSaved(roleIds: string[]): Promise { - const tool = this.selectedToolForRoles(); - if (tool) { - await this.adminToolService.setToolRoles(tool.toolId, roleIds); - this.selectedToolForRoles.set(null); - } - } - - async deleteTool(tool: ToolDefinition): Promise { - if (confirm(`Delete tool "${tool.displayName}"?`)) { - await this.adminToolService.deleteTool(tool.toolId); - } - } - - async syncFromRegistry(): Promise { - this.syncing.set(true); - try { - const result = await this.adminToolService.syncFromRegistry(false); - alert(`Sync complete:\n- Created: ${result.discovered.length}\n- Deprecated: ${result.orphaned.length}`); - } finally { - this.syncing.set(false); - } - } -} -``` - -### Tool Role Assignment Dialog - -```typescript -// frontend/ai.client/src/app/admin/tools/tool-role-dialog.component.ts - -import { - Component, - ChangeDetectionStrategy, - input, - output, - inject, - signal, - OnInit -} from '@angular/core'; -import { CommonModule } from '@angular/common'; -import { NgIcon, provideIcons } from '@ng-icons/core'; -import { heroXMark, heroCheck } from '@ng-icons/heroicons/outline'; -import { AdminToolService, ToolDefinition, ToolRoleAssignment } from './admin-tool.service'; -import { AppRolesService, AppRole } from '../roles/services/app-roles.service'; - -@Component({ - selector: 'app-tool-role-dialog', - changeDetection: ChangeDetectionStrategy.OnPush, - imports: [CommonModule, NgIcon], - providers: [provideIcons({ heroXMark, heroCheck })], - template: ` -
-
- -
-
-

Manage Role Access

-

{{ tool().displayName }}

-
- -
- - -
- @if (loading()) { -

Loading roles...

- } @else { -

- Select which AppRoles should have access to this tool. -

- -
- @for (role of allRoles(); track role.roleId) { - - } -
- } -
- - -
-

- Changes take effect within 5-10 minutes. -

-
- - -
-
-
-
- ` -}) -export class ToolRoleDialogComponent implements OnInit { - tool = input.required(); - closed = output(); - saved = output(); - - private adminToolService = inject(AdminToolService); - private appRolesService = inject(AppRolesService); - - loading = signal(true); - saving = signal(false); - allRoles = signal([]); - currentAssignments = signal>(new Map()); - selectedRoleIds = signal>(new Set()); - - async ngOnInit(): Promise { - this.loading.set(true); - try { - // Load all roles and current assignments in parallel - const [roles, assignments] = await Promise.all([ - this.appRolesService.listRoles(), - this.adminToolService.getToolRoles(this.tool().toolId) - ]); - - this.allRoles.set(roles.roles.filter(r => !r.isSystemRole || r.roleId !== 'system_admin')); - - const assignmentMap = new Map(); - for (const a of assignments) { - assignmentMap.set(a.roleId, a); - } - this.currentAssignments.set(assignmentMap); - - // Initialize selected with direct grants only - const directGrants = assignments.filter(a => a.grantType === 'direct').map(a => a.roleId); - this.selectedRoleIds.set(new Set(directGrants)); - } finally { - this.loading.set(false); - } - } - - toggleRole(roleId: string): void { - this.selectedRoleIds.update(set => { - const newSet = new Set(set); - if (newSet.has(roleId)) { - newSet.delete(roleId); - } else { - newSet.add(roleId); - } - return newSet; - }); - } - - getGrantType(roleId: string): string { - const assignment = this.currentAssignments().get(roleId); - if (!assignment) return ''; - if (assignment.grantType === 'inherited') { - return `inherited from ${assignment.inheritedFrom}`; - } - return 'direct'; - } - - async save(): Promise { - this.saving.set(true); - try { - const roleIds = Array.from(this.selectedRoleIds()); - this.saved.emit(roleIds); - } finally { - this.saving.set(false); - } - } -} -``` - ---- - -## Migration Strategy - -### Phase 1: Tool Catalog Infrastructure - -1. Create DynamoDB table for tool catalog (metadata only) -2. Implement `ToolCatalogRepository` -3. Create seed script to populate catalog from existing registry -4. Implement `/api/tools` and `/api/tools/preferences` endpoints - -### Phase 2: AppRole Integration - -1. Add `get_roles_granting_tool()` to AppRoleAdminService -2. Add `add_tool_to_role()` and `remove_tool_from_role()` methods -3. Implement bidirectional sync endpoints -4. Update ToolRoleMappingIndex (GSI2) queries - -### Phase 3: Frontend Integration - -1. Create `ToolService` to replace hardcoded list -2. Update tool settings UI to use dynamic data -3. Add tool loading to app initialization - -### Phase 4: Admin UI - -1. Create tool catalog management page -2. Create tool-role assignment dialog -3. Add sync from registry feature -4. Integrate with existing role management UI - -### Phase 5: Cleanup - -1. Remove hardcoded tool lists from frontend -2. Update documentation -3. Add monitoring/alerting - ---- - -## Seed Data - -Initial tool catalog entries (access controlled via AppRoles): - -```json -{ - "tools": [ - { - "toolId": "calculator", - "displayName": "Calculator", - "description": "Perform mathematical calculations", - "category": "utility", - "icon": "heroCalculator", - "protocol": "local", - "isPublic": true, - "enabledByDefault": true - }, - { - "toolId": "get_current_weather", - "displayName": "Weather Lookup", - "description": "Get current weather conditions for a location", - "category": "utility", - "icon": "heroCloud", - "protocol": "local", - "isPublic": true, - "enabledByDefault": false - }, - { - "toolId": "ddg_web_search", - "displayName": "Web Search", - "description": "Search the web using DuckDuckGo", - "category": "search", - "icon": "heroGlobeAlt", - "protocol": "local", - "isPublic": true, - "enabledByDefault": false - }, - { - "toolId": "code_interpreter", - "displayName": "Code Interpreter", - "description": "Execute Python code and generate visualizations", - "category": "code", - "icon": "heroCodeBracket", - "protocol": "aws_sdk", - "isPublic": false, - "enabledByDefault": false - }, - { - "toolId": "browser_navigate", - "displayName": "Browser Navigation", - "description": "Navigate to URLs in an automated browser", - "category": "browser", - "icon": "heroComputerDesktop", - "protocol": "aws_sdk", - "isPublic": false, - "enabledByDefault": false - } - ] -} -``` - -**Note:** The `allowedAppRoles` field is computed at runtime by querying which AppRoles have each tool in their `grantedTools`. - ---- - -## Security Considerations - -### Authorization Enforcement - -1. **AppRole-based Access**: Tool access derives from AppRole effective permissions -2. **Double Validation**: Tool access validated on both frontend (UI filtering) and backend (request validation) -3. **Audit Trail**: All admin actions logged with actor, timestamp, and changes -4. **Cache Consistency**: Tool access changes propagate via AppRole cache invalidation (5-10 min) - -### Principle of Least Privilege - -- Public tools explicitly marked with `isPublic: true` -- Non-public tools require explicit AppRole grant -- System admin has wildcard access (`"*"` in effective permissions) - ---- - -## Open Questions (Resolved) - -| Question | Resolution | -|----------|-----------| -| Role Discovery | Use AppRoles from existing RBAC system | -| Tool Dependencies | Future enhancement - not in initial scope | -| Usage Quotas | Handled by existing quota system | -| Tool Groups | AppRole inheritance provides grouping | - ---- - -## Appendix: Comparison with v1 Spec - -| Aspect | v1 (Original) | v2 (This Spec) | -|--------|---------------|----------------| -| Access Control | `allowed_roles: ["Faculty", "Staff"]` (JWT roles) | Via AppRoles (`grantedTools` field) | -| Role Assignments | `ToolRoleAssignment` entity | Stored on AppRole, computed for display | -| DynamoDB Schema | Separate tool-role mapping items | Uses AppRoles table GSI2 | -| Permission Resolution | Custom logic per tool | Reuses AppRoleService | -| Inheritance | None | Via AppRole `inheritsFrom` | -| Caching | Custom tool cache | Reuses AppRole cache layer | - ---- - -*End of Specification* diff --git a/docs/specs/USER_ADMIN_SPEC.md b/docs/specs/USER_ADMIN_SPEC.md deleted file mode 100644 index 31963f02..00000000 --- a/docs/specs/USER_ADMIN_SPEC.md +++ /dev/null @@ -1,2310 +0,0 @@ -# User Admin System - Implementation Specification - -**Version:** 1.0 -**Created:** 2025-12-27 -**Status:** Ready for Implementation - ---- - -## Table of Contents - -1. [Overview](#overview) -2. [Scope](#scope) -3. [DynamoDB Schema](#dynamodb-schema) -4. [Backend Implementation](#backend-implementation) -5. [Frontend Implementation](#frontend-implementation) -6. [User Sync Strategy](#user-sync-strategy) -7. [Testing Strategy](#testing-strategy) -8. [Deployment Plan](#deployment-plan) -9. [Validation Criteria](#validation-criteria) - ---- - -## Overview - -### Objectives - -Provide admins with a centralized user lookup view to: -- Search and browse users -- View user profile information synced from JWT -- See user cost and quota status at a glance -- Access user-specific quota events and history -- Take admin actions (create overrides, assign tiers) - -### Design Principles - -1. **Scan-Free Queries** - All access patterns use GSIs, no table scans -2. **Just-in-Time Sync** - User records created/updated from JWT on login -3. **Eventual Consistency** - `lastLoginAt` updated on login, not per-request -4. **Composable Queries** - User detail aggregates data from multiple tables in parallel - ---- - -## Scope - -### Included - -**User Management:** -- User record storage with JWT-synced data -- Search by email (exact match) -- Browse by email domain -- Browse by status + recent login -- User detail view with aggregated data - -**User Detail View:** -- Profile info (email, name, roles, picture) -- Current month cost summary -- Quota status (resolved tier, usage, remaining) -- Recent quota events -- Admin actions (create override, assign tier) - -**Admin Dashboard Widgets:** -- Recently active users -- Users approaching quota (80%+) -- Users by email domain - -### Not Included (Future Consideration) - -- Full-text search (name/email partial match) -- User suspension/account management -- Usage analytics and trends -- Session history browsing -- Data export (GDPR) - ---- - -## DynamoDB Schema - -### Users Table - -``` -Table: Users -Environment Variable: DYNAMODB_USERS_TABLE_NAME (default: "Users") -═══════════════════════════════════════════════════════════════ - -Primary Key: - PK: USER# - SK: PROFILE - -Attributes: - userId: string # From JWT "sub" claim - email: string # Lowercase, from JWT - name: string # From JWT "name" claim - roles: string[] # From JWT "roles" claim (stored as List) - picture: string? # From JWT "picture" claim (optional) - emailDomain: string # Extracted from email, lowercase - createdAt: string # ISO timestamp, first login - lastLoginAt: string # ISO timestamp, updated on each login - status: string # "active" | "inactive" | "suspended" - -═══════════════════════════════════════════════════════════════ -``` - -### Global Secondary Indexes - -| GSI | PK | SK | Projection | Use Case | -|-----|----|----|------------|----------| -| **UserIdIndex** | `userId` | - | ALL | O(1) lookup by user ID (for deep links) | -| **EmailIndex** | `email` | - | ALL | O(1) exact email lookup | -| **EmailDomainIndex** | `DOMAIN#` | `lastLoginAt` | KEYS_ONLY + userId, email, name, status | Browse users by company/domain | -| **StatusLoginIndex** | `STATUS#` | `lastLoginAt` | KEYS_ONLY + userId, email, name, emailDomain | Browse active users by recency | - -### Access Patterns - -| Pattern | Query | GSI | Notes | -|---------|-------|-----|-------| -| Get user by ID (internal) | `PK = USER#` | - | Primary key lookup (requires PK prefix) | -| Get user by ID (deep link) | `userId = ` | UserIdIndex | Direct ID lookup for admin deep links | -| Get user by email | `email = ` | EmailIndex | Case-insensitive (store lowercase) | -| List users by domain | `PK = DOMAIN#`, sorted by `lastLoginAt` | EmailDomainIndex | Paginated, most recent first | -| List active users | `PK = STATUS#active`, sorted by `lastLoginAt` | StatusLoginIndex | Paginated, most recent first | -| List inactive users | `PK = STATUS#inactive`, sorted by `lastLoginAt` | StatusLoginIndex | Users with old lastLoginAt | - -### Deep Link Support - -The `UserIdIndex` enables admin deep links to user detail pages: - -``` -/admin/users/:userId -``` - -This is used by: -- **TopUsersTableComponent** - Click on a row to navigate to user detail -- **Cost Dashboard** - Click on user in cost breakdown -- **Quota Events** - Click on user ID to view user detail -- **External links** - Share user detail URL with other admins - -#### Integration with Existing Components - -**TopUsersTableComponent** (`frontend/ai.client/src/app/admin/costs/components/top-users-table.component.ts`) - -Already emits `userClick` event with `userId`. Update the parent component's handler: - -```typescript -// In admin-costs.page.ts -onUserClick(userId: string): void { - this.router.navigate(['/admin/users', userId]); -} -``` - -**Quota Event Viewer** - Add user ID links in the event list to navigate to user detail. - -### Capacity Planning (30K Users) - -**Read Capacity:** -- User lookup: 1 RCU per request -- List queries: ~10 RCU per page (25 items) -- Expected: 100-500 RCU sustained - -**Write Capacity:** -- User sync on login: 1 WCU per login -- 30K users × 2 logins/day = 60K writes/day = ~1 WCU sustained -- Peak: 10-50 WCU (morning login surge) - -**Recommendation:** On-demand capacity mode - ---- - -## Backend Implementation - -### Directory Structure - -``` -backend/src/ -├── apis/ -│ └── app_api/ -│ └── admin/ -│ └── users/ -│ ├── __init__.py -│ ├── routes.py # API endpoints -│ ├── service.py # Business logic -│ └── models.py # Request/response models -└── users/ - ├── __init__.py - ├── models.py # Domain models - ├── repository.py # DynamoDB operations - └── sync.py # JWT sync logic -``` - -### Domain Models - -**File:** `backend/src/users/models.py` - -```python -from pydantic import BaseModel, Field, field_validator -from typing import List, Optional -from datetime import datetime - -class UserProfile(BaseModel): - """User profile stored in DynamoDB""" - user_id: str = Field(..., alias="userId") - email: str - name: str - roles: List[str] = Field(default_factory=list) - picture: Optional[str] = None - email_domain: str = Field(..., alias="emailDomain") - created_at: str = Field(..., alias="createdAt") - last_login_at: str = Field(..., alias="lastLoginAt") - status: str = Field(default="active") - - @field_validator('email', mode='before') - @classmethod - def lowercase_email(cls, v: str) -> str: - return v.lower() if v else v - - @field_validator('email_domain', mode='before') - @classmethod - def lowercase_domain(cls, v: str) -> str: - return v.lower() if v else v - - class Config: - populate_by_name = True - - -class UserListItem(BaseModel): - """Minimal user info for list views""" - user_id: str = Field(..., alias="userId") - email: str - name: str - status: str - last_login_at: str = Field(..., alias="lastLoginAt") - email_domain: Optional[str] = Field(None, alias="emailDomain") - - -class UserDetailView(BaseModel): - """Comprehensive user view for admin detail page""" - profile: UserProfile - - # Cost summary (from UserCostSummary table) - current_month_cost: float = Field(0.0, alias="currentMonthCost") - current_month_requests: int = Field(0, alias="currentMonthRequests") - - # Quota status (from quota resolver) - quota_tier_name: Optional[str] = Field(None, alias="quotaTierName") - quota_matched_by: Optional[str] = Field(None, alias="quotaMatchedBy") - quota_limit: Optional[float] = Field(None, alias="quotaLimit") - quota_usage_percentage: float = Field(0.0, alias="quotaUsagePercentage") - quota_remaining: Optional[float] = Field(None, alias="quotaRemaining") - has_active_override: bool = Field(False, alias="hasActiveOverride") - - # Recent events (from QuotaEvents) - recent_events: List[dict] = Field(default_factory=list, alias="recentEvents") - - class Config: - populate_by_name = True -``` - -### Repository - -**File:** `backend/src/users/repository.py` - -```python -import logging -from typing import Optional, List, Tuple -from datetime import datetime -from botocore.exceptions import ClientError - -from .models import UserProfile, UserListItem - -logger = logging.getLogger(__name__) - - -class UserRepository: - """DynamoDB repository for user operations""" - - def __init__(self, dynamodb_client, table_name: str): - self._client = dynamodb_client - self._table_name = table_name - - # ========== Single User Operations ========== - - async def get_user(self, user_id: str) -> Optional[UserProfile]: - """ - Get user by ID using primary key. - Use this for internal operations where you have the full PK. - """ - try: - response = self._client.get_item( - TableName=self._table_name, - Key={ - "PK": {"S": f"USER#{user_id}"}, - "SK": {"S": "PROFILE"} - } - ) - item = response.get("Item") - if not item: - return None - return self._item_to_profile(item) - except ClientError as e: - logger.error(f"Error getting user {user_id}: {e}") - raise - - async def get_user_by_user_id(self, user_id: str) -> Optional[UserProfile]: - """ - Get user by userId attribute via UserIdIndex GSI. - Use this for admin deep links where you only have the raw user ID. - """ - try: - response = self._client.query( - TableName=self._table_name, - IndexName="UserIdIndex", - KeyConditionExpression="userId = :userId", - ExpressionAttributeValues={ - ":userId": {"S": user_id} - }, - Limit=1 - ) - items = response.get("Items", []) - if not items: - return None - return self._item_to_profile(items[0]) - except ClientError as e: - logger.error(f"Error getting user by userId {user_id}: {e}") - raise - - async def get_user_by_email(self, email: str) -> Optional[UserProfile]: - """Get user by email (case-insensitive)""" - try: - response = self._client.query( - TableName=self._table_name, - IndexName="EmailIndex", - KeyConditionExpression="email = :email", - ExpressionAttributeValues={ - ":email": {"S": email.lower()} - }, - Limit=1 - ) - items = response.get("Items", []) - if not items: - return None - return self._item_to_profile(items[0]) - except ClientError as e: - logger.error(f"Error getting user by email {email}: {e}") - raise - - async def create_user(self, profile: UserProfile) -> UserProfile: - """Create a new user""" - item = self._profile_to_item(profile) - try: - self._client.put_item( - TableName=self._table_name, - Item=item, - ConditionExpression="attribute_not_exists(PK)" - ) - return profile - except ClientError as e: - if e.response["Error"]["Code"] == "ConditionalCheckFailedException": - raise ValueError(f"User {profile.user_id} already exists") - logger.error(f"Error creating user: {e}") - raise - - async def update_user(self, user_id: str, profile: UserProfile) -> UserProfile: - """Update existing user""" - item = self._profile_to_item(profile) - try: - self._client.put_item( - TableName=self._table_name, - Item=item - ) - return profile - except ClientError as e: - logger.error(f"Error updating user {user_id}: {e}") - raise - - async def upsert_user(self, profile: UserProfile) -> Tuple[UserProfile, bool]: - """ - Create or update user. - Returns (profile, is_new_user) - """ - existing = await self.get_user(profile.user_id) - if existing: - # Preserve createdAt from existing record - profile.created_at = existing.created_at - await self.update_user(profile.user_id, profile) - return profile, False - else: - await self.create_user(profile) - return profile, True - - # ========== List Operations ========== - - async def list_users_by_domain( - self, - domain: str, - limit: int = 25, - last_evaluated_key: Optional[dict] = None - ) -> Tuple[List[UserListItem], Optional[dict]]: - """List users by email domain, sorted by last login (descending)""" - try: - kwargs = { - "TableName": self._table_name, - "IndexName": "EmailDomainIndex", - "KeyConditionExpression": "GSI2PK = :pk", - "ExpressionAttributeValues": { - ":pk": {"S": f"DOMAIN#{domain.lower()}"} - }, - "ScanIndexForward": False, # Most recent first - "Limit": limit - } - if last_evaluated_key: - kwargs["ExclusiveStartKey"] = last_evaluated_key - - response = self._client.query(**kwargs) - items = [self._item_to_list_item(item) for item in response.get("Items", [])] - next_key = response.get("LastEvaluatedKey") - return items, next_key - except ClientError as e: - logger.error(f"Error listing users by domain {domain}: {e}") - raise - - async def list_users_by_status( - self, - status: str = "active", - limit: int = 25, - last_evaluated_key: Optional[dict] = None - ) -> Tuple[List[UserListItem], Optional[dict]]: - """List users by status, sorted by last login (descending)""" - try: - kwargs = { - "TableName": self._table_name, - "IndexName": "StatusLoginIndex", - "KeyConditionExpression": "GSI3PK = :pk", - "ExpressionAttributeValues": { - ":pk": {"S": f"STATUS#{status}"} - }, - "ScanIndexForward": False, # Most recent first - "Limit": limit - } - if last_evaluated_key: - kwargs["ExclusiveStartKey"] = last_evaluated_key - - response = self._client.query(**kwargs) - items = [self._item_to_list_item(item) for item in response.get("Items", [])] - next_key = response.get("LastEvaluatedKey") - return items, next_key - except ClientError as e: - logger.error(f"Error listing users by status {status}: {e}") - raise - - # ========== Helpers ========== - - def _profile_to_item(self, profile: UserProfile) -> dict: - """Convert UserProfile to DynamoDB item""" - item = { - "PK": {"S": f"USER#{profile.user_id}"}, - "SK": {"S": "PROFILE"}, - "userId": {"S": profile.user_id}, - "email": {"S": profile.email.lower()}, - "name": {"S": profile.name}, - "roles": {"L": [{"S": r} for r in profile.roles]}, - "emailDomain": {"S": profile.email_domain.lower()}, - "createdAt": {"S": profile.created_at}, - "lastLoginAt": {"S": profile.last_login_at}, - "status": {"S": profile.status}, - # GSI keys - "GSI2PK": {"S": f"DOMAIN#{profile.email_domain.lower()}"}, - "GSI2SK": {"S": profile.last_login_at}, - "GSI3PK": {"S": f"STATUS#{profile.status}"}, - "GSI3SK": {"S": profile.last_login_at}, - } - if profile.picture: - item["picture"] = {"S": profile.picture} - return item - - def _item_to_profile(self, item: dict) -> UserProfile: - """Convert DynamoDB item to UserProfile""" - return UserProfile( - user_id=item["userId"]["S"], - email=item["email"]["S"], - name=item["name"]["S"], - roles=[r["S"] for r in item.get("roles", {}).get("L", [])], - picture=item.get("picture", {}).get("S"), - email_domain=item["emailDomain"]["S"], - created_at=item["createdAt"]["S"], - last_login_at=item["lastLoginAt"]["S"], - status=item.get("status", {}).get("S", "active") - ) - - def _item_to_list_item(self, item: dict) -> UserListItem: - """Convert DynamoDB item to UserListItem""" - return UserListItem( - user_id=item["userId"]["S"], - email=item["email"]["S"], - name=item["name"]["S"], - status=item.get("status", {}).get("S", "active"), - last_login_at=item["lastLoginAt"]["S"], - email_domain=item.get("emailDomain", {}).get("S") - ) -``` - -### User Sync Service - -**File:** `backend/src/users/sync.py` - -```python -import logging -from datetime import datetime -from typing import Tuple - -from .models import UserProfile -from .repository import UserRepository - -logger = logging.getLogger(__name__) - - -class UserSyncService: - """ - Syncs user data from JWT claims to DynamoDB. - Called on each login/token refresh. - """ - - def __init__(self, repository: UserRepository): - self._repository = repository - - async def sync_from_jwt(self, jwt_claims: dict) -> Tuple[UserProfile, bool]: - """ - Create or update user from JWT claims. - - Args: - jwt_claims: Decoded JWT payload containing user info - - Returns: - Tuple of (UserProfile, is_new_user) - """ - user_id = jwt_claims.get("sub") - if not user_id: - raise ValueError("JWT missing 'sub' claim") - - email = jwt_claims.get("email", "") - if not email: - raise ValueError("JWT missing 'email' claim") - - # Extract domain from email - email_domain = email.split("@")[1] if "@" in email else "" - - now = datetime.utcnow().isoformat() + "Z" - - # Build profile from JWT claims - profile = UserProfile( - user_id=user_id, - email=email.lower(), - name=jwt_claims.get("name", ""), - roles=jwt_claims.get("roles", []), - picture=jwt_claims.get("picture"), - email_domain=email_domain.lower(), - created_at=now, # Will be overwritten if user exists - last_login_at=now, - status="active" - ) - - # Upsert user - profile, is_new = await self._repository.upsert_user(profile) - - if is_new: - logger.info(f"Created new user: {user_id} ({email})") - else: - logger.debug(f"Updated user: {user_id} ({email})") - - return profile, is_new -``` - -### Admin API Routes - -**File:** `backend/src/apis/app_api/admin/users/routes.py` - -```python -from fastapi import APIRouter, Depends, HTTPException, Query -from typing import List, Optional - -from apis.shared.auth.dependencies import require_admin -from apis.shared.auth.models import User - -from .service import UserAdminService -from .models import ( - UserListResponse, - UserDetailResponse, - UserSearchQuery -) - -router = APIRouter(prefix="/users", tags=["Admin - Users"]) - - -def get_user_service() -> UserAdminService: - """Dependency to get UserAdminService instance""" - # Implementation depends on your DI setup - from apis.shared.dependencies import get_user_admin_service - return get_user_admin_service() - - -@router.get("", response_model=UserListResponse) -async def list_users( - status: str = Query("active", description="Filter by status"), - domain: Optional[str] = Query(None, description="Filter by email domain"), - limit: int = Query(25, ge=1, le=100), - cursor: Optional[str] = Query(None, description="Pagination cursor"), - admin_user: User = Depends(require_admin), - service: UserAdminService = Depends(get_user_service) -): - """ - List users with optional filters. - - - **status**: Filter by user status (active, inactive, suspended) - - **domain**: Filter by email domain (e.g., "example.com") - - **limit**: Number of results per page (1-100) - - **cursor**: Pagination cursor from previous response - """ - return await service.list_users( - status=status, - domain=domain, - limit=limit, - cursor=cursor - ) - - -@router.get("/search", response_model=UserListResponse) -async def search_users( - email: str = Query(..., description="Email to search (exact match)"), - admin_user: User = Depends(require_admin), - service: UserAdminService = Depends(get_user_service) -): - """ - Search for a user by exact email match. - """ - user = await service.search_by_email(email) - if not user: - return UserListResponse(users=[], next_cursor=None) - return UserListResponse(users=[user], next_cursor=None) - - -@router.get("/{user_id}", response_model=UserDetailResponse) -async def get_user_detail( - user_id: str, - admin_user: User = Depends(require_admin), - service: UserAdminService = Depends(get_user_service) -): - """ - Get comprehensive user detail including: - - Profile information - - Current month cost summary - - Quota status - - Recent quota events - """ - detail = await service.get_user_detail(user_id) - if not detail: - raise HTTPException(status_code=404, detail=f"User {user_id} not found") - return detail - - -@router.get("/domains/list", response_model=List[str]) -async def list_email_domains( - limit: int = Query(50, ge=1, le=200), - admin_user: User = Depends(require_admin), - service: UserAdminService = Depends(get_user_service) -): - """ - List distinct email domains with user counts. - Useful for domain filter dropdown. - """ - return await service.list_domains(limit=limit) -``` - -### Admin API Models - -**File:** `backend/src/apis/app_api/admin/users/models.py` - -```python -from pydantic import BaseModel, Field -from typing import List, Optional - - -class UserListItem(BaseModel): - """User item for list views""" - user_id: str = Field(..., alias="userId") - email: str - name: str - status: str - last_login_at: str = Field(..., alias="lastLoginAt") - email_domain: Optional[str] = Field(None, alias="emailDomain") - - # Quick stats (optional, populated for dashboard views) - current_month_cost: Optional[float] = Field(None, alias="currentMonthCost") - quota_usage_percentage: Optional[float] = Field(None, alias="quotaUsagePercentage") - - class Config: - populate_by_name = True - - -class UserListResponse(BaseModel): - """Paginated user list response""" - users: List[UserListItem] - next_cursor: Optional[str] = Field(None, alias="nextCursor") - total_count: Optional[int] = Field(None, alias="totalCount") - - class Config: - populate_by_name = True - - -class QuotaStatus(BaseModel): - """User's current quota status""" - tier_id: Optional[str] = Field(None, alias="tierId") - tier_name: Optional[str] = Field(None, alias="tierName") - matched_by: Optional[str] = Field(None, alias="matchedBy") - monthly_limit: Optional[float] = Field(None, alias="monthlyLimit") - current_usage: float = Field(0.0, alias="currentUsage") - usage_percentage: float = Field(0.0, alias="usagePercentage") - remaining: Optional[float] = None - has_active_override: bool = Field(False, alias="hasActiveOverride") - override_reason: Optional[str] = Field(None, alias="overrideReason") - - class Config: - populate_by_name = True - - -class CostSummary(BaseModel): - """User's current month cost summary""" - total_cost: float = Field(0.0, alias="totalCost") - total_requests: int = Field(0, alias="totalRequests") - total_input_tokens: int = Field(0, alias="totalInputTokens") - total_output_tokens: int = Field(0, alias="totalOutputTokens") - cache_savings: float = Field(0.0, alias="cacheSavings") - primary_model: Optional[str] = Field(None, alias="primaryModel") - - class Config: - populate_by_name = True - - -class QuotaEventSummary(BaseModel): - """Summary of a quota event""" - event_id: str = Field(..., alias="eventId") - event_type: str = Field(..., alias="eventType") - timestamp: str - percentage_used: float = Field(..., alias="percentageUsed") - - class Config: - populate_by_name = True - - -class UserProfile(BaseModel): - """Full user profile""" - user_id: str = Field(..., alias="userId") - email: str - name: str - roles: List[str] = Field(default_factory=list) - picture: Optional[str] = None - email_domain: str = Field(..., alias="emailDomain") - created_at: str = Field(..., alias="createdAt") - last_login_at: str = Field(..., alias="lastLoginAt") - status: str - - class Config: - populate_by_name = True - - -class UserDetailResponse(BaseModel): - """Comprehensive user detail for admin view""" - profile: UserProfile - cost_summary: CostSummary = Field(..., alias="costSummary") - quota_status: QuotaStatus = Field(..., alias="quotaStatus") - recent_events: List[QuotaEventSummary] = Field( - default_factory=list, - alias="recentEvents" - ) - - class Config: - populate_by_name = True -``` - -### Admin Service - -**File:** `backend/src/apis/app_api/admin/users/service.py` - -```python -import asyncio -import logging -import base64 -import json -from typing import Optional, List -from datetime import datetime - -from users.repository import UserRepository -from users.models import UserProfile, UserListItem -from apis.app_api.costs.aggregator import CostAggregator -from agents.main_agent.quota.resolver import QuotaResolver -from agents.main_agent.quota.repository import QuotaRepository -from apis.shared.auth.models import User - -from .models import ( - UserListResponse, - UserDetailResponse, - QuotaStatus, - CostSummary, - QuotaEventSummary -) - -logger = logging.getLogger(__name__) - - -class UserAdminService: - """Service for user admin operations""" - - def __init__( - self, - user_repository: UserRepository, - cost_aggregator: CostAggregator, - quota_resolver: QuotaResolver, - quota_repository: QuotaRepository - ): - self._user_repo = user_repository - self._cost_aggregator = cost_aggregator - self._quota_resolver = quota_resolver - self._quota_repo = quota_repository - - async def list_users( - self, - status: str = "active", - domain: Optional[str] = None, - limit: int = 25, - cursor: Optional[str] = None - ) -> UserListResponse: - """List users with filters and pagination""" - - # Decode cursor if provided - last_key = None - if cursor: - try: - last_key = json.loads(base64.b64decode(cursor).decode()) - except Exception: - pass - - # Query based on filters - if domain: - users, next_key = await self._user_repo.list_users_by_domain( - domain=domain, - limit=limit, - last_evaluated_key=last_key - ) - else: - users, next_key = await self._user_repo.list_users_by_status( - status=status, - limit=limit, - last_evaluated_key=last_key - ) - - # Encode next cursor - next_cursor = None - if next_key: - next_cursor = base64.b64encode(json.dumps(next_key).encode()).decode() - - return UserListResponse( - users=users, - next_cursor=next_cursor - ) - - async def search_by_email(self, email: str) -> Optional[UserListItem]: - """Search for user by exact email""" - profile = await self._user_repo.get_user_by_email(email) - if not profile: - return None - - return UserListItem( - user_id=profile.user_id, - email=profile.email, - name=profile.name, - status=profile.status, - last_login_at=profile.last_login_at, - email_domain=profile.email_domain - ) - - async def get_user_detail(self, user_id: str) -> Optional[UserDetailResponse]: - """ - Get comprehensive user detail. - Uses UserIdIndex GSI to support admin deep links by raw user ID. - """ - - # Get user profile using UserIdIndex (for deep link support) - profile = await self._user_repo.get_user_by_user_id(user_id) - if not profile: - return None - - # Parallel fetch of related data - current_period = datetime.utcnow().strftime("%Y-%m") - - # Create a mock User object for quota resolution - user = User( - user_id=profile.user_id, - email=profile.email, - name=profile.name, - roles=profile.roles - ) - - cost_summary_task = self._cost_aggregator.get_user_cost_summary( - user_id=user_id, - period=current_period - ) - quota_task = self._quota_resolver.resolve_user_quota(user) - events_task = self._quota_repo.list_user_events( - user_id=user_id, - limit=5 - ) - - # Await all in parallel - cost_data, resolved_quota, recent_events = await asyncio.gather( - cost_summary_task, - quota_task, - events_task, - return_exceptions=True - ) - - # Build cost summary - cost_summary = CostSummary(total_cost=0.0, total_requests=0) - if cost_data and not isinstance(cost_data, Exception): - cost_summary = CostSummary( - total_cost=cost_data.total_cost, - total_requests=cost_data.total_requests, - total_input_tokens=cost_data.total_input_tokens, - total_output_tokens=cost_data.total_output_tokens, - cache_savings=cost_data.total_cache_savings, - primary_model=self._get_primary_model(cost_data) - ) - - # Build quota status - quota_status = QuotaStatus() - if resolved_quota and not isinstance(resolved_quota, Exception): - tier = resolved_quota.tier - usage_pct = 0.0 - remaining = None - - if tier and tier.monthly_cost_limit and tier.monthly_cost_limit != float('inf'): - usage_pct = (cost_summary.total_cost / tier.monthly_cost_limit) * 100 - remaining = max(0, tier.monthly_cost_limit - cost_summary.total_cost) - - quota_status = QuotaStatus( - tier_id=tier.tier_id if tier else None, - tier_name=tier.tier_name if tier else None, - matched_by=resolved_quota.matched_by, - monthly_limit=tier.monthly_cost_limit if tier else None, - current_usage=cost_summary.total_cost, - usage_percentage=round(usage_pct, 1), - remaining=remaining, - has_active_override=resolved_quota.override is not None, - override_reason=resolved_quota.override.reason if resolved_quota.override else None - ) - - # Build event summaries - event_summaries = [] - if recent_events and not isinstance(recent_events, Exception): - for event in recent_events: - event_summaries.append(QuotaEventSummary( - event_id=event.event_id, - event_type=event.event_type, - timestamp=event.timestamp, - percentage_used=event.percentage_used - )) - - return UserDetailResponse( - profile=profile, - cost_summary=cost_summary, - quota_status=quota_status, - recent_events=event_summaries - ) - - async def list_domains(self, limit: int = 50) -> List[str]: - """ - List distinct email domains. - Note: This requires a scan or maintaining a separate domain list. - For now, return empty - implement if needed. - """ - # TODO: Implement domain listing - # Options: - # 1. Maintain a separate DOMAINS item updated on user create - # 2. Scan with projection (not recommended at scale) - # 3. Use application-level aggregation - return [] - - def _get_primary_model(self, cost_data) -> Optional[str]: - """Get the most-used model from cost data""" - if not cost_data or not cost_data.models: - return None - - # Find model with most requests - primary = max(cost_data.models, key=lambda m: m.request_count) - return primary.model_name if primary else None -``` - ---- - -## Frontend Implementation - -### Directory Structure - -``` -frontend/ai.client/src/app/admin/ -├── users/ -│ ├── models/ -│ │ └── user.models.ts -│ ├── services/ -│ │ ├── user-http.service.ts -│ │ └── user-state.service.ts -│ └── pages/ -│ ├── user-list/ -│ │ └── user-list.page.ts -│ └── user-detail/ -│ └── user-detail.page.ts -└── admin.page.ts # Add user lookup card -``` - -### TypeScript Models - -**File:** `frontend/ai.client/src/app/admin/users/models/user.models.ts` - -```typescript -export interface UserListItem { - userId: string; - email: string; - name: string; - status: 'active' | 'inactive' | 'suspended'; - lastLoginAt: string; - emailDomain?: string; - currentMonthCost?: number; - quotaUsagePercentage?: number; -} - -export interface UserListResponse { - users: UserListItem[]; - nextCursor?: string; - totalCount?: number; -} - -export interface QuotaStatus { - tierId?: string; - tierName?: string; - matchedBy?: string; - monthlyLimit?: number; - currentUsage: number; - usagePercentage: number; - remaining?: number; - hasActiveOverride: boolean; - overrideReason?: string; -} - -export interface CostSummary { - totalCost: number; - totalRequests: number; - totalInputTokens: number; - totalOutputTokens: number; - cacheSavings: number; - primaryModel?: string; -} - -export interface QuotaEventSummary { - eventId: string; - eventType: 'warning' | 'block' | 'reset' | 'override_applied'; - timestamp: string; - percentageUsed: number; -} - -export interface UserProfile { - userId: string; - email: string; - name: string; - roles: string[]; - picture?: string; - emailDomain: string; - createdAt: string; - lastLoginAt: string; - status: 'active' | 'inactive' | 'suspended'; -} - -export interface UserDetailResponse { - profile: UserProfile; - costSummary: CostSummary; - quotaStatus: QuotaStatus; - recentEvents: QuotaEventSummary[]; -} -``` - -### HTTP Service - -**File:** `frontend/ai.client/src/app/admin/users/services/user-http.service.ts` - -```typescript -import { Injectable, inject } from '@angular/core'; -import { HttpClient, HttpParams } from '@angular/common/http'; -import { Observable } from 'rxjs'; -import { environment } from '../../../../environments/environment'; -import { UserListResponse, UserDetailResponse } from '../models/user.models'; - -@Injectable({ - providedIn: 'root', -}) -export class UserHttpService { - private http = inject(HttpClient); - private baseUrl = `${environment.apiUrl}/api/admin/users`; - - listUsers( - status: string = 'active', - domain?: string, - limit: number = 25, - cursor?: string - ): Observable { - let params = new HttpParams() - .set('status', status) - .set('limit', limit.toString()); - - if (domain) { - params = params.set('domain', domain); - } - if (cursor) { - params = params.set('cursor', cursor); - } - - return this.http.get(this.baseUrl, { params }); - } - - searchByEmail(email: string): Observable { - const params = new HttpParams().set('email', email); - return this.http.get(`${this.baseUrl}/search`, { params }); - } - - getUserDetail(userId: string): Observable { - return this.http.get(`${this.baseUrl}/${userId}`); - } - - listDomains(limit: number = 50): Observable { - const params = new HttpParams().set('limit', limit.toString()); - return this.http.get(`${this.baseUrl}/domains/list`, { params }); - } -} -``` - -### State Service - -**File:** `frontend/ai.client/src/app/admin/users/services/user-state.service.ts` - -```typescript -import { Injectable, inject, signal, computed } from '@angular/core'; -import { UserHttpService } from './user-http.service'; -import { - UserListItem, - UserDetailResponse, -} from '../models/user.models'; - -@Injectable({ - providedIn: 'root', -}) -export class UserStateService { - private http = inject(UserHttpService); - - // State - users = signal([]); - selectedUser = signal(null); - loading = signal(false); - searchQuery = signal(''); - statusFilter = signal<'active' | 'inactive' | 'suspended'>('active'); - domainFilter = signal(null); - nextCursor = signal(null); - - // Computed - hasMore = computed(() => this.nextCursor() !== null); - userCount = computed(() => this.users().length); - - loadUsers(reset: boolean = false): void { - if (reset) { - this.users.set([]); - this.nextCursor.set(null); - } - - this.loading.set(true); - - this.http - .listUsers( - this.statusFilter(), - this.domainFilter() ?? undefined, - 25, - reset ? undefined : this.nextCursor() ?? undefined - ) - .subscribe({ - next: (response) => { - if (reset) { - this.users.set(response.users); - } else { - this.users.update((current) => [...current, ...response.users]); - } - this.nextCursor.set(response.nextCursor ?? null); - this.loading.set(false); - }, - error: () => this.loading.set(false), - }); - } - - searchByEmail(email: string): void { - this.loading.set(true); - this.searchQuery.set(email); - - this.http.searchByEmail(email).subscribe({ - next: (response) => { - this.users.set(response.users); - this.nextCursor.set(null); - this.loading.set(false); - }, - error: () => this.loading.set(false), - }); - } - - loadUserDetail(userId: string): void { - this.loading.set(true); - this.selectedUser.set(null); - - this.http.getUserDetail(userId).subscribe({ - next: (detail) => { - this.selectedUser.set(detail); - this.loading.set(false); - }, - error: () => this.loading.set(false), - }); - } - - clearSelection(): void { - this.selectedUser.set(null); - } - - setStatusFilter(status: 'active' | 'inactive' | 'suspended'): void { - this.statusFilter.set(status); - this.loadUsers(true); - } - - setDomainFilter(domain: string | null): void { - this.domainFilter.set(domain); - this.loadUsers(true); - } -} -``` - -### User List Page - -**File:** `frontend/ai.client/src/app/admin/users/pages/user-list/user-list.page.ts` - -```typescript -import { - Component, - ChangeDetectionStrategy, - inject, - OnInit, - signal, -} from '@angular/core'; -import { Router } from '@angular/router'; -import { FormsModule } from '@angular/forms'; -import { NgIcon, provideIcons } from '@ng-icons/core'; -import { - heroMagnifyingGlass, - heroUser, - heroChevronRight, -} from '@ng-icons/heroicons/outline'; -import { UserStateService } from '../../services/user-state.service'; -import { UserListItem } from '../../models/user.models'; - -@Component({ - selector: 'app-user-list', - changeDetection: ChangeDetectionStrategy.OnPush, - imports: [FormsModule, NgIcon], - providers: [ - provideIcons({ heroMagnifyingGlass, heroUser, heroChevronRight }), - ], - host: { - class: 'block p-6', - }, - template: ` -
-

User Lookup

-

- Search and browse users to view their profile, costs, and quota status. -

-
- - -
-
- - -
-
- - -
- -
- - - @if (state.loading() && state.users().length === 0) { -
Loading users...
- } - - -
- @for (user of state.users(); track user.userId) { -
- -
- -
- - -
-
- {{ user.email }} - @if (user.status !== 'active') { - - {{ user.status }} - - } -
-
- {{ user.name || 'No name' }} · Last login: - {{ formatDate(user.lastLoginAt) }} -
-
- - - @if (user.quotaUsagePercentage !== undefined) { -
-
- {{ user.quotaUsagePercentage }}% quota used -
- @if (user.currentMonthCost !== undefined) { -
- \${{ user.currentMonthCost.toFixed(2) }} this month -
- } -
- } - - -
- } -
- - - @if (state.users().length === 0 && !state.loading()) { -
- -

No users found

-

Try adjusting your search or filters

-
- } - - - @if (state.hasMore()) { -
- -
- } - `, -}) -export class UserListPage implements OnInit { - state = inject(UserStateService); - private router = inject(Router); - - searchEmail = ''; - - ngOnInit(): void { - this.state.loadUsers(true); - } - - search(): void { - if (this.searchEmail.trim()) { - this.state.searchByEmail(this.searchEmail.trim()); - } else { - this.state.loadUsers(true); - } - } - - viewUser(user: UserListItem): void { - this.router.navigate(['/admin/users', user.userId]); - } - - loadMore(): void { - this.state.loadUsers(false); - } - - formatDate(isoString: string): string { - const date = new Date(isoString); - const now = new Date(); - const diffMs = now.getTime() - date.getTime(); - const diffDays = Math.floor(diffMs / (1000 * 60 * 60 * 24)); - - if (diffDays === 0) { - return 'Today'; - } else if (diffDays === 1) { - return 'Yesterday'; - } else if (diffDays < 7) { - return `${diffDays} days ago`; - } else { - return date.toLocaleDateString(); - } - } -} -``` - -### User Detail Page - -**File:** `frontend/ai.client/src/app/admin/users/pages/user-detail/user-detail.page.ts` - -```typescript -import { - Component, - ChangeDetectionStrategy, - inject, - OnInit, - computed, -} from '@angular/core'; -import { ActivatedRoute, Router } from '@angular/router'; -import { NgIcon, provideIcons } from '@ng-icons/core'; -import { - heroArrowLeft, - heroUser, - heroCurrencyDollar, - heroChartBar, - heroShieldCheck, - heroExclamationTriangle, - heroClock, -} from '@ng-icons/heroicons/outline'; -import { UserStateService } from '../../services/user-state.service'; - -@Component({ - selector: 'app-user-detail', - changeDetection: ChangeDetectionStrategy.OnPush, - imports: [NgIcon], - providers: [ - provideIcons({ - heroArrowLeft, - heroUser, - heroCurrencyDollar, - heroChartBar, - heroShieldCheck, - heroExclamationTriangle, - heroClock, - }), - ], - host: { - class: 'block p-6', - }, - template: ` - - - - @if (state.loading()) { -
Loading user details...
- } - - @if (user(); as detail) { - -
- - @if (detail.profile.picture) { - - } @else { -
- -
- } - - -
-

{{ detail.profile.name || 'Unknown User' }}

-

{{ detail.profile.email }}

-
- ID: {{ detail.profile.userId }} - Domain: {{ detail.profile.emailDomain }} -
-
- @for (role of detail.profile.roles; track role) { - - {{ role }} - - } -
-
- - -
- - {{ detail.profile.status }} - -
-
- - -
- -
-
- -

Current Month Cost

-
-
- \${{ detail.costSummary.totalCost.toFixed(2) }} -
-
-
{{ detail.costSummary.totalRequests }} requests
-
- {{ formatTokens(detail.costSummary.totalInputTokens) }} input / - {{ formatTokens(detail.costSummary.totalOutputTokens) }} output tokens -
- @if (detail.costSummary.cacheSavings > 0) { -
- \${{ detail.costSummary.cacheSavings.toFixed(2) }} cache savings -
- } -
-
- - -
-
- -

Quota Status

-
- @if (detail.quotaStatus.tierName) { -
- {{ detail.quotaStatus.tierName }} - - ({{ detail.quotaStatus.matchedBy }}) - -
- -
-
- \${{ detail.quotaStatus.currentUsage.toFixed(2) }} - \${{ detail.quotaStatus.monthlyLimit?.toFixed(2) ?? '∞' }} -
-
-
-
-
- {{ detail.quotaStatus.usagePercentage.toFixed(1) }}% used - @if (detail.quotaStatus.remaining !== undefined) { - · \${{ detail.quotaStatus.remaining.toFixed(2) }} remaining - } -
-
- @if (detail.quotaStatus.hasActiveOverride) { -
- - - Override active: {{ detail.quotaStatus.overrideReason }} - -
- } - } @else { -
No quota assigned
- } -
- - -
-
- -

Activity

-
-
-
- Member since: - {{ formatFullDate(detail.profile.createdAt) }} -
-
- Last login: - {{ formatFullDate(detail.profile.lastLoginAt) }} -
- @if (detail.costSummary.primaryModel) { -
- Primary model: - {{ detail.costSummary.primaryModel }} -
- } -
-
-
- - -
-
-

Recent Quota Events

- -
- @if (detail.recentEvents.length > 0) { -
- @for (event of detail.recentEvents; track event.eventId) { -
- -
- {{ event.eventType }} - - at {{ event.percentageUsed.toFixed(0) }}% usage - -
- - {{ formatFullDate(event.timestamp) }} - -
- } -
- } @else { -
No recent events
- } -
- - -
- - - -
- } - `, -}) -export class UserDetailPage implements OnInit { - state = inject(UserStateService); - private route = inject(ActivatedRoute); - private router = inject(Router); - - user = computed(() => this.state.selectedUser()); - Math = Math; // Expose Math for template - - ngOnInit(): void { - const userId = this.route.snapshot.paramMap.get('userId'); - if (userId) { - this.state.loadUserDetail(userId); - } - } - - goBack(): void { - this.state.clearSelection(); - this.router.navigate(['/admin/users']); - } - - createOverride(): void { - const userId = this.user()?.profile.userId; - if (userId) { - this.router.navigate(['/admin/quota/overrides/new'], { - queryParams: { userId }, - }); - } - } - - assignTier(): void { - const userId = this.user()?.profile.userId; - if (userId) { - this.router.navigate(['/admin/quota/assignments/new'], { - queryParams: { userId, type: 'direct_user' }, - }); - } - } - - viewCostDetails(): void { - const userId = this.user()?.profile.userId; - if (userId) { - // Navigate to cost dashboard with user filter (if supported) - this.router.navigate(['/admin/costs'], { - queryParams: { userId }, - }); - } - } - - formatTokens(tokens: number): string { - if (tokens >= 1_000_000) { - return `${(tokens / 1_000_000).toFixed(1)}M`; - } else if (tokens >= 1_000) { - return `${(tokens / 1_000).toFixed(1)}K`; - } - return tokens.toString(); - } - - formatFullDate(isoString: string): string { - return new Date(isoString).toLocaleString(); - } -} -``` - ---- - -## User Sync Strategy - -### When to Sync - -User sync from JWT should occur: - -1. **On Login** - When user authenticates and receives new tokens -2. **On Token Refresh** - When refresh token is exchanged for new access token - -### Integration Point - -Modify the existing auth dependency to call sync: - -**File:** `backend/src/apis/shared/auth/dependencies.py` - -```python -from users.sync import UserSyncService -from users.repository import UserRepository - -# Initialize once -user_repo = UserRepository(dynamodb_client, table_name) -user_sync = UserSyncService(user_repo) - - -async def get_current_user( - token: str = Depends(oauth2_scheme) -) -> User: - """Validate JWT and sync user to database""" - # Validate JWT (existing logic) - claims = validate_jwt(token) - - # Sync user to database (fire-and-forget for performance) - try: - asyncio.create_task(user_sync.sync_from_jwt(claims)) - except Exception as e: - logger.warning(f"User sync failed: {e}") - # Don't fail the request if sync fails - - # Return user object - return User( - user_id=claims["sub"], - email=claims["email"], - name=claims.get("name", ""), - roles=claims.get("roles", []), - picture=claims.get("picture") - ) -``` - -### First-Time User Flow - -``` -1. User logs in for first time -2. JWT validated -3. sync_from_jwt() called -4. No existing user found -5. New user created with: - - createdAt = now - - lastLoginAt = now - - status = "active" -6. User record now in DynamoDB -``` - -### Returning User Flow - -``` -1. User logs in -2. JWT validated -3. sync_from_jwt() called -4. Existing user found -5. User updated with: - - lastLoginAt = now - - Other fields synced (name, roles, picture) - - createdAt preserved -6. User record updated -``` - ---- - -## Testing Strategy - -### Backend Unit Tests - -**File:** `backend/tests/users/test_repository.py` - -```python -import pytest -from users.repository import UserRepository -from users.models import UserProfile - -@pytest.mark.asyncio -async def test_create_and_get_user(user_repo): - """Test creating and retrieving a user""" - profile = UserProfile( - user_id="test-123", - email="test@example.com", - name="Test User", - roles=["user"], - email_domain="example.com", - created_at="2025-01-01T00:00:00Z", - last_login_at="2025-01-01T00:00:00Z", - status="active" - ) - - await user_repo.create_user(profile) - retrieved = await user_repo.get_user("test-123") - - assert retrieved is not None - assert retrieved.email == "test@example.com" - assert retrieved.status == "active" - - -@pytest.mark.asyncio -async def test_get_user_by_email_case_insensitive(user_repo): - """Test email lookup is case-insensitive""" - profile = UserProfile( - user_id="test-456", - email="Test.User@Example.COM", - name="Test User", - roles=[], - email_domain="example.com", - created_at="2025-01-01T00:00:00Z", - last_login_at="2025-01-01T00:00:00Z", - status="active" - ) - - await user_repo.create_user(profile) - - # Should find with lowercase - retrieved = await user_repo.get_user_by_email("test.user@example.com") - assert retrieved is not None - assert retrieved.user_id == "test-456" - - -@pytest.mark.asyncio -async def test_list_users_by_domain(user_repo): - """Test listing users by email domain""" - # Create users in different domains - for i, domain in enumerate(["example.com", "example.com", "other.com"]): - profile = UserProfile( - user_id=f"user-{i}", - email=f"user{i}@{domain}", - name=f"User {i}", - roles=[], - email_domain=domain, - created_at="2025-01-01T00:00:00Z", - last_login_at=f"2025-01-0{i+1}T00:00:00Z", - status="active" - ) - await user_repo.create_user(profile) - - users, _ = await user_repo.list_users_by_domain("example.com") - assert len(users) == 2 -``` - -### Frontend Tests - -**File:** `frontend/ai.client/src/app/admin/users/services/user-http.service.spec.ts` - -```typescript -import { TestBed } from '@angular/core/testing'; -import { - HttpClientTestingModule, - HttpTestingController, -} from '@angular/common/http/testing'; -import { UserHttpService } from './user-http.service'; - -describe('UserHttpService', () => { - let service: UserHttpService; - let httpMock: HttpTestingController; - - beforeEach(() => { - TestBed.configureTestingModule({ - imports: [HttpClientTestingModule], - providers: [UserHttpService], - }); - - service = TestBed.inject(UserHttpService); - httpMock = TestBed.inject(HttpTestingController); - }); - - afterEach(() => { - httpMock.verify(); - }); - - it('should list users with status filter', () => { - const mockResponse = { - users: [{ userId: '123', email: 'test@example.com', name: 'Test', status: 'active' }], - nextCursor: null, - }; - - service.listUsers('active').subscribe((response) => { - expect(response.users.length).toBe(1); - expect(response.users[0].userId).toBe('123'); - }); - - const req = httpMock.expectOne((r) => r.url.includes('/api/admin/users')); - expect(req.request.params.get('status')).toBe('active'); - req.flush(mockResponse); - }); - - it('should search by email', () => { - service.searchByEmail('test@example.com').subscribe(); - - const req = httpMock.expectOne((r) => r.url.includes('/search')); - expect(req.request.params.get('email')).toBe('test@example.com'); - req.flush({ users: [], nextCursor: null }); - }); -}); -``` - ---- - -## Deployment Plan - -### 1. Infrastructure (DynamoDB Table) - -#### Option A: AWS CLI (Manual) - -```bash -aws dynamodb create-table \ - --table-name Users \ - --attribute-definitions \ - AttributeName=PK,AttributeType=S \ - AttributeName=SK,AttributeType=S \ - AttributeName=userId,AttributeType=S \ - AttributeName=email,AttributeType=S \ - AttributeName=GSI2PK,AttributeType=S \ - AttributeName=GSI2SK,AttributeType=S \ - AttributeName=GSI3PK,AttributeType=S \ - AttributeName=GSI3SK,AttributeType=S \ - --key-schema \ - AttributeName=PK,KeyType=HASH \ - AttributeName=SK,KeyType=RANGE \ - --global-secondary-indexes \ - '[ - { - "IndexName": "UserIdIndex", - "KeySchema": [{"AttributeName": "userId", "KeyType": "HASH"}], - "Projection": {"ProjectionType": "ALL"} - }, - { - "IndexName": "EmailIndex", - "KeySchema": [{"AttributeName": "email", "KeyType": "HASH"}], - "Projection": {"ProjectionType": "ALL"} - }, - { - "IndexName": "EmailDomainIndex", - "KeySchema": [ - {"AttributeName": "GSI2PK", "KeyType": "HASH"}, - {"AttributeName": "GSI2SK", "KeyType": "RANGE"} - ], - "Projection": { - "ProjectionType": "INCLUDE", - "NonKeyAttributes": ["userId", "email", "name", "status"] - } - }, - { - "IndexName": "StatusLoginIndex", - "KeySchema": [ - {"AttributeName": "GSI3PK", "KeyType": "HASH"}, - {"AttributeName": "GSI3SK", "KeyType": "RANGE"} - ], - "Projection": { - "ProjectionType": "INCLUDE", - "NonKeyAttributes": ["userId", "email", "name", "emailDomain"] - } - } - ]' \ - --billing-mode PAY_PER_REQUEST -``` - -#### Option B: CDK (Recommended) - -**File:** `infrastructure/lib/app-api-stack.ts` - -Add the Users table after the existing Managed Models table section (~line 520): - -```typescript -// ============================================================ -// Users Table (User Admin) -// ============================================================ - -// Users Table - User profiles synced from JWT for admin lookup -const usersTable = new dynamodb.Table(this, 'UsersTable', { - tableName: getResourceName(config, 'users'), - partitionKey: { - name: 'PK', - type: dynamodb.AttributeType.STRING, - }, - sortKey: { - name: 'SK', - type: dynamodb.AttributeType.STRING, - }, - billingMode: dynamodb.BillingMode.PAY_PER_REQUEST, - pointInTimeRecovery: true, - removalPolicy: config.environment === 'prod' - ? cdk.RemovalPolicy.RETAIN - : cdk.RemovalPolicy.DESTROY, - encryption: dynamodb.TableEncryption.AWS_MANAGED, -}); - -// UserIdIndex - O(1) lookup by userId for admin deep links -usersTable.addGlobalSecondaryIndex({ - indexName: 'UserIdIndex', - partitionKey: { - name: 'userId', - type: dynamodb.AttributeType.STRING, - }, - projectionType: dynamodb.ProjectionType.ALL, -}); - -// EmailIndex - O(1) lookup by email -usersTable.addGlobalSecondaryIndex({ - indexName: 'EmailIndex', - partitionKey: { - name: 'email', - type: dynamodb.AttributeType.STRING, - }, - projectionType: dynamodb.ProjectionType.ALL, -}); - -// EmailDomainIndex - Browse users by company/domain -usersTable.addGlobalSecondaryIndex({ - indexName: 'EmailDomainIndex', - partitionKey: { - name: 'GSI2PK', - type: dynamodb.AttributeType.STRING, - }, - sortKey: { - name: 'GSI2SK', - type: dynamodb.AttributeType.STRING, - }, - projectionType: dynamodb.ProjectionType.INCLUDE, - nonKeyAttributes: ['userId', 'email', 'name', 'status'], -}); - -// StatusLoginIndex - Browse users by status, sorted by last login -usersTable.addGlobalSecondaryIndex({ - indexName: 'StatusLoginIndex', - partitionKey: { - name: 'GSI3PK', - type: dynamodb.AttributeType.STRING, - }, - sortKey: { - name: 'GSI3SK', - type: dynamodb.AttributeType.STRING, - }, - projectionType: dynamodb.ProjectionType.INCLUDE, - nonKeyAttributes: ['userId', 'email', 'name', 'emailDomain'], -}); - -// Store users table name in SSM -new ssm.StringParameter(this, 'UsersTableNameParameter', { - parameterName: `/${config.projectPrefix}/users/users-table-name`, - stringValue: usersTable.tableName, - description: 'Users table name for admin user lookup', - tier: ssm.ParameterTier.STANDARD, -}); - -new ssm.StringParameter(this, 'UsersTableArnParameter', { - parameterName: `/${config.projectPrefix}/users/users-table-arn`, - stringValue: usersTable.tableArn, - description: 'Users table ARN', - tier: ssm.ParameterTier.STANDARD, -}); -``` - -**Add to ECS container environment variables** (~line 555-567): - -```typescript -environment: { - // ... existing environment variables ... - DYNAMODB_USERS_TABLE_NAME: usersTable.tableName, -}, -``` - -**Grant permissions to ECS task role** (~line 600): - -```typescript -// Grant permissions for users table -usersTable.grantReadWriteData(taskDefinition.taskRole); -``` - -**Add CloudFormation output** (~line 730): - -```typescript -new cdk.CfnOutput(this, 'UsersTableName', { - value: usersTable.tableName, - description: 'Users table name for admin user lookup', - exportName: `${config.projectPrefix}-UsersTableName`, -}); -``` - -### 2. Environment Configuration - -**File:** `backend/src/.env.example` - -Add after the existing quota table configuration (~line 160): - -```bash -# ============================================================================= -# USER ADMIN CONFIGURATION -# ============================================================================= - -# DynamoDB table for user profiles (OPTIONAL - User Admin) -# Purpose: Store user profiles synced from JWT for admin user lookup -# Local Development: Leave empty to disable user sync (admin user lookup disabled) -# Production: Set to your DynamoDB table name for admin user management -# Schema: PK=USER#, SK=PROFILE -# GSIs: UserIdIndex (deep links), EmailIndex (search), EmailDomainIndex, StatusLoginIndex -# Features: JWT sync on login, admin deep links from cost dashboard -# CDK Deployment: See infrastructure/lib/app-api-stack.ts -# Example: Users-dev -DYNAMODB_USERS_TABLE_NAME= -``` - -### 3. Backend Deployment - -```bash -# Add environment variable -export DYNAMODB_USERS_TABLE_NAME=Users - -# Deploy backend -cd backend -docker build -t backend:user-admin . -docker push backend:user-admin -``` - -### 4. Frontend Deployment - -```bash -cd frontend/ai.client - -# Add routes to admin module -# Build and deploy -npm run build -- --configuration=production -aws s3 sync dist/ai-client s3://your-bucket/ -``` - -### 5. Verification - -```bash -# Test user sync -curl -X POST http://localhost:8000/api/chat \ - -H "Authorization: Bearer $TOKEN" \ - -d '{"message": "hello"}' - -# Verify user was created -aws dynamodb get-item \ - --table-name Users \ - --key '{"PK": {"S": "USER#your-user-id"}, "SK": {"S": "PROFILE"}}' - -# Test admin API -curl http://localhost:8000/api/admin/users \ - -H "Authorization: Bearer $ADMIN_TOKEN" -``` - ---- - -## Validation Criteria - -### Backend - -- [ ] Users table created with correct schema -- [ ] All 4 GSIs created and queryable (UserIdIndex, EmailIndex, EmailDomainIndex, StatusLoginIndex) -- [ ] User sync creates new users on first login -- [ ] User sync updates existing users on subsequent logins -- [ ] `lastLoginAt` updated correctly -- [ ] `createdAt` preserved on updates -- [ ] Email stored and queried as lowercase -- [ ] List by domain returns users sorted by lastLoginAt -- [ ] List by status returns users sorted by lastLoginAt -- [ ] Search by email is case-insensitive -- [ ] User detail aggregates data from multiple tables -- [ ] Admin endpoints require admin role - -### Frontend - -- [ ] User list displays with pagination -- [ ] Search by email works -- [ ] Status filter works -- [ ] Domain filter works (if implemented) -- [ ] User detail shows profile, cost, quota, events -- [ ] Admin actions navigate to correct pages -- [ ] Loading states display correctly -- [ ] Empty states display correctly - -### Integration - -- [ ] End-to-end: Login → User created → Admin can view -- [ ] End-to-end: User with cost → Detail shows correct cost -- [ ] End-to-end: User with quota → Detail shows correct quota -- [ ] End-to-end: Create override from user detail - ---- - -## Future Enhancements - -1. **Full-Text Search** - Integrate OpenSearch for name/email partial matching -2. **User Suspension** - Add suspend/unsuspend functionality -3. **Bulk Operations** - Export users, bulk tier assignment -4. **Usage Analytics** - Trends, graphs, comparisons -5. **Session History** - View user's conversation sessions -6. **Audit Logging** - Track admin actions on users - ---- - -**End of Specification** diff --git a/docs/specs/USER_COST_TRACKING_SPEC.md b/docs/specs/USER_COST_TRACKING_SPEC.md deleted file mode 100644 index 2a3d9f6f..00000000 --- a/docs/specs/USER_COST_TRACKING_SPEC.md +++ /dev/null @@ -1,2193 +0,0 @@ -# User Cost Tracking Specification - -## Executive Summary - -This specification outlines a comprehensive approach to accurately track user inference costs based on model usage, including token caching considerations. The system will capture token usage and pricing data at the point of inference, store it in DynamoDB for production (local files for development), and provide high-performance aggregation capabilities for future quota implementation. - -**Production Target**: Scale to 10,000+ monthly active users with sub-100ms query performance. - -**Note**: This application has not yet been deployed to production, so no migration strategy is required. All cost tracking features will be implemented as part of the initial production deployment. - -## Table of Contents - -1. [Architecture Overview](#architecture-overview) -2. [Current Infrastructure Analysis](#current-infrastructure-analysis) -3. [Data Models](#data-models) -4. [Cost Capture Strategy](#cost-capture-strategy) -5. [Storage Architecture](#storage-architecture) -6. [Token Caching Considerations](#token-caching-considerations) -7. [Cost Calculation](#cost-calculation) -8. [Aggregation & Querying](#aggregation--querying) -9. [Future: Quota Implementation](#future-quota-implementation) -10. [Implementation Plan](#implementation-plan) - ---- - -## Architecture Overview - -### Current Flow - -``` -User Request - ↓ -FastAPI Endpoint (inference_api/chat/routes.py) - ↓ -get_agent() (chat/service.py) - Creates MainAgent with model config - ↓ -StreamCoordinator.stream_response() (streaming/stream_coordinator.py) - ↓ -process_agent_stream() (streaming/stream_processor.py) - Extracts metadata - ↓ -_store_message_metadata() (stream_coordinator.py:146-155) - Stores metadata - ↓ -Storage Layer (DynamoDB in production, local files in development) -``` - -### Key Capture Points - -1. **Model Configuration**: Captured at agent creation (`chat/service.py:99-109`) -2. **Token Usage**: Extracted from stream events (`stream_processor.py:844-1088`) -3. **Pricing Data**: Available from managed models (`admin/models.py:147-168`) -4. **User Attribution**: Available from JWT authentication (`auth/dependencies.py`) - ---- - -## Current Infrastructure Analysis - -### Existing Components ✅ - -#### 1. Token Usage Tracking (Already Implemented) -- **Location**: `backend/src/agents/main_agent/streaming/stream_processor.py:844-1088` -- **Functionality**: Extracts token usage from model metadata events -- **Data Captured**: - - `inputTokens` - Standard input tokens - - `outputTokens` - Standard output tokens - - `totalTokens` - Sum of input + output - - `cacheReadInputTokens` - Tokens read from cache (90% discount) - - `cacheWriteInputTokens` - Tokens written to cache (25% markup) - -#### 2. Model Pricing (Partially Implemented) -- **Location**: `backend/src/apis/app_api/admin/models.py:107-168` -- **Managed Model Data**: - - `input_price_per_million_tokens` - - `output_price_per_million_tokens` - - Model metadata (provider, name, id) - -**Gap**: No cache pricing in managed models (exists in `costs/pricing_config.py` for Bedrock only) - -#### 3. Message Metadata Storage (Already Implemented) -- **Location**: `backend/src/apis/app_api/messages/models.py:74-84` -- **Storage Path**: `sessions/session_{id}/message-metadata.json` -- **Current Structure**: - ```python - { - "latency": { "timeToFirstToken": int, "endToEndLatency": int }, - "token_usage": { "inputTokens": int, "outputTokens": int, ... }, - "model_info": { "modelId": str, "modelName": str, ... }, - "attribution": { "userId": str, "sessionId": str, "timestamp": str } - } - ``` - -**Gap**: Missing `pricing_snapshot` in stored metadata - -#### 4. User Authentication (Already Implemented) -- **Location**: `backend/src/apis/shared/auth/dependencies.py` -- **Provides**: `user_id`, `email`, `roles` from JWT - -### Missing Components ❌ - -1. **Cache Pricing in Managed Models**: Need to add cache pricing fields -2. **Pricing Snapshot**: Need to capture pricing at request time -3. **Cost Calculation**: Need service to calculate cost from usage + pricing -4. **User Cost Aggregation**: Need database/service for aggregating user costs -5. **Multi-Provider Pricing**: OpenAI and Gemini pricing not yet configured - ---- - -## Data Models - -### 1. Enhanced ManagedModel (Update Required) - -**File**: `backend/src/apis/app_api/admin/models.py` - -```python -class ManagedModel(BaseModel): - """Managed model with full details including cache pricing""" - model_config = ConfigDict(populate_by_name=True) - - id: str - model_id: str = Field(..., alias="modelId") - model_name: str = Field(..., alias="modelName") - provider: str - provider_name: str = Field(..., alias="providerName") - - # Token limits - max_input_tokens: int = Field(..., alias="maxInputTokens") - max_output_tokens: int = Field(..., alias="maxOutputTokens") - - # Standard pricing - input_price_per_million_tokens: float = Field(..., alias="inputPricePerMillionTokens") - output_price_per_million_tokens: float = Field(..., alias="outputPricePerMillionTokens") - - # ✨ NEW: Cache pricing (for providers that support it) - cache_write_price_per_million_tokens: Optional[float] = Field( - None, - alias="cacheWritePricePerMillionTokens", - description="Price per million tokens written to cache (Bedrock only, ~25% markup)" - ) - cache_read_price_per_million_tokens: Optional[float] = Field( - None, - alias="cacheReadPricePerMillionTokens", - description="Price per million tokens read from cache (Bedrock only, ~90% discount)" - ) - - # Other fields... - available_to_roles: List[str] = Field(..., alias="availableToRoles") - enabled: bool - is_reasoning_model: bool = Field(..., alias="isReasoningModel") - knowledge_cutoff_date: Optional[str] = Field(None, alias="knowledgeCutoffDate") - created_at: datetime = Field(..., alias="createdAt") - updated_at: datetime = Field(..., alias="updatedAt") -``` - -### 2. Enhanced PricingSnapshot (Update Required) - -**File**: `backend/src/apis/app_api/messages/models.py` - -```python -class PricingSnapshot(BaseModel): - """Pricing rates at time of request for historical accuracy""" - model_config = ConfigDict(populate_by_name=True) - - # Standard pricing - input_price_per_mtok: float = Field(..., alias="inputPricePerMtok") - output_price_per_mtok: float = Field(..., alias="outputPricePerMtok") - - # ✨ NEW: Cache pricing - cache_write_price_per_mtok: Optional[float] = Field( - None, - alias="cacheWritePricePerMtok", - description="Cache write pricing (Bedrock only)" - ) - cache_read_price_per_mtok: Optional[float] = Field( - None, - alias="cacheReadPricePerMtok", - description="Cache read pricing (Bedrock only)" - ) - - currency: str = Field(default="USD") - snapshot_at: str = Field(..., alias="snapshotAt", description="ISO timestamp when pricing was captured") -``` - -### 3. Enhanced MessageMetadata (Update Required) - -**File**: `backend/src/apis/app_api/messages/models.py` - -```python -class MessageMetadata(BaseModel): - """Metadata associated with a single message""" - model_config = ConfigDict(populate_by_name=True, extra='allow') - - latency: Optional[LatencyMetrics] = Field(None) - token_usage: Optional[TokenUsage] = Field(None, alias="tokenUsage") - model_info: Optional[ModelInfo] = Field(None, alias="modelInfo") - attribution: Optional[Attribution] = Field(None) - - # ✨ NEW: Calculated cost (computed from usage + pricing snapshot) - cost: Optional[float] = Field( - None, - description="Total cost in USD for this message (computed from token usage and pricing)" - ) -``` - -### 4. NEW: UserCostSummary (Create) - -**File**: `backend/src/apis/app_api/costs/models.py` (new file) - -```python -from pydantic import BaseModel, Field, ConfigDict -from typing import Optional, Dict, Any -from datetime import datetime - - -class CostBreakdown(BaseModel): - """Detailed cost breakdown by token type""" - model_config = ConfigDict(populate_by_name=True) - - input_cost: float = Field(..., alias="inputCost", description="Cost from input tokens") - output_cost: float = Field(..., alias="outputCost", description="Cost from output tokens") - cache_write_cost: float = Field(0.0, alias="cacheWriteCost", description="Cost from cache writes") - cache_read_cost: float = Field(0.0, alias="cacheReadCost", description="Cost from cache reads") - total_cost: float = Field(..., alias="totalCost", description="Total cost (sum of all)") - - -class ModelCostSummary(BaseModel): - """Cost summary for a specific model""" - model_config = ConfigDict(populate_by_name=True) - - model_id: str = Field(..., alias="modelId") - model_name: str = Field(..., alias="modelName") - provider: str - - # Token usage - total_input_tokens: int = Field(..., alias="totalInputTokens") - total_output_tokens: int = Field(..., alias="totalOutputTokens") - total_cache_read_tokens: int = Field(0, alias="totalCacheReadTokens") - total_cache_write_tokens: int = Field(0, alias="totalCacheWriteTokens") - - # Cost - cost_breakdown: CostBreakdown = Field(..., alias="costBreakdown") - - # Stats - request_count: int = Field(..., alias="requestCount", description="Number of requests using this model") - - -class UserCostSummary(BaseModel): - """Aggregated cost summary for a user""" - model_config = ConfigDict(populate_by_name=True) - - user_id: str = Field(..., alias="userId") - - # Time range - period_start: str = Field(..., alias="periodStart", description="ISO timestamp of period start") - period_end: str = Field(..., alias="periodEnd", description="ISO timestamp of period end") - - # Aggregate costs - total_cost: float = Field(..., alias="totalCost", description="Total cost across all models") - - # Per-model breakdown - models: list[ModelCostSummary] = Field( - default_factory=list, - description="Cost breakdown by model" - ) - - # Overall token usage - total_requests: int = Field(..., alias="totalRequests") - total_input_tokens: int = Field(..., alias="totalInputTokens") - total_output_tokens: int = Field(..., alias="totalOutputTokens") - total_cache_savings: float = Field( - 0.0, - alias="totalCacheSavings", - description="Total cost saved from cache hits" - ) -``` - ---- - -## Cost Capture Strategy - -### Point of Capture: Stream Coordinator - -**Location**: `backend/src/agents/main_agent/streaming/stream_coordinator.py` - -The stream coordinator already stores message metadata after streaming completes. We enhance this to include pricing and cost calculation. - -#### Current Flow (Line 134-155) - -```python -# Store metadata after flush completes -if message_id is not None: - # Always update session metadata - await self._update_session_metadata(...) - - # Store message-level metadata only if we have usage or timing data - if accumulated_metadata.get("usage") or first_token_time: - await self._store_message_metadata( - session_id=session_id, - user_id=user_id, - message_id=message_id, - accumulated_metadata=accumulated_metadata, - stream_start_time=stream_start_time, - stream_end_time=stream_end_time, - first_token_time=first_token_time, - agent=main_agent_wrapper - ) -``` - -#### Enhanced Flow (Proposed) - -```python -# Store metadata after flush completes -if message_id is not None: - # Always update session metadata - await self._update_session_metadata(...) - - # Store message-level metadata with cost calculation - if accumulated_metadata.get("usage") or first_token_time: - # ✨ NEW: Get pricing snapshot at time of request - pricing_snapshot = await self._get_pricing_snapshot( - agent=main_agent_wrapper - ) - - # ✨ NEW: Calculate cost from usage + pricing - cost = self._calculate_message_cost( - usage=accumulated_metadata.get("usage", {}), - pricing=pricing_snapshot - ) - - await self._store_message_metadata( - session_id=session_id, - user_id=user_id, - message_id=message_id, - accumulated_metadata=accumulated_metadata, - stream_start_time=stream_start_time, - stream_end_time=stream_end_time, - first_token_time=first_token_time, - agent=main_agent_wrapper, - pricing_snapshot=pricing_snapshot, # ✨ NEW - cost=cost # ✨ NEW - ) -``` - -### Why This Approach? - -1. **Accuracy**: Captures pricing at exact time of inference -2. **Single Source of Truth**: Reuses existing metadata storage -3. **Historical Accuracy**: Pricing snapshot allows accurate historical cost calculation even after price changes -4. **Minimal Changes**: Builds on existing infrastructure -5. **Performance**: Cost calculated once at write time, not on every read - ---- - -## Storage Architecture - -### Overview - -**Development Environment**: Local file storage (existing implementation) -**Production Environment**: DynamoDB with optimized schema for cost tracking - -### Local Storage (Development Only) - -**Path**: `sessions/session_{id}/message-metadata.json` - -**Structure** (Enhanced with cost tracking): -```json -{ - "0": { - "latency": { "timeToFirstToken": 250, "endToEndLatency": 1500 }, - "tokenUsage": { - "inputTokens": 1000, - "outputTokens": 500, - "totalTokens": 1500, - "cacheReadInputTokens": 200, - "cacheWriteInputTokens": 100 - }, - "modelInfo": { - "modelId": "us.anthropic.claude-sonnet-4-5-20250929-v1:0", - "modelName": "Claude 3.5 Sonnet", - "modelVersion": "v2", - "pricingSnapshot": { - "inputPricePerMtok": 3.0, - "outputPricePerMtok": 15.0, - "cacheWritePricePerMtok": 3.75, - "cacheReadPricePerMtok": 0.30, - "currency": "USD", - "snapshotAt": "2025-01-15T10:30:00Z" - } - }, - "attribution": { - "userId": "user_123", - "sessionId": "abc-def-ghi", - "timestamp": "2025-01-15T10:30:00Z" - }, - "cost": 0.0234 - } -} -``` - -**Purpose**: Fast local development without AWS dependencies - ---- - -### Production Storage (DynamoDB) - -#### Architecture Overview - -**AgentCore Memory** (managed by AWS) handles session and message storage: -- Sessions managed via AgentCore Memory API -- Messages stored in AgentCore Memory -- Accessed via existing endpoints: `GET /sessions`, `GET /sessions/{id}/messages` - -**Our Cost Tracking Tables**: -1. **SessionsMetadata** - Message-level metadata (cost, tokens, latency) -2. **UserCostSummary** - Pre-aggregated costs for fast quota checks - -**Separation of Concerns**: -- AgentCore Memory = Session/message **content** (what was said) -- SessionsMetadata = Message **metadata** (cost, performance) -- UserCostSummary = Aggregated **cost summaries** (billing, quotas) - -**Environment Configuration** (`.env`): -```bash -# Message Metadata Storage (cost tracking per message) -# AgentCore Memory manages sessions/messages, we store additional metadata -DYNAMODB_SESSIONS_METADATA_TABLE_NAME=SessionsMetadata - -# Cost Summary Storage (separate table for aggregation) -DYNAMODB_COST_SUMMARY_TABLE_NAME=UserCostSummary # For quota checks and dashboards -``` - ---- - -#### Table 1: SessionsMetadata - -**Purpose**: Store message-level metadata (cost, tokens, latency) for messages managed by AgentCore Memory - -**Key Concept**: -- Sessions and messages are in AgentCore Memory (AWS managed) -- This table stores **metadata about those messages** (cost tracking) -- Linked via `sessionId` + `messageId` references - -**Schema**: - -```python -{ - # Primary Key - "PK": "USER#alice", # Partition key - "SK": "SESSION#abc123#MSG#00005", # Sort key (session + message reference) - - # References (to AgentCore Memory) - "userId": "alice", - "sessionId": "abc123", # Links to AgentCore Memory session - "messageId": 5, # Links to AgentCore Memory message - "timestamp": "2025-01-15T10:30:45.123Z", - "ttl": 1768118400, # Auto-delete after 365 days (matches AgentCore Memory retention) - - # Cost & Usage - "cost": 0.0234, # Decimal - "inputTokens": 1000, - "outputTokens": 500, - "cacheReadTokens": 200, - "cacheWriteTokens": 100, - "totalTokens": 1500, - - # Model Info - "modelId": "us.anthropic.claude-sonnet-4-5-20250929-v1:0", - "modelName": "Claude 3.5 Sonnet", - "provider": "bedrock", - - # Pricing Snapshot (for historical accuracy) - "pricingSnapshot": { - "inputPricePerMtok": 3.0, - "outputPricePerMtok": 15.0, - "cacheReadPricePerMtok": 0.30, - "cacheWritePricePerMtok": 3.75, - "currency": "USD", - "snapshotAt": "2025-01-15T10:30:45.123Z" - }, - - # Latency - "timeToFirstToken": 250, # milliseconds - "endToEndLatency": 1500, # milliseconds - - # Additional metadata - "organizationId": "org_abc", # Future: multi-tenant - "tags": { # Future: cost allocation - "project": "marketing-bot", - "department": "sales" - } -} -``` - -**Indexes**: - -**Primary Index**: -- `PK` = `USER#` (Partition Key) -- `SK` = `SESSION##MSG#` (Sort Key) - -**GSI 1: UserTimestampIndex** (for time-range queries) -- `GSI1PK` = `USER#` (Partition Key) -- `GSI1SK` = `` (Sort Key) -- **Projection**: ALL -- **Use Cases**: - - Get all message metadata in date range for cost reports - - Generate billing period summaries - - Analytics queries - -**GSI 2: ModelUsageIndex** (for model analytics - optional) -- `GSI2PK` = `MODEL#` (Partition Key) -- `GSI2SK` = `` (Sort Key) -- **Projection**: KEYS_ONLY + cost, tokens -- **Use Cases**: - - Track which models are most used - - Calculate total cost per model across all users - - Pricing optimization analysis - -**Access Patterns**: - -```python -# 1. Get message metadata for a specific message -get_item( - Key={ - "PK": "USER#alice", - "SK": "SESSION#abc123#MSG#00005" - } -) - -# 2. Get all message metadata for a session -query( - KeyConditionExpression="PK = :user AND begins_with(SK, :session_prefix)", - ExpressionAttributeValues={ - ":user": "USER#alice", - ":session_prefix": "SESSION#abc123#MSG#" - } -) - -# 3. Get user message metadata in date range (via GSI1) -query( - IndexName="UserTimestampIndex", - KeyConditionExpression="GSI1PK = :user AND GSI1SK BETWEEN :start AND :end", - ExpressionAttributeValues={ - ":user": "USER#alice", - ":start": "2025-01-01T00:00:00Z", - ":end": "2025-01-31T23:59:59Z" - } -) - -# 4. Write message metadata after streaming completes -put_item( - Item={ - "PK": "USER#alice", - "SK": "SESSION#abc123#MSG#00005", - "userId": "alice", - "sessionId": "abc123", # Reference to AgentCore Memory session - "messageId": 5, # Reference to AgentCore Memory message - "cost": 0.0234, - "inputTokens": 1000, - "outputTokens": 500, - # ... all metadata attributes - } -) - -# 5. Integration with existing endpoints -# Sessions are fetched via: GET /sessions (AgentCore Memory) -# Messages are fetched via: GET /sessions/{session_id}/messages (AgentCore Memory) -# Metadata is enriched from this table using sessionId + messageId as keys -``` - -**Integration with Existing Endpoints**: - -The metadata table complements your existing session/message endpoints: - -| Endpoint | Data Source | Purpose | -|----------|-------------|---------| -| `GET /sessions` | AgentCore Memory | List user sessions | -| `GET /sessions/{id}/metadata` | AgentCore Memory | Get session metadata (title, preferences) | -| `GET /sessions/{id}/messages` | AgentCore Memory | Get message content | -| `GET /costs/summary` | SessionsMetadata + UserCostSummary | Get cost data (NEW) | - -**Enrichment Pattern**: -```python -# Existing: Get messages from AgentCore Memory -messages = await agentcore_memory.get_messages(session_id) - -# New: Enrich with cost metadata -for message in messages: - metadata = await dynamodb.get_item( - Key={ - "PK": f"USER#{user_id}", - "SK": f"SESSION#{session_id}#MSG#{message.id}" - } - ) - message.cost = metadata.get("cost") - message.tokenUsage = metadata.get("tokenUsage") -``` - -**Performance Characteristics**: -- **Write**: Single-digit millisecond latency -- **Read (single item)**: Single-digit millisecond latency -- **Query (time range)**: 10-50ms for typical user (hundreds of messages) -- **Scalability**: Unlimited (auto-scales with partition key distribution) - ---- - -#### Table 2: UserCostSummary - -**Purpose**: Pre-aggregated cost summaries for fast quota checks and dashboards - -**Schema**: - -```python -{ - # Primary Key - "PK": "USER#alice", # Partition key - "SK": "PERIOD#2025-01", # Sort key (YYYY-MM for monthly) - - # Aggregate Costs - "totalCost": 125.50, # Decimal - "totalRequests": 1234, - "totalInputTokens": 5000000, - "totalOutputTokens": 2500000, - "totalCacheReadTokens": 1000000, - "totalCacheWriteTokens": 500000, - - # Cache Savings - "cacheSavings": 15.75, # How much saved by caching - - # Per-Model Breakdown - "modelBreakdown": { - "claude-sonnet-4-5": { - "cost": 85.30, - "requests": 890, - "inputTokens": 3500000, - "outputTokens": 1800000 - }, - "claude-haiku-4-5": { - "cost": 40.20, - "requests": 344, - "inputTokens": 1500000, - "outputTokens": 700000 - } - }, - - # Period Info - "periodStart": "2025-01-01T00:00:00Z", - "periodEnd": "2025-01-31T23:59:59Z", - "lastUpdated": "2025-01-15T10:30:45.123Z", - - # Quota Info (denormalized for fast checks) - "quotaLimit": 200.00, - "quotaRemaining": 74.50, - "quotaPercentUsed": 62.75 -} -``` - -**Indexes**: - -**Primary Index**: -- `PK` = `USER#` (Partition Key) -- `SK` = `PERIOD#` (Sort Key for monthly) or `PERIOD#` (for daily) - -**GSI 1: PeriodIndex** (for admin queries - optional) -- `GSI1PK` = `PERIOD#` (Partition Key) -- `GSI1SK` = `` (Sort Key) -- **Use Cases**: - - Find top spenders in a period - - Generate org-wide cost reports - -**Access Patterns**: - -```python -# 1. Get current month summary (for quota check) -get_item( - Key={ - "PK": "USER#alice", - "SK": "PERIOD#2025-01" - } -) -# Latency: <10ms (single-item read) ✅ - -# 2. Get user's historical costs -query( - KeyConditionExpression="PK = :user AND begins_with(SK, :prefix)", - ExpressionAttributeValues={ - ":user": "USER#alice", - ":prefix": "PERIOD#" - }, - ScanIndexForward=False, # Descending (newest first) - Limit=12 # Last 12 months -) - -# 3. Update summary (atomic increment) -update_item( - Key={"PK": "USER#alice", "SK": "PERIOD#2025-01"}, - UpdateExpression="ADD totalCost :cost, totalRequests :one, totalInputTokens :input, totalOutputTokens :output", - ExpressionAttributeValues={ - ":cost": Decimal("0.0234"), - ":one": 1, - ":input": 1000, - ":output": 500 - } -) -``` - -**Update Strategy**: - -After each request, update the summary table asynchronously: - -```python -async def _update_cost_summary(user_id: str, cost: float, usage: dict, timestamp: str): - """Update pre-aggregated cost summary (async, non-blocking)""" - - # Determine period key - dt = datetime.fromisoformat(timestamp) - period_key = f"PERIOD#{dt.strftime('%Y-%m')}" - - # Atomic increment (DynamoDB handles concurrency) - await dynamodb.update_item( - TableName="UserCostSummary", - Key={ - "PK": f"USER#{user_id}", - "SK": period_key - }, - UpdateExpression=""" - ADD totalCost :cost, - totalRequests :one, - totalInputTokens :input, - totalOutputTokens :output, - totalCacheReadTokens :cacheRead, - totalCacheWriteTokens :cacheWrite - SET lastUpdated = :now - """, - ExpressionAttributeValues={ - ":cost": Decimal(str(cost)), - ":one": 1, - ":input": usage.get("inputTokens", 0), - ":output": usage.get("outputTokens", 0), - ":cacheRead": usage.get("cacheReadInputTokens", 0), - ":cacheWrite": usage.get("cacheWriteInputTokens", 0), - ":now": timestamp - } - ) - - # Also update per-model breakdown (nested update) - # Implementation details omitted for brevity -``` - -**Performance Characteristics**: -- **Quota Check**: <10ms (single `GetItem`) -- **Dashboard Load**: <20ms (query last 12 months) -- **Update**: <10ms (atomic increment, non-blocking) -- **Concurrency**: Handled automatically by DynamoDB - ---- - -### Storage Abstraction Layer - -To support both local files (dev) and DynamoDB (prod), implement a storage interface: - -**File**: `backend/src/apis/app_api/storage/metadata_storage.py` - -```python -from abc import ABC, abstractmethod -from typing import Optional, List, Dict, Any -from datetime import datetime - - -class MetadataStorage(ABC): - """Abstract interface for message metadata storage""" - - @abstractmethod - async def store_message_metadata( - self, - user_id: str, - session_id: str, - message_id: int, - metadata: Dict[str, Any] - ) -> None: - """Store message metadata""" - pass - - @abstractmethod - async def get_user_cost_summary( - self, - user_id: str, - period: str # e.g., "2025-01" - ) -> Optional[Dict[str, Any]]: - """Get pre-aggregated cost summary for quota checks""" - pass - - @abstractmethod - async def get_user_messages_in_range( - self, - user_id: str, - start_date: datetime, - end_date: datetime - ) -> List[Dict[str, Any]]: - """Get all user messages in date range (for detailed reports)""" - pass - - -class LocalFileStorage(MetadataStorage): - """Local file storage for development""" - # Implementation using existing file-based approach - pass - - -class DynamoDBStorage(MetadataStorage): - """DynamoDB storage for production""" - # Implementation using boto3 DynamoDB client - pass - - -# Factory function -def get_metadata_storage() -> MetadataStorage: - """Get appropriate storage based on environment""" - import os - - if os.environ.get("ENVIRONMENT") == "production": - return DynamoDBStorage() - else: - return LocalFileStorage() -``` - -**Benefits**: -- Developers work locally without AWS -- Production uses scalable DynamoDB -- Easy testing (mock the interface) -- Future-proof (can add other backends) - ---- - -## Token Caching Considerations - -### Cache Token Pricing - -**Bedrock Models** (Claude via Bedrock): -- **Cache Write**: ~25% markup over input price -- **Cache Read**: ~90% discount from input price - -**Example** (Claude Sonnet 4.5): -- Input: $3.00 per million tokens -- Output: $15.00 per million tokens -- Cache Write: $3.75 per million tokens (25% markup) -- Cache Read: $0.30 per million tokens (90% discount) - -### Cache Token Detection - -Already implemented in `stream_processor.py:881-923`: - -```python -# Add cache token fields if present -cache_read = usage_obj.get("cacheReadInputTokens") -if cache_read is None: - cache_read = usage_obj.get("cache_read_input_tokens") - -cache_write = usage_obj.get("cacheWriteInputTokens") -if cache_write is None: - cache_write = usage_obj.get("cache_write_input_tokens") - -# Include cache fields if they exist (even if 0) -if cache_read is not None: - usage_data["cacheReadInputTokens"] = cache_read -if cache_write is not None: - usage_data["cacheWriteInputTokens"] = cache_write -``` - -### Cache Cost Impact - -**Without caching**: -``` -Cost = (1000 input tokens × $3.00/M) + (500 output tokens × $15.00/M) - = $0.003 + $0.0075 - = $0.0105 -``` - -**With caching** (200 cache reads, 100 cache writes): -``` -Standard input: 1000 - 200 - 100 = 700 tokens -Cache reads: 200 tokens -Cache writes: 100 tokens - -Cost = (700 × $3.00/M) + (200 × $0.30/M) + (100 × $3.75/M) + (500 × $15.00/M) - = $0.0021 + $0.00006 + $0.000375 + $0.0075 - = $0.010035 -``` - -**Savings**: ~4% in this example, but can be much higher with larger cache hits - ---- - -## Cost Calculation - -### Service Implementation - -**File**: `backend/src/apis/app_api/costs/calculator.py` (new file) - -```python -from typing import Dict, Optional -from .models import CostBreakdown - - -class CostCalculator: - """Calculate costs from token usage and pricing""" - - @staticmethod - def calculate_message_cost( - usage: Dict[str, int], - pricing: Dict[str, float] - ) -> tuple[float, CostBreakdown]: - """ - Calculate cost for a single message - - Args: - usage: Token usage dict with inputTokens, outputTokens, etc. - pricing: Pricing dict with inputPricePerMtok, etc. - - Returns: - Tuple of (total_cost, cost_breakdown) - """ - # Extract token counts (default to 0 if not present) - input_tokens = usage.get("inputTokens", 0) - output_tokens = usage.get("outputTokens", 0) - cache_read_tokens = usage.get("cacheReadInputTokens", 0) - cache_write_tokens = usage.get("cacheWriteInputTokens", 0) - - # Extract pricing (default to 0 if not present) - input_price = pricing.get("inputPricePerMtok", 0.0) - output_price = pricing.get("outputPricePerMtok", 0.0) - cache_read_price = pricing.get("cacheReadPricePerMtok", 0.0) - cache_write_price = pricing.get("cacheWritePricePerMtok", 0.0) - - # Calculate costs (per million tokens) - input_cost = (input_tokens / 1_000_000) * input_price - output_cost = (output_tokens / 1_000_000) * output_price - cache_read_cost = (cache_read_tokens / 1_000_000) * cache_read_price - cache_write_cost = (cache_write_tokens / 1_000_000) * cache_write_price - - total_cost = input_cost + output_cost + cache_read_cost + cache_write_cost - - breakdown = CostBreakdown( - inputCost=input_cost, - outputCost=output_cost, - cacheReadCost=cache_read_cost, - cacheWriteCost=cache_write_cost, - totalCost=total_cost - ) - - return total_cost, breakdown - - @staticmethod - def calculate_cache_savings( - cache_read_tokens: int, - input_price: float, - cache_read_price: float - ) -> float: - """ - Calculate cost savings from cache hits - - Without cache, these tokens would have been charged at input_price. - With cache, they're charged at cache_read_price. - - Args: - cache_read_tokens: Number of tokens read from cache - input_price: Standard input price per million tokens - cache_read_price: Cache read price per million tokens - - Returns: - Cost savings in USD - """ - if cache_read_tokens == 0: - return 0.0 - - standard_cost = (cache_read_tokens / 1_000_000) * input_price - cache_cost = (cache_read_tokens / 1_000_000) * cache_read_price - - return standard_cost - cache_cost -``` - -### Integration Point - -**File**: `backend/src/agents/main_agent/streaming/stream_coordinator.py` - -Add new methods: - -```python -async def _get_pricing_snapshot(self, agent: Any) -> Optional[Dict[str, Any]]: - """ - Get pricing snapshot from agent's model configuration - - Args: - agent: MainAgent wrapper instance - - Returns: - Pricing snapshot dict or None if unavailable - """ - if not agent or not hasattr(agent, 'model_config'): - return None - - model_config = agent.model_config - model_id = model_config.model_id - - # Get managed model pricing - # TODO: Import managed models service - from apis.app_api.admin.services.managed_models import get_model_by_model_id - - managed_model = await get_model_by_model_id(model_id) - if not managed_model: - logger.warning(f"No managed model found for {model_id}") - return None - - # Create pricing snapshot - from datetime import datetime, timezone - - snapshot = { - "inputPricePerMtok": managed_model.input_price_per_million_tokens, - "outputPricePerMtok": managed_model.output_price_per_million_tokens, - "currency": "USD", - "snapshotAt": datetime.now(timezone.utc).isoformat() - } - - # Add cache pricing if available (Bedrock only) - if managed_model.cache_write_price_per_million_tokens is not None: - snapshot["cacheWritePricePerMtok"] = managed_model.cache_write_price_per_million_tokens - if managed_model.cache_read_price_per_million_tokens is not None: - snapshot["cacheReadPricePerMtok"] = managed_model.cache_read_price_per_million_tokens - - return snapshot - - -def _calculate_message_cost( - self, - usage: Dict[str, Any], - pricing: Optional[Dict[str, Any]] -) -> Optional[float]: - """ - Calculate message cost from usage and pricing - - Args: - usage: Token usage dict - pricing: Pricing snapshot dict - - Returns: - Total cost in USD or None if pricing unavailable - """ - if not pricing: - return None - - from apis.app_api.costs.calculator import CostCalculator - - total_cost, _ = CostCalculator.calculate_message_cost(usage, pricing) - return total_cost -``` - ---- - -## Aggregation & Querying - -### Service Implementation - -**File**: `backend/src/apis/app_api/costs/aggregator.py` (new file) - -```python -from datetime import datetime, timezone -from typing import Optional -from decimal import Decimal -import boto3 - -from .models import UserCostSummary, ModelCostSummary, CostBreakdown -from apis.app_api.storage.metadata_storage import get_metadata_storage - - -class CostAggregator: - """Aggregate costs across sessions and time periods""" - - def __init__(self): - self.storage = get_metadata_storage() - - async def get_user_cost_summary( - self, - user_id: str, - period: str # e.g., "2025-01" for monthly - ) -> UserCostSummary: - """ - Get aggregated cost summary for a user (fast path using pre-aggregated data) - - This method queries the UserCostSummary table for O(1) performance. - - Args: - user_id: User identifier - period: Period identifier (YYYY-MM for monthly) - - Returns: - UserCostSummary with pre-aggregated costs - """ - # Get pre-aggregated summary from storage - summary = await self.storage.get_user_cost_summary(user_id, period) - - if not summary: - # No data for this period, return empty summary - return self._create_empty_summary(user_id, period) - - # Convert to UserCostSummary model - return UserCostSummary( - userId=user_id, - periodStart=summary["periodStart"], - periodEnd=summary["periodEnd"], - totalCost=float(summary["totalCost"]), - models=self._build_model_summaries(summary.get("modelBreakdown", {})), - totalRequests=summary["totalRequests"], - totalInputTokens=summary["totalInputTokens"], - totalOutputTokens=summary["totalOutputTokens"], - totalCacheSavings=float(summary.get("cacheSavings", 0.0)) - ) - - async def get_detailed_cost_report( - self, - user_id: str, - start_date: datetime, - end_date: datetime - ) -> UserCostSummary: - """ - Get detailed cost report by querying message-level data - - This method queries the MessageMetadata table for detailed breakdowns. - Use this for custom date ranges or when detailed per-message data is needed. - - Args: - user_id: User identifier - start_date: Start of period - end_date: End of period - - Returns: - UserCostSummary with detailed aggregations - """ - # Query message metadata in date range - messages = await self.storage.get_user_messages_in_range( - user_id, start_date, end_date - ) - - # Aggregate from message-level data - total_cost = 0.0 - total_requests = len(messages) - total_input_tokens = 0 - total_output_tokens = 0 - total_cache_savings = 0.0 - - model_stats = {} - - for message in messages: - # Extract cost and tokens - cost = float(message.get("cost", 0.0)) - total_cost += cost - - input_tokens = message.get("inputTokens", 0) - output_tokens = message.get("outputTokens", 0) - cache_read_tokens = message.get("cacheReadTokens", 0) - cache_write_tokens = message.get("cacheWriteTokens", 0) - - total_input_tokens += input_tokens - total_output_tokens += output_tokens - - # Calculate cache savings - if cache_read_tokens > 0: - pricing = message.get("pricingSnapshot", {}) - standard_cost = (cache_read_tokens / 1_000_000) * pricing.get("inputPricePerMtok", 0) - cache_cost = (cache_read_tokens / 1_000_000) * pricing.get("cacheReadPricePerMtok", 0) - total_cache_savings += (standard_cost - cache_cost) - - # Aggregate per-model - model_id = message.get("modelId", "unknown") - if model_id not in model_stats: - model_stats[model_id] = { - "modelName": message.get("modelName", "Unknown"), - "provider": message.get("provider", "unknown"), - "cost": 0.0, - "requests": 0, - "inputTokens": 0, - "outputTokens": 0, - "cacheReadTokens": 0, - "cacheWriteTokens": 0 - } - - stats = model_stats[model_id] - stats["cost"] += cost - stats["requests"] += 1 - stats["inputTokens"] += input_tokens - stats["outputTokens"] += output_tokens - stats["cacheReadTokens"] += cache_read_tokens - stats["cacheWriteTokens"] += cache_write_tokens - - # Build model summaries - models = [] - for model_id, stats in model_stats.items(): - breakdown = CostBreakdown( - inputCost=0.0, # TODO: Store breakdown in metadata - outputCost=0.0, - cacheReadCost=0.0, - cacheWriteCost=0.0, - totalCost=stats["cost"] - ) - - model_summary = ModelCostSummary( - modelId=model_id, - modelName=stats["modelName"], - provider=stats["provider"], - totalInputTokens=stats["inputTokens"], - totalOutputTokens=stats["outputTokens"], - totalCacheReadTokens=stats["cacheReadTokens"], - totalCacheWriteTokens=stats["cacheWriteTokens"], - costBreakdown=breakdown, - requestCount=stats["requests"] - ) - models.append(model_summary) - - return UserCostSummary( - userId=user_id, - periodStart=start_date.isoformat(), - periodEnd=end_date.isoformat(), - totalCost=total_cost, - models=models, - totalRequests=total_requests, - totalInputTokens=total_input_tokens, - totalOutputTokens=total_output_tokens, - totalCacheSavings=total_cache_savings - ) - - def _build_model_summaries(self, model_breakdown: dict) -> list: - """Build ModelCostSummary objects from breakdown dict""" - models = [] - for model_id, stats in model_breakdown.items(): - breakdown = CostBreakdown( - inputCost=0.0, # Stored in summary if needed - outputCost=0.0, - cacheReadCost=0.0, - cacheWriteCost=0.0, - totalCost=float(stats["cost"]) - ) - - models.append(ModelCostSummary( - modelId=model_id, - modelName=stats.get("modelName", "Unknown"), - provider=stats.get("provider", "unknown"), - totalInputTokens=stats.get("inputTokens", 0), - totalOutputTokens=stats.get("outputTokens", 0), - totalCacheReadTokens=stats.get("cacheReadTokens", 0), - totalCacheWriteTokens=stats.get("cacheWriteTokens", 0), - costBreakdown=breakdown, - requestCount=stats.get("requests", 0) - )) - - return models - - def _create_empty_summary(self, user_id: str, period: str) -> UserCostSummary: - """Create empty summary for period with no data""" - return UserCostSummary( - userId=user_id, - periodStart=f"{period}-01T00:00:00Z", - periodEnd=f"{period}-31T23:59:59Z", - totalCost=0.0, - models=[], - totalRequests=0, - totalInputTokens=0, - totalOutputTokens=0, - totalCacheSavings=0.0 - ) -``` - -### API Endpoints - -**File**: `backend/src/apis/app_api/costs/routes.py` (new file) - -```python -from fastapi import APIRouter, Depends, Query -from datetime import datetime -from typing import Optional - -from apis.shared.auth.dependencies import get_current_user -from apis.shared.auth.models import User -from .models import UserCostSummary -from .aggregator import CostAggregator - -router = APIRouter(prefix="/costs", tags=["costs"]) - - -@router.get("/summary", response_model=UserCostSummary) -async def get_cost_summary( - period: Optional[str] = Query(None, description="Period (YYYY-MM), defaults to current month"), - current_user: User = Depends(get_current_user) -): - """ - Get cost summary for the authenticated user (fast path) - - Uses pre-aggregated UserCostSummary table for <10ms response time. - - Args: - period: Optional period (YYYY-MM), defaults to current month - current_user: Authenticated user from JWT - - Returns: - UserCostSummary with pre-aggregated costs - - Example: - GET /costs/summary?period=2025-01 - """ - # Default to current month - if not period: - period = datetime.utcnow().strftime("%Y-%m") - - # Get pre-aggregated summary (O(1) lookup) - aggregator = CostAggregator() - summary = await aggregator.get_user_cost_summary( - user_id=current_user.user_id, - period=period - ) - - return summary - - -@router.get("/detailed-report", response_model=UserCostSummary) -async def get_detailed_report( - start_date: str = Query(..., description="ISO 8601 start date (YYYY-MM-DD)"), - end_date: str = Query(..., description="ISO 8601 end date (YYYY-MM-DD)"), - current_user: User = Depends(get_current_user) -): - """ - Get detailed cost report for custom date range - - Queries MessageMetadata table for detailed breakdown. - Use this for custom date ranges or when detailed per-message data is needed. - - Args: - start_date: Start date (ISO 8601) - end_date: End date (ISO 8601) - current_user: Authenticated user from JWT - - Returns: - UserCostSummary with detailed aggregations - - Example: - GET /costs/detailed-report?start_date=2025-01-01&end_date=2025-01-15 - """ - # Parse dates - start = datetime.fromisoformat(start_date) - end = datetime.fromisoformat(end_date) - - # Validate date range (max 90 days for performance) - if (end - start).days > 90: - raise HTTPException( - status_code=400, - detail="Date range cannot exceed 90 days" - ) - - # Get detailed report (queries message-level data) - aggregator = CostAggregator() - summary = await aggregator.get_detailed_cost_report( - user_id=current_user.user_id, - start_date=start, - end_date=end - ) - - return summary -``` - ---- - -## Future: Quota Implementation - -### Quota Models - -**File**: `backend/src/apis/app_api/costs/quota_models.py` (future) - -```python -from pydantic import BaseModel, Field, ConfigDict -from typing import Optional, Literal - - -class UserQuota(BaseModel): - """User quota configuration""" - model_config = ConfigDict(populate_by_name=True) - - user_id: str = Field(..., alias="userId") - - # Quota limits - monthly_cost_limit: float = Field(..., alias="monthlyCostLimit", description="Monthly spend limit in USD") - daily_cost_limit: Optional[float] = Field(None, alias="dailyCostLimit", description="Daily spend limit in USD") - - # Quota period - period: Literal["daily", "monthly"] = Field(default="monthly") - - # Actions on limit - action_on_limit: Literal["block", "warn", "notify"] = Field( - default="warn", - alias="actionOnLimit" - ) - - # Current usage - current_period_cost: float = Field(0.0, alias="currentPeriodCost") - period_start: str = Field(..., alias="periodStart") - period_end: str = Field(..., alias="periodEnd") - - -class QuotaCheckResult(BaseModel): - """Result of quota check""" - model_config = ConfigDict(populate_by_name=True) - - allowed: bool = Field(..., description="Whether request is allowed") - current_usage: float = Field(..., alias="currentUsage", description="Current period usage") - limit: float = Field(..., description="Quota limit") - remaining: float = Field(..., description="Remaining quota") - percentage_used: float = Field(..., alias="percentageUsed", description="Percentage of quota used") - message: Optional[str] = Field(None, description="Message to display to user") -``` - -### Pre-Request Quota Check - -```python -async def check_quota_before_request(user_id: str) -> QuotaCheckResult: - """ - Check if user has remaining quota before processing request - - This is a fast check using cached/aggregated data. - """ - # Get user quota config - quota = await get_user_quota(user_id) - - # Get current period usage - aggregator = CostAggregator() - summary = await aggregator.get_user_cost_summary( - user_id=user_id, - start_date=datetime.fromisoformat(quota.period_start), - end_date=datetime.fromisoformat(quota.period_end) - ) - - current_usage = summary.total_cost - limit = quota.monthly_cost_limit - remaining = limit - current_usage - percentage = (current_usage / limit) * 100 if limit > 0 else 0 - - # Determine if allowed - allowed = True - message = None - - if quota.action_on_limit == "block" and current_usage >= limit: - allowed = False - message = f"Monthly quota exceeded. Limit: ${limit:.2f}, Used: ${current_usage:.2f}" - elif quota.action_on_limit == "warn" and percentage >= 80: - message = f"You've used {percentage:.0f}% of your monthly quota (${current_usage:.2f}/${limit:.2f})" - - return QuotaCheckResult( - allowed=allowed, - currentUsage=current_usage, - limit=limit, - remaining=remaining, - percentageUsed=percentage, - message=message - ) -``` - ---- - -## Environment Configuration - -### Backend Configuration (.env) - -Add the following environment variables to `backend/src/.env`: - -```bash -# ============================================================================= -# DATABASE CONFIGURATION -# ============================================================================= - -# DynamoDB table for session metadata (message-level cost tracking) -# AgentCore Memory manages sessions and messages in the cloud -# This table stores additional metadata like cost, tokens, latency per message -# Local development uses file storage if not set -DYNAMODB_SESSIONS_METADATA_TABLE_NAME=SessionsMetadata - -# DynamoDB table for user cost summaries (separate table) -# Stores pre-aggregated costs for fast quota checks and dashboards -# Required for production cost tracking and quota enforcement -DYNAMODB_COST_SUMMARY_TABLE_NAME=UserCostSummary -``` - -**Usage in Code**: -```python -import os - -# Get table names from environment -SESSIONS_METADATA_TABLE = os.environ.get("DYNAMODB_SESSIONS_METADATA_TABLE_NAME", "SessionsMetadata") -COST_SUMMARY_TABLE = os.environ.get("DYNAMODB_COST_SUMMARY_TABLE_NAME", "UserCostSummary") - -# Use in DynamoDB operations -# Note: Sessions and messages are in AgentCore Memory, NOT DynamoDB -dynamodb.Table(SESSIONS_METADATA_TABLE).put_item(...) # Store metadata only -dynamodb.Table(COST_SUMMARY_TABLE).get_item(...) # Get cost summary -``` - -**Local Development**: -- If `DYNAMODB_SESSIONS_METADATA_TABLE_NAME` is not set → Use local file storage for metadata -- If `DYNAMODB_COST_SUMMARY_TABLE_NAME` is not set → Cost tracking disabled (dev mode) -- Sessions/messages use local AgentCore Memory storage - -**Production**: -- Both environment variables MUST be set -- AgentCore Memory handles sessions/messages (AWS managed) -- Our tables handle metadata and cost summaries -- Tables must be created via Infrastructure as Code (CloudFormation/CDK) - ---- - -## Implementation Plan - -### Phase 1: Data Model Updates & DynamoDB Setup (Week 1-2) - -**Priority: HIGH** - -1. **Update Data Models** - - Add `cache_write_price_per_million_tokens` to ManagedModel - - Add `cache_read_price_per_million_tokens` to ManagedModel - - Update `PricingSnapshot` model with cache pricing fields - - Add `cost` field to MessageMetadata - - Update admin UI to accept/display cache pricing - -2. **Create DynamoDB Tables** (Infrastructure) - - Create `SessionsMetadata` table (message-level cost/token/latency data) - - Primary key: PK (partition), SK (sort) - - GSI 1: UserTimestampIndex (for time-range queries) - - GSI 2: ModelUsageIndex (optional, for analytics) - - TTL enabled on `ttl` attribute (365-day retention, matches AgentCore Memory) - - Links to AgentCore Memory sessions via `sessionId` + `messageId` - - Create `UserCostSummary` table (separate table for cost aggregation) - - Primary key: PK (partition), SK (sort) - - GSI 1: PeriodIndex (optional, for admin queries) - - Set up IAM permissions for Lambda/ECS (read/write to tables) - - Set up IAM permissions for AgentCore Memory (already configured) - - Configure table capacity (on-demand recommended) - - Add environment variables to deployment configuration - -3. **Create Storage Abstraction Layer** - - Implement `MetadataStorage` interface - - Implement `LocalFileStorage` (development) - - Implement `DynamoDBStorage` (production) - - Add environment-based factory pattern - -**Files to Create**: -- `backend/src/apis/app_api/storage/metadata_storage.py` -- `backend/src/apis/app_api/storage/dynamodb_storage.py` -- Infrastructure: CloudFormation/CDK for DynamoDB tables - -**Files to Modify**: -- `backend/src/apis/app_api/admin/models.py` -- `backend/src/apis/app_api/messages/models.py` - -**Tests**: -- Pydantic model validation tests -- Storage abstraction interface tests -- Mock DynamoDB operations - ---- - -### Phase 2: Cost Calculation & Capture (Week 3) - -**Priority: HIGH** - -1. **Create Cost Calculator Service** - - Implement `calculate_message_cost()` - - Implement `calculate_cache_savings()` - - Handle multi-provider pricing (Bedrock, OpenAI, Gemini) - - Add comprehensive unit tests - -2. **Create Pricing Service** - - Implement `get_model_pricing()` with LRU cache - - Implement `create_pricing_snapshot()` - - Query managed models efficiently - -3. **Integrate into Stream Coordinator** - - Add `_get_pricing_snapshot()` method - - Add `_calculate_message_cost()` method - - Update `_store_message_metadata()` to: - - Calculate cost from usage + pricing - - Store to MessageMetadata table (DynamoDB/local files) - - Update UserCostSummary table (async, atomic increment) - - Test with real streaming requests - -**Files to Create**: -- `backend/src/apis/app_api/costs/calculator.py` -- `backend/src/apis/app_api/costs/pricing_service.py` - -**Files to Modify**: -- `backend/src/agents/main_agent/streaming/stream_coordinator.py` - -**Tests**: -- Cost calculation unit tests (various token combinations) -- Cache savings calculation tests -- Integration tests with mocked DynamoDB -- End-to-end streaming tests - ---- - -### Phase 3: Aggregation & API Endpoints (Week 4) - -**Priority: HIGH** - -1. **Create Cost Aggregator Service** - - Implement `get_user_cost_summary()` (fast path via UserCostSummary table) - - Implement `get_detailed_cost_report()` (query MessageMetadata table) - - Handle date range filtering with GSI - - Calculate cache savings - -2. **Create Cost API Endpoints** - - `GET /costs/summary?period=YYYY-MM` - Fast pre-aggregated summary - - `GET /costs/detailed-report?start_date&end_date` - Custom date ranges - - Add authentication/authorization - - Add request validation (max date range) - -3. **Frontend Cost Dashboard** - - Create cost summary component - - Display total costs, per-model breakdown - - Show cache savings visualization - - Add period selector (current month, last 30 days, etc.) - - Real-time cost updates - -**Files to Create**: -- `backend/src/apis/app_api/costs/aggregator.py` -- `backend/src/apis/app_api/costs/routes.py` -- `backend/src/apis/app_api/costs/models.py` -- `frontend/ai.client/src/app/costs/` (new feature module) - -**Tests**: -- Aggregation logic tests -- API endpoint integration tests -- Frontend component tests - ---- - -### Phase 4: Multi-Provider Pricing & Frontend Forms (Week 5) - -**Priority: MEDIUM** - -1. **Add OpenAI Pricing** - - Research current OpenAI pricing (GPT-4, GPT-3.5, etc.) - - Add to managed models database - - Update calculator to handle OpenAI-specific pricing - - No cache pricing for OpenAI (standard input/output only) - -2. **Add Gemini Pricing** - - Research current Gemini pricing - - Add to managed models database - - Update calculator to handle Gemini-specific pricing - -3. **Update Admin Model Form (Frontend)** - - **Location**: `frontend/ai.client/src/app/admin/manage-models/new/` - - **Requirements**: - - Add cache pricing fields: `cacheReadPricePerMillionTokens`, `cacheWritePricePerMillionTokens` - - **Show cache fields ONLY when `provider === 'bedrock'`** - - Hide cache fields for OpenAI and Gemini providers - - Validate cache pricing fields (must be positive numbers) - - Update form submission to include cache pricing in API request - - **Form Structure**: - ```typescript - interface ModelFormData { - modelId: string; - modelName: string; - provider: 'bedrock' | 'openai' | 'gemini'; - inputPricePerMillionTokens: number; - outputPricePerMillionTokens: number; - - // Cache pricing (Bedrock only) - cacheReadPricePerMillionTokens?: number; // Show if provider === 'bedrock' - cacheWritePricePerMillionTokens?: number; // Show if provider === 'bedrock' - - // Other fields... - } - ``` - - **UI Implementation**: - ```angular - - - - - - - - - @if (form.value.provider === 'bedrock') { -
-

Cache Pricing (Optional)

-

Bedrock supports prompt caching for reduced costs on repeated content.

- - - - -
- } - ``` - -4. **Pricing Management UI** - - Admin UI to update pricing - - Show pricing history/changelog - - Bulk import pricing from CSV/JSON - -**Files to Create**: -- `frontend/ai.client/src/app/admin/manage-models/new/model-form.component.ts` (update) -- `frontend/ai.client/src/app/admin/manage-models/new/model-form.component.html` (update) - -**Files to Modify**: -- `backend/src/apis/app_api/admin/services/managed_models.py` -- `backend/src/apis/app_api/admin/models.py` (ManagedModel with cache pricing) -- Admin UI components -- Cost calculator (multi-provider support) - -**Tests**: -- Multi-provider cost calculation tests -- Admin pricing update tests -- Frontend form validation tests (cache pricing shown/hidden based on provider) - ---- - -### Phase 5: Quota System (Week 6-7 - Optional) - -**Priority: LOW (Future Enhancement)** - -1. **Create Quota Infrastructure** - - `UserQuota` model (DynamoDB table) - - `QuotaCheckResult` model - - Quota configuration per user/org - -2. **Implement Quota Service** - - `check_quota_before_request()` (<50ms, reads UserCostSummary) - - `update_quota_usage()` (handled by existing summary updates) - - Quota reset logic (monthly/daily) - - Notification triggers (80%, 90%, 100%) - -3. **Integrate Quota Checks** - - Add quota check before streaming starts - - Block/warn based on quota config - - Return quota status in API responses - -4. **Admin Quota Management** - - Set user/org quotas - - View quota usage dashboard - - Generate quota reports - - Override quotas for specific users - -**Files to Create**: -- `backend/src/apis/app_api/costs/quota_models.py` -- `backend/src/apis/app_api/costs/quota_service.py` -- `backend/src/apis/shared/middleware/quota_middleware.py` -- DynamoDB table for UserQuota - -**Tests**: -- Quota check performance tests (<50ms target) -- Middleware integration tests -- Admin UI tests - ---- - -## Performance Characteristics - -### Production (DynamoDB) - -**Write Performance** (per request): -- Calculate cost: <1ms (pure math) -- Write to MessageMetadata: 5-10ms (single `PutItem`) -- Update UserCostSummary: 5-10ms (atomic `UpdateItem`, async) -- **Total overhead**: ~10-20ms (async, non-blocking for user) - -**Read Performance** (quota checks, dashboards): -- Quota check (UserCostSummary `GetItem`): <10ms ✅ -- Monthly summary (UserCostSummary `GetItem`): <10ms ✅ -- Historical costs (12 months via `Query`): <20ms ✅ -- Detailed report (custom date range via GSI): 20-100ms (depends on data volume) - -**Scalability**: -- **10,000 users**: Excellent (each user = separate partition key) -- **100,000 users**: Excellent (DynamoDB auto-scales) -- **1,000,000 users**: Excellent (partition key distribution ensures no hot keys) -- **Concurrent writes**: Unlimited (DynamoDB handles automatically) - -### Development (Local Files) - -**Write Performance**: -- Calculate cost: <1ms -- File write: 5-50ms (depends on session size) -- **Total**: Acceptable for development - -**Read Performance**: -- Monthly summary: 10-100ms (file I/O) -- Detailed report: 100-500ms (multiple file reads) -- **Total**: Acceptable for development, not production - -**Scalability**: -- Good for < 100 sessions -- Degrades with large session files -- **Production deployment must use DynamoDB** - ---- - -## Security & Privacy - -### Data Access Control - -- **User Data**: Users can only access their own cost data -- **Admin Data**: Admins can view all user costs (RBAC) -- **Authentication**: JWT-based authentication required - -### Pricing Data - -- **Visibility**: Pricing data is admin-only by default -- **Transparency**: Users can see their per-request costs -- **Historical Accuracy**: Pricing snapshots prevent retroactive cost changes - -### PII Considerations - -- Cost data includes `user_id` but not email/name -- Session titles may contain PII - ensure proper access control -- Cost reports should not expose message content - ---- - -## Monitoring & Alerting - -### Metrics to Track - -1. **Cost Metrics**: - - Total cost per user (daily, monthly) - - Cost per model/provider - - Cache hit rate and savings - - Average cost per request - -2. **Usage Metrics**: - - Total tokens processed - - Requests per user - - Most expensive sessions - -3. **System Metrics**: - - Cost calculation latency - - Aggregation query time - - Storage size growth - -### Alerts - -1. **User Alerts**: - - 80% quota threshold reached - - Daily spend anomaly detected - - Monthly quota exceeded - -2. **Admin Alerts**: - - Overall spend spike - - Missing pricing for new model - - Cost calculation failures - ---- - -## Testing Strategy - -### Unit Tests - -- Cost calculation with various token combinations -- Cache savings calculations -- Pricing snapshot creation -- Aggregation logic - -### Integration Tests - -- End-to-end streaming with cost capture -- Cost aggregation across multiple sessions -- Multi-provider cost calculations -- Quota enforcement - -### Load Tests - -- Cost calculation performance (1000 messages) -- Aggregation performance (100 sessions) -- Concurrent quota checks - -### Manual Testing Scenarios - -1. **Single Request**: Verify cost matches manual calculation -2. **With Caching**: Verify cache tokens reduce cost -3. **Multiple Models**: Switch models mid-session, verify per-model costs -4. **Date Ranges**: Filter costs by various date ranges -5. **Quota Limits**: Test block/warn behaviors - ---- - -## Documentation - -### Developer Documentation - -- Architecture overview (this spec) -- API endpoint documentation -- Cost calculation examples -- Database schema - -### User Documentation - -- How costs are calculated -- Understanding cache savings -- Quota system explanation -- Cost dashboard user guide - -### Admin Documentation - -- Setting up pricing -- Managing user quotas -- Generating cost reports -- Pricing update procedures - ---- - -## Open Questions & Decisions - -### 1. Pricing for New Models - -**Question**: How do we handle new models before pricing is configured? - -**Options**: -- A) Block requests until pricing is added -- B) Allow requests, store tokens, calculate cost later -- C) Use default/estimated pricing with warning - -**Recommendation**: Option B - Store usage, calculate when pricing available - ---- - -### 2. Free Tier / Credits - -**Question**: Should we support free credits or promotional quotas? - -**Options**: -- A) Add `credits` field to user quota -- B) Negative costs for promotional periods -- C) Separate credit tracking system - -**Recommendation**: Phase 6 feature, design separately - ---- - -### 3. Cost Rounding - -**Question**: How many decimal places for cost values? - -**Options**: -- A) Store full precision (float) -- B) Round to cents ($0.01) -- C) Round to 4 decimals ($0.0001) - -**Recommendation**: Store full precision, display 4 decimals, round on billing - ---- - -### 4. Aggregation Frequency - -**Question**: How often to pre-aggregate costs? - -**Options**: -- A) Real-time (calculate on demand) -- B) Hourly (background job) -- C) Daily (midnight UTC) - -**Recommendation**: Phase 1 - real-time, Phase 5 - daily pre-aggregation - ---- - -## Success Metrics - -### Phase 1-2 (Cost Capture) - -- ✅ 100% of streaming requests capture pricing snapshot -- ✅ 100% of messages have calculated cost -- ✅ Cache token costs correctly calculated -- ✅ < 50ms overhead for cost calculation - -### Phase 3 (Aggregation) - -- ✅ Cost summary API responds in < 1s for typical user -- ✅ Per-model breakdown matches sum of message costs -- ✅ Cache savings accurately calculated - -### Phase 5 (Quotas) - -- ✅ Quota checks complete in < 100ms -- ✅ Users blocked at quota limit (if configured) -- ✅ Notifications sent at 80% threshold - ---- - -## DynamoDB Best Practices & Cost Optimization - -### Table Capacity Planning - -**Recommended: On-Demand Mode** -- Auto-scales with traffic -- No capacity planning required -- Pay per request -- Ideal for variable workloads - -**Cost Estimate** (10,000 monthly active users): -``` -Assumptions: -- 10,000 users × 100 requests/month = 1M requests/month -- Average 2 writes per request (MessageMetadata + UserCostSummary) -- Average 10 reads per user/month (dashboards, quota checks) - -Writes: 2M writes × $1.25/M = $2.50/month -Reads: 100K reads × $0.25/M = $0.025/month -Storage: 10GB × $0.25/GB = $2.50/month - -Total: ~$5/month for 10K users ✅ -``` - -### Data Retention Strategy - -**Recommended: TTL for MessageMetadata** -```python -# Set TTL to auto-delete after 365 days (matches AgentCore Memory retention) -"ttl": int((datetime.utcnow() + timedelta(days=365)).timestamp()) -``` - -**Benefits**: -- Reduces storage costs -- Aligns with AgentCore Memory retention policy (365 days) -- Maintains compliance (GDPR right to deletion) -- Keeps recent data for detailed reports -- UserCostSummary persists indefinitely (small footprint) - -### Partition Key Distribution - -**Key Design**: `USER#` - -**Why This Works**: -- Each user = separate partition -- No hot partitions (even distribution) -- Scales linearly with users -- 10K users = 10K partitions ✅ - -**Avoid**: -- ❌ `PERIOD#2025-01` as PK (hot partition, all users in one key) -- ❌ `MODEL#claude` as PK (hot partition for popular models) - -### GSI Optimization - -**UserTimestampIndex**: -- Projection: ALL (for flexibility) -- Used infrequently (detailed reports only) -- Most queries use primary index - -**Alternative** (if GSI costs become significant): -- Projection: KEYS_ONLY + cost, tokens -- Reduces GSI storage by ~70% -- Requires additional `GetItem` calls for full data - -### Monitoring & Alarms - -**CloudWatch Metrics**: -``` -1. ConsumedReadCapacityUnits (should be low with on-demand) -2. ConsumedWriteCapacityUnits (should be low with on-demand) -3. UserErrors (should be 0) -4. SystemErrors (should be 0) -5. ConditionalCheckFailedRequests (atomic increments may retry) -``` - -**Alarms**: -- UserErrors > 10/minute → Investigate permissions/throttling -- Average latency > 100ms → Check GSI performance -- Storage > 100GB → Review TTL configuration - ---- - -## Conclusion - -This specification provides a production-ready, scalable approach to user cost tracking for 10,000+ users: - -### Key Strengths - -1. **Accurate Cost Tracking** - - Captures pricing at inference time (historical accuracy) - - Handles token caching with proper discount calculations - - Multi-provider support (Bedrock, OpenAI, Gemini) - -2. **High Performance** - - <10ms quota checks (critical for user experience) - - <20ms monthly dashboard loads - - ~10-20ms write overhead (async, non-blocking) - - Scales to 1M+ users without degradation - -3. **Production-Ready Architecture** - - AgentCore Memory for session/message storage (AWS managed) - - SessionsMetadata table for cost/token/latency tracking - - UserCostSummary table for pre-aggregated costs - - Storage abstraction for local development - - Atomic updates for concurrent requests - - Environment-based configuration via `.env` - -4. **Cost Efficient** - - ~$5/month for 10K users - - TTL-based data retention - - On-demand capacity (no over-provisioning) - - Minimal read/write operations - -5. **Future-Proof** - - Foundation for quota enforcement - - Supports multi-tenant organizations - - Cost allocation tags - - Detailed audit trail - -### Implementation Timeline - -- **Week 1-2**: Data models + DynamoDB setup -- **Week 3**: Cost calculation & capture -- **Week 4**: Aggregation & API endpoints -- **Week 5**: Multi-provider pricing -- **Week 6-7**: Quota system (optional) - -### Success Metrics - -- ✅ 100% of requests have cost calculated -- ✅ <10ms quota check latency (p99) -- ✅ <20ms dashboard load latency (p99) -- ✅ Support 10,000+ monthly users -- ✅ <$10/month infrastructure cost per 10K users - -The phased approach enables incremental delivery while maintaining production quality and scalability from day one. - ---- - -## Architecture Summary - -### Key Design Decisions - -| Decision | Rationale | -|----------|-----------| -| **AgentCore Memory** for sessions/messages | Managed by AWS, integrated with agent framework, handles conversation storage | -| **Separate metadata table** for cost tracking | Lightweight metadata layer, doesn't duplicate AgentCore Memory data | -| **Separate table** for cost summaries | Enables O(1) quota checks, pre-aggregated data for dashboards | -| **Environment variables** for table names | Flexible deployment, easy configuration, supports multi-environment | -| **Cache pricing** (Bedrock only) | OpenAI/Gemini don't support caching, avoid UI clutter for unsupported features | -| **Storage abstraction layer** | Developers work locally without AWS, production uses DynamoDB seamlessly | -| **Pre-aggregated summaries** | <10ms quota checks critical for user experience | -| **Pricing snapshots** | Historical accuracy even after price changes | -| **TTL on metadata** | Automatic data retention, compliance (GDPR), cost optimization | - -### DynamoDB Schema Quick Reference - -**SessionsMetadata Table** (metadata only): -``` -PK: USER# -SK: SESSION##MSG# → Message metadata (cost, tokens, latency) - -Note: Sessions and messages themselves are in AgentCore Memory -This table stores METADATA about those messages -``` - -**UserCostSummary Table** (separate): -``` -PK: USER# -SK: PERIOD# → Monthly cost summary -``` - -### Environment Variables - -```bash -# Message metadata (cost tracking) -DYNAMODB_SESSIONS_METADATA_TABLE_NAME=SessionsMetadata - -# Pre-aggregated costs (separate table) -DYNAMODB_COST_SUMMARY_TABLE_NAME=UserCostSummary -``` - -### Frontend Integration Points - -1. **Admin Model Form**: Cache pricing fields (Bedrock only) -2. **Cost Dashboard**: Display user costs and cache savings -3. **Quota Warnings**: Show usage percentage and remaining quota - -### Critical Performance Targets - -- ✅ Quota check: <10ms (single GetItem) -- ✅ Monthly dashboard: <20ms (single GetItem) -- ✅ Write overhead: ~10-20ms (async, non-blocking) -- ✅ Scale: 10,000+ users without degradation diff --git a/docs/specs/assistant-preview-refactor.md b/docs/specs/assistant-preview-refactor.md deleted file mode 100644 index abab8bb6..00000000 --- a/docs/specs/assistant-preview-refactor.md +++ /dev/null @@ -1,671 +0,0 @@ -# Assistant Preview & Chat Container Refactoring Specification - -## Overview - -This specification describes the implementation of an assistant preview feature within the assistant form page, along with a refactoring of the chat UI into a reusable `ChatContainerComponent`. The goal is to allow users to test their assistants in real-time while editing, without persisting preview conversations to their session history. - ---- - -## Table of Contents - -1. [Feature Requirements](#feature-requirements) -2. [Architecture Overview](#architecture-overview) -3. [Backend Changes](#backend-changes) -4. [Frontend Changes](#frontend-changes) -5. [Component Specifications](#component-specifications) -6. [Service Specifications](#service-specifications) -7. [Shared Constants](#shared-constants) -8. [File Changes Summary](#file-changes-summary) - ---- - -## Feature Requirements - -### Functional Requirements - -1. **Split Column Layout**: Assistant form page displays form inputs on the left (50%) and live preview on the right (50%) -2. **Hidden Sidenav**: Sidenav is hidden when entering the assistant form view, restored when leaving -3. **Live Preview Chat**: Users can send messages to test their assistant configuration -4. **Sessionless Preview**: Preview conversations use a special `preview-` prefixed session ID that the backend recognizes and skips persistence for -5. **Multi-turn Support**: Preview maintains conversation context within the same editing session -6. **Full Feature Parity**: Preview supports all chat features (streaming, tool use, tool results, citations, reasoning) - -### Non-Functional Requirements - -1. **No Global State Pollution**: Preview should not affect the main chat's state -2. **Instance-scoped Services**: Stream parsing and chat state should be isolated per preview instance -3. **Reusable Chat UI**: Extract chat UI into a reusable component for both session page and preview -4. **Maintainable Code**: Single source of truth for chat UI, no duplication - ---- - -## Architecture Overview - -``` -┌─────────────────────────────────────────────────────────────────┐ -│ assistant-form.page │ -├─────────────────────────────┬───────────────────────────────────┤ -│ Form Inputs (50%) │ Preview Panel (50%) │ -│ │ │ -│ - Name │ ┌─────────────────────────────┐ │ -│ - Description │ │ ChatContainerComponent │ │ -│ - Instructions │ │ (embeddedMode: true) │ │ -│ - File Upload │ │ │ │ -│ │ │ - MessageListComponent │ │ -│ │ │ - ChatInputComponent │ │ -│ │ │ │ │ -│ │ └─────────────────────────────┘ │ -│ │ │ -│ │ PreviewChatService (scoped) │ -│ │ StreamParserService (scoped) │ -└─────────────────────────────┴───────────────────────────────────┘ - -┌─────────────────────────────────────────────────────────────────┐ -│ session.page │ -│ │ -│ ┌────────────────────────────────────────────────────────────┐ │ -│ │ ChatContainerComponent │ │ -│ │ (fullPageMode: true) │ │ -│ │ │ │ -│ │ - Topnav (fixed, sidenav-aware) │ │ -│ │ - MessageListComponent │ │ -│ │ - ChatInputComponent (fixed footer, sidenav-aware) │ │ -│ │ │ │ -│ └────────────────────────────────────────────────────────────┘ │ -│ │ -│ ChatRequestService (root) │ -│ StreamParserService (root) │ -└─────────────────────────────────────────────────────────────────┘ -``` - ---- - -## Backend Changes - -### 1. Preview Session Detection - -**File:** `backend/src/apis/inference_api/chat/routes.py` - -Add a helper function to detect preview sessions: - -```python -# Preview session prefix - sessions with this prefix skip persistence -PREVIEW_SESSION_PREFIX = "preview-" - - -def is_preview_session(session_id: str) -> bool: - """Check if a session ID is a preview session (should skip persistence). - - Preview sessions are used for assistant testing in the form builder. - They allow full agent functionality but don't save to user's conversation history. - """ - return session_id.startswith(PREVIEW_SESSION_PREFIX) -``` - -### 2. Skip Persistence for Preview Sessions - -Wrap persistence operations with preview checks: - -```python -# In stream_conversational_message() - after emitting done event: -if is_preview_session(session_id): - logger.info(f"🔍 Preview session {session_id} - skipping message persistence") - return - -# Continue with normal persistence... -``` - -```python -# In invocations endpoint - session state validation: -if not is_preview_session(input_data.session_id): - # Check existing assistant, validate session state, etc. -else: - logger.info(f"🔍 Preview session - skipping session state validation") -``` - -```python -# In invocations endpoint - assistant_id persistence: -if not is_preview_session(input_data.session_id): - # Save assistant_id to session preferences -else: - logger.info(f"🔍 Preview session - skipping assistant_id persistence") -``` - -### 3. Locations to Add Preview Checks - -| Location | What to Skip | -|----------|-------------| -| `stream_conversational_message()` after done event | Message persistence to AgentCore Memory | -| Assistant validation block | Session state checks (existing assistant, message count) | -| Assistant preferences save | `store_session_metadata()` call | - ---- - -## Frontend Changes - -### Directory Structure - -``` -frontend/ai.client/src/app/ -├── session/ -│ ├── components/ -│ │ └── chat-container/ -│ │ ├── chat-container.component.ts # NEW - Reusable chat UI -│ │ ├── chat-container.component.html # NEW -│ │ └── chat-container.component.css # NEW -│ ├── services/ -│ │ └── chat/ -│ │ └── stream-parser.service.ts # MODIFY - Allow instance scoping -│ ├── session.page.ts # MODIFY - Use ChatContainerComponent -│ └── session.page.html # MODIFY - Simplified -├── assistants/ -│ └── assistant-form/ -│ ├── assistant-form.page.ts # MODIFY - Split layout, hide sidenav -│ ├── assistant-form.page.html # MODIFY - Two column layout -│ └── components/ -│ └── assistant-preview.component.ts # NEW - Preview panel -├── services/ -│ └── sidenav/ -│ └── sidenav.service.ts # EXISTS - Already has hide()/show() -└── shared/ - └── constants/ - └── session.constants.ts # NEW - Shared constants -``` - ---- - -## Component Specifications - -### ChatContainerComponent - -**Purpose:** Reusable chat UI that can be used in both full-page mode (session page) and embedded mode (assistant preview). - -**File:** `session/components/chat-container/chat-container.component.ts` - -```typescript -export interface ChatContainerConfig { - /** Show the top navigation bar (full-page mode only) */ - showTopnav: boolean; - /** Show the greeting/empty state */ - showEmptyState: boolean; - /** Allow closing the assistant card */ - allowCloseAssistant: boolean; - /** Show file attachment controls in chat input */ - showFileControls: boolean; - /** Custom greeting message (overrides default) */ - customGreeting?: string; - /** Enable embedded mode (flex layout, no fixed positioning) */ - embeddedMode: boolean; - /** Enable full-page mode (fixed positioning with sidenav awareness) */ - fullPageMode: boolean; -} - -@Component({ - selector: 'app-chat-container', - standalone: true, - imports: [ - MessageListComponent, - ChatInputComponent, - AnimatedTextComponent, - ParagraphSkeletonComponent, - Topnav, - NgIcon - ], - providers: [provideIcons({ heroXMark })], - changeDetection: ChangeDetectionStrategy.OnPush, - templateUrl: './chat-container.component.html', - styleUrl: './chat-container.component.css' -}) -export class ChatContainerComponent { - // Inject sidenav service for full-page mode positioning - protected sidenavService = inject(SidenavService); - - // Required inputs - messages = input.required(); - sessionId = input(null); - - // Optional inputs - assistant = input(null); - assistantError = input(null); - isChatLoading = input(false); - isLoadingSession = input(false); - streamingMessageId = input(null); - greetingMessage = input('How can I help you today?'); - - // Configuration with defaults - config = input>({}); - - protected readonly resolvedConfig = computed(() => ({ - showTopnav: false, - showEmptyState: true, - allowCloseAssistant: true, - showFileControls: true, - embeddedMode: false, - fullPageMode: false, - ...this.config() - })); - - // Output events - messageSubmitted = output<{ content: string; timestamp: Date; fileUploadIds?: string[] }>(); - messageCancelled = output(); - fileAttached = output(); - settingsToggled = output(); - assistantClosed = output(); - - // Computed signals - protected readonly hasMessages = computed(() => this.messages().length > 0); - protected readonly showSkeleton = computed(() => this.isLoadingSession() && !this.hasMessages()); - protected readonly canCloseAssistant = computed(() => - this.resolvedConfig().allowCloseAssistant && !this.hasMessages() && !!this.assistant() - ); - protected readonly isSidenavCollapsed = computed(() => this.sidenavService.isCollapsed()); -} -``` - -**CSS Classes:** - -| Class | Mode | Description | -|-------|------|-------------| -| `.embedded` | Embedded | Flex layout, relative positioning, border separators | -| `.full-page` | Full-page | Fixed positioning for topnav/footer | -| `.sidenav-expanded` | Full-page | Applies `left: 18rem` offset on lg screens | - -**CSS Structure:** - -```css -/* Use media query for sidenav-aware positioning */ -@media (min-width: 1024px) { - .chat-input-footer.full-page.sidenav-expanded, - .chat-container-empty.full-page.sidenav-expanded, - .chat-topnav-wrapper.sidenav-expanded { - left: 18rem; /* 72 in Tailwind = 18rem */ - } -} - -.chat-topnav-wrapper { - @apply fixed top-0 left-0 right-0 z-40 transition-[left] duration-300; -} - -.chat-input-footer.full-page { - @apply pb-4 fixed bottom-0 left-0 right-0 transition-[left] duration-300; -} - -.chat-container-empty.full-page { - @apply fixed inset-0 transition-[left] duration-300; -} -``` - -### AssistantPreviewComponent - -**Purpose:** Wrapper component for the preview panel that provides the preview-specific chat service. - -**File:** `assistants/assistant-form/components/assistant-preview.component.ts` - -```typescript -@Component({ - selector: 'app-assistant-preview', - standalone: true, - imports: [ChatContainerComponent, NgIcon], - providers: [ - PreviewChatService, // Component-scoped - StreamParserService, // Component-scoped instance - provideIcons({ heroSparkles }) - ], - template: ` - @if (!assistantId()) { - -
-
- -

- Save your assistant to enable the chat preview -

-
-
- } @else { - - } - `, - changeDetection: ChangeDetectionStrategy.OnPush -}) -export class AssistantPreviewComponent implements OnDestroy { - protected previewChatService = inject(PreviewChatService); - - // Inputs from parent form - assistantId = input(null); - name = input(''); - description = input(''); - instructions = input(''); - - readonly chatConfig: Partial = { - embeddedMode: true, - allowCloseAssistant: false, - showEmptyState: true, - showTopnav: false, - showFileControls: false - }; - - // Build assistant object for display - protected readonly assistantObject = computed(() => ({ - id: this.assistantId() || '', - name: this.name() || 'New Assistant', - description: this.description() || '', - instructions: this.instructions() || '', - // Required fields with defaults - ownerId: '', - ownerName: '', - tags: [], - usageCount: 0, - status: 'active' as const, - createdAt: new Date().toISOString(), - updatedAt: new Date().toISOString() - })); - - protected readonly greetingMessage = computed(() => - `Chat with ${this.name() || 'your assistant'}` - ); - - onMessageSubmitted(event: { content: string }) { - const id = this.assistantId(); - if (id) { - this.previewChatService.sendMessage(event.content, id); - } - } - - onMessageCancelled() { - this.previewChatService.cancelRequest(); - } - - ngOnDestroy() { - this.previewChatService.reset(); - } -} -``` - ---- - -## Service Specifications - -### PreviewChatService - -**Purpose:** Component-scoped service for managing preview chat state and API communication. - -**File:** `assistants/assistant-form/services/preview-chat.service.ts` - -**Key Design Decisions:** -1. **Component-scoped** - Provided at component level, not root -2. **Own StreamParserService** - Doesn't share with main chat -3. **No global state mutation** - Does NOT modify ChatStateService - -```typescript -import { PREVIEW_SESSION_PREFIX } from '../../../shared/constants/session.constants'; - -@Injectable() // NOT providedIn: 'root' - component scoped -export class PreviewChatService { - private authService = inject(AuthService); - private modelService = inject(ModelService); - private toolService = inject(ToolService); - private streamParser = inject(StreamParserService); // Will be component-scoped instance - - // Local state - private messagesSignal = signal([]); - private isLoadingSignal = signal(false); - private streamingMessageIdSignal = signal(null); - private abortController: AbortController | null = null; - private previewSessionId = `${PREVIEW_SESSION_PREFIX}${uuidv4()}`; - private messageCount = 0; - - // Public readonly signals - readonly messages = this.messagesSignal.asReadonly(); - readonly isLoading = this.isLoadingSignal.asReadonly(); - readonly streamingMessageId = this.streamingMessageIdSignal.asReadonly(); - - async sendMessage(content: string, assistantId: string): Promise { - if (this.isLoadingSignal() || !content.trim() || !assistantId) return; - - // Create and add user message - const userMessage = this.createUserMessage(content); - this.messagesSignal.update(msgs => [...msgs, userMessage]); - this.messageCount++; - - // Start streaming - this.isLoadingSignal.set(true); - this.abortController = new AbortController(); - this.streamParser.reset(this.previewSessionId, this.messageCount); - - try { - await this.streamChatRequest(content, assistantId); - // Sync messages from parser - this.syncMessagesFromParser(); - } catch (error) { - if ((error as Error).name !== 'AbortError') { - this.addErrorMessage(); - } - } finally { - this.isLoadingSignal.set(false); - this.streamingMessageIdSignal.set(null); - this.abortController = null; - } - } - - cancelRequest(): void { - this.abortController?.abort(); - this.isLoadingSignal.set(false); - this.streamingMessageIdSignal.set(null); - } - - clearMessages(): void { - this.messagesSignal.set([]); - this.messageCount = 0; - this.streamParser.reset(); - } - - reset(): void { - this.cancelRequest(); - this.clearMessages(); - this.previewSessionId = `${PREVIEW_SESSION_PREFIX}${uuidv4()}`; - } - - private async streamChatRequest(message: string, assistantId: string): Promise { - const token = await this.getBearerToken(); - const enabledTools = this.toolService.getEnabledToolIds(); - - const requestObject: Record = { - message, - session_id: this.previewSessionId, - assistant_id: assistantId, - enabled_tools: enabledTools - }; - - // Only include model if not default - const selectedModel = this.modelService.getSelectedModel(); - if (!this.modelService.isUsingDefaultModel() && selectedModel) { - requestObject['model_id'] = selectedModel.modelId; - requestObject['provider'] = selectedModel.provider; - } - - await fetchEventSource(`${environment.inferenceApiUrl}/invocations?qualifier=DEFAULT`, { - method: 'POST', - headers: { - 'Content-Type': 'application/json', - 'Authorization': `Bearer ${token}`, - 'Accept': 'text/event-stream' - }, - body: JSON.stringify(requestObject), - signal: this.abortController?.signal, - onmessage: (msg) => { - if (msg.data) { - try { - const data = JSON.parse(msg.data); - this.streamParser.parseEventSourceMessage(msg.event, data); - // Update streaming message ID - this.streamingMessageIdSignal.set(this.streamParser.streamingMessageId()); - // Sync messages reactively - this.syncMessagesFromParser(); - } catch { /* ignore parse errors */ } - } - }, - onerror: (err) => { throw err; } - }); - } - - private syncMessagesFromParser(): void { - const parserMessages = this.streamParser.allMessages(); - const assistantMessages = parserMessages.filter(m => m.role === 'assistant'); - const userMessages = this.messagesSignal().filter(m => m.role === 'user'); - this.messagesSignal.set([...userMessages, ...assistantMessages]); - } -} -``` - -### ChatInputComponent Modification - -**Purpose:** Accept loading state as input instead of reading from global ChatStateService. - -**File:** `session/components/chat-input/chat-input.component.ts` - -```typescript -@Component({...}) -export class ChatInputComponent { - // NEW: Accept loading state as input - isChatLoading = input(undefined); - - // Existing injection for fallback - private chatState = inject(ChatStateService); - - // Computed that prefers input over global state - protected readonly isLoading = computed(() => - this.isChatLoading() ?? this.chatState.isChatLoading() - ); -} -``` - -Then in template, use `isLoading()` instead of `chatState.isChatLoading()`. - -### ChatContainerComponent - Pass Loading State - -```html - -``` - ---- - -## Shared Constants - -**File:** `shared/constants/session.constants.ts` - -```typescript -/** - * Prefix for preview session IDs. - * Sessions with this prefix are recognized by the backend and skip persistence. - */ -export const PREVIEW_SESSION_PREFIX = 'preview-'; - -/** - * Check if a session ID is a preview session. - */ -export function isPreviewSession(sessionId: string): boolean { - return sessionId.startsWith(PREVIEW_SESSION_PREFIX); -} -``` - ---- - -## File Changes Summary - -### New Files - -| File | Purpose | -|------|---------| -| `session/components/chat-container/chat-container.component.ts` | Reusable chat UI component | -| `session/components/chat-container/chat-container.component.html` | Chat container template | -| `session/components/chat-container/chat-container.component.css` | Chat container styles | -| `assistants/assistant-form/components/assistant-preview.component.ts` | Preview panel component | -| `assistants/assistant-form/services/preview-chat.service.ts` | Preview-specific chat service | -| `shared/constants/session.constants.ts` | Shared constants for session handling | - -### Modified Files - -| File | Changes | -|------|---------| -| `session/session.page.ts` | Use ChatContainerComponent, remove duplicated logic | -| `session/session.page.html` | Replace duplicated template with ChatContainerComponent | -| `session/components/chat-input/chat-input.component.ts` | Add `isChatLoading` input | -| `assistants/assistant-form/assistant-form.page.ts` | Add sidenav hide/show, split layout | -| `assistants/assistant-form/assistant-form.page.html` | Two-column layout with preview | -| `backend/.../chat/routes.py` | Add `is_preview_session()` helper, skip persistence | - -### Files to Export - -Add to barrel files: -- `session/components/chat-container/index.ts` -- `shared/constants/index.ts` - ---- - -## Testing Checklist - -### Backend -- [ ] Preview session (`preview-*`) skips message persistence -- [ ] Preview session skips session state validation -- [ ] Preview session skips assistant_id preference storage -- [ ] Regular sessions still persist correctly -- [ ] Multi-turn conversations work in preview (agent has context) - -### Frontend - Preview -- [ ] Preview appears when assistant is saved -- [ ] Placeholder shown when assistant not yet saved -- [ ] Messages stream correctly with tool use -- [ ] Tool results display properly -- [ ] Citations display properly -- [ ] Loading state shows/hides correctly -- [ ] Cancel button works -- [ ] Multi-turn conversation maintains context -- [ ] Clearing messages works -- [ ] Leaving and returning to form resets preview - -### Frontend - Session Page -- [ ] Session page renders correctly with ChatContainerComponent -- [ ] Topnav positioning correct with sidenav open/closed -- [ ] Chat input positioning correct with sidenav open/closed -- [ ] Empty state displays correctly -- [ ] Skeleton loading displays correctly -- [ ] All existing functionality preserved - -### Frontend - Isolation -- [ ] Preview chat doesn't affect main chat loading state -- [ ] Main chat doesn't affect preview state -- [ ] Running both simultaneously works correctly - ---- - -## Migration Notes - -1. **Do not incrementally migrate** - Replace all at once to avoid partial states -2. **Test sidenav transitions** - Ensure smooth animation when toggling -3. **Verify tool rendering** - Preview must handle all tool types the main chat does -4. **Check mobile responsiveness** - Preview panel should handle narrow widths gracefully - ---- - -## Future Improvements (Out of Scope) - -1. **NoOpSessionManager** - For completely stateless preview (no AgentCore Memory writes at all) -2. **Preview history persistence** - Save/restore preview conversations per assistant -3. **Side-by-side comparison** - Compare different assistant configurations -4. **Preview in modal** - Alternative to split layout for smaller screens diff --git a/frontend/ai.client/package-lock.json b/frontend/ai.client/package-lock.json index c2167245..bca23c7c 100644 --- a/frontend/ai.client/package-lock.json +++ b/frontend/ai.client/package-lock.json @@ -1,28 +1,28 @@ { "name": "ai.client", - "version": "1.0.0-beta.20", + "version": "1.0.0-beta.22", "lockfileVersion": 3, "requires": true, "packages": { "": { "name": "ai.client", - "version": "1.0.0-beta.20", - "dependencies": { - "@angular/cdk": "21.2.4", - "@angular/common": "21.2.6", - "@angular/compiler": "21.2.6", - "@angular/core": "21.2.6", - "@angular/forms": "21.2.6", - "@angular/platform-browser": "21.2.6", - "@angular/router": "21.2.6", + "version": "1.0.0-beta.22", + "dependencies": { + "@angular/cdk": "21.2.5", + "@angular/common": "21.2.7", + "@angular/compiler": "21.2.7", + "@angular/core": "21.2.7", + "@angular/forms": "21.2.7", + "@angular/platform-browser": "21.2.7", + "@angular/router": "21.2.7", "@ctrl/ngx-emoji-mart": "9.3.0", "@microsoft/fetch-event-source": "2.0.1", "@ng-icons/core": "33.2.0", "@ng-icons/heroicons": "33.2.0", "chart.js": "4.5.1", - "katex": "0.16.44", - "marked": "17.0.5", - "mermaid": "11.13.0", + "katex": "0.16.45", + "marked": "17.0.6", + "mermaid": "11.14.0", "ng2-charts": "10.0.0", "ngx-markdown": "21.1.0", "prismjs": "1.30.0", @@ -31,11 +31,11 @@ "uuid": "13.0.0" }, "devDependencies": { - "@analogjs/vite-plugin-angular": "3.0.0-alpha.18", - "@analogjs/vitest-angular": "3.0.0-alpha.18", - "@angular/build": "21.2.5", - "@angular/cli": "21.2.5", - "@angular/compiler-cli": "21.2.6", + "@analogjs/vite-plugin-angular": "3.0.0-alpha.26", + "@analogjs/vitest-angular": "3.0.0-alpha.26", + "@angular/build": "21.2.6", + "@angular/cli": "21.2.6", + "@angular/compiler-cli": "21.2.7", "@tailwindcss/postcss": "4.2.2", "@vitest/coverage-v8": "4.1.2", "fast-check": "4.6.0", @@ -283,23 +283,25 @@ } }, "node_modules/@analogjs/vite-plugin-angular": { - "version": "3.0.0-alpha.18", - "resolved": "https://registry.npmjs.org/@analogjs/vite-plugin-angular/-/vite-plugin-angular-3.0.0-alpha.18.tgz", - "integrity": "sha512-WVYRQ/cpOPdkAyeRFxgpu0rIzo8yiVV+aJ/dVAw2dOTSo9YcPBIWdtu6yEx3Vy+nA9S3HKErMZ2pvZbknbNySg==", + "version": "3.0.0-alpha.26", + "resolved": "https://registry.npmjs.org/@analogjs/vite-plugin-angular/-/vite-plugin-angular-3.0.0-alpha.26.tgz", + "integrity": "sha512-hdBdQu3to4mkFCEE1WCthiSP6w6FSLALav257KHC5fjSFP6DzT3wlFOzSjO0G3Y0/aWr6/E4phOTYlzW7PgpCA==", "dev": true, "license": "MIT", "dependencies": { - "oxc-parser": "^0.121.0", - "oxc-resolver": "^11.19.0", - "rolldown": "^1.0.0-rc.11", - "tinyglobby": "^0.2.14" + "es-toolkit": "^1.45.1", + "obug": "^2.1.1", + "oxc-parser": "^0.123.0", + "oxc-resolver": "^11.19.1", + "rolldown": "^1.0.0-rc.13", + "tinyglobby": "^0.2.15" }, "funding": { "type": "github", "url": "https://github.com/sponsors/brandonroberts" }, "peerDependencies": { - "@angular-devkit/build-angular": "^15.0.0 || ^16.0.0 || ^17.0.0 || ^18.0.0 || ^19.0.0 || ^20.0.0 || ^21.0.0", + "@angular-devkit/build-angular": "^16.0.0 || ^17.0.0 || ^18.0.0 || ^19.0.0 || ^20.0.0 || ^21.0.0", "@angular/build": "^18.0.0 || ^19.0.0 || ^20.0.0 || ^21.0.0" }, "peerDependenciesMeta": { @@ -312,9 +314,9 @@ } }, "node_modules/@analogjs/vite-plugin-angular/node_modules/@oxc-project/types": { - "version": "0.122.0", - "resolved": "https://registry.npmjs.org/@oxc-project/types/-/types-0.122.0.tgz", - "integrity": "sha512-oLAl5kBpV4w69UtFZ9xqcmTi+GENWOcPF7FCrczTiBbmC0ibXxCwyvZGbO39rCVEuLGAZM84DH0pUIyyv/YJzA==", + "version": "0.123.0", + "resolved": "https://registry.npmjs.org/@oxc-project/types/-/types-0.123.0.tgz", + "integrity": "sha512-YtECP/y8Mj1lSHiUWGSRzy/C6teUKlS87dEfuVKT09LgQbUsBW1rNg+MiJ4buGu3yuADV60gbIvo9/HplA56Ew==", "dev": true, "license": "MIT", "funding": { @@ -322,9 +324,9 @@ } }, "node_modules/@analogjs/vite-plugin-angular/node_modules/@rolldown/binding-android-arm64": { - "version": "1.0.0-rc.12", - "resolved": "https://registry.npmjs.org/@rolldown/binding-android-arm64/-/binding-android-arm64-1.0.0-rc.12.tgz", - "integrity": "sha512-pv1y2Fv0JybcykuiiD3qBOBdz6RteYojRFY1d+b95WVuzx211CRh+ytI/+9iVyWQ6koTh5dawe4S/yRfOFjgaA==", + "version": "1.0.0-rc.13", + "resolved": "https://registry.npmjs.org/@rolldown/binding-android-arm64/-/binding-android-arm64-1.0.0-rc.13.tgz", + "integrity": "sha512-5ZiiecKH2DXAVJTNN13gNMUcCDg4Jy8ZjbXEsPnqa248wgOVeYRX0iqXXD5Jz4bI9BFHgKsI2qmyJynstbmr+g==", "cpu": [ "arm64" ], @@ -339,9 +341,9 @@ } }, "node_modules/@analogjs/vite-plugin-angular/node_modules/@rolldown/binding-darwin-arm64": { - "version": "1.0.0-rc.12", - "resolved": "https://registry.npmjs.org/@rolldown/binding-darwin-arm64/-/binding-darwin-arm64-1.0.0-rc.12.tgz", - "integrity": "sha512-cFYr6zTG/3PXXF3pUO+umXxt1wkRK/0AYT8lDwuqvRC+LuKYWSAQAQZjCWDQpAH172ZV6ieYrNnFzVVcnSflAg==", + "version": "1.0.0-rc.13", + "resolved": "https://registry.npmjs.org/@rolldown/binding-darwin-arm64/-/binding-darwin-arm64-1.0.0-rc.13.tgz", + "integrity": "sha512-tz/v/8G77seu8zAB3A5sK3UFoOl06zcshEzhUO62sAEtrEuW/H1CcyoupOrD+NbQJytYgA4CppXPzlrmp4JZKA==", "cpu": [ "arm64" ], @@ -356,9 +358,9 @@ } }, "node_modules/@analogjs/vite-plugin-angular/node_modules/@rolldown/binding-darwin-x64": { - "version": "1.0.0-rc.12", - "resolved": "https://registry.npmjs.org/@rolldown/binding-darwin-x64/-/binding-darwin-x64-1.0.0-rc.12.tgz", - "integrity": "sha512-ZCsYknnHzeXYps0lGBz8JrF37GpE9bFVefrlmDrAQhOEi4IOIlcoU1+FwHEtyXGx2VkYAvhu7dyBf75EJQffBw==", + "version": "1.0.0-rc.13", + "resolved": "https://registry.npmjs.org/@rolldown/binding-darwin-x64/-/binding-darwin-x64-1.0.0-rc.13.tgz", + "integrity": "sha512-8DakphqOz8JrMYWTJmWA+vDJxut6LijZ8Xcdc4flOlAhU7PNVwo2MaWBF9iXjJAPo5rC/IxEFZDhJ3GC7NHvug==", "cpu": [ "x64" ], @@ -373,9 +375,9 @@ } }, "node_modules/@analogjs/vite-plugin-angular/node_modules/@rolldown/binding-freebsd-x64": { - "version": "1.0.0-rc.12", - "resolved": "https://registry.npmjs.org/@rolldown/binding-freebsd-x64/-/binding-freebsd-x64-1.0.0-rc.12.tgz", - "integrity": "sha512-dMLeprcVsyJsKolRXyoTH3NL6qtsT0Y2xeuEA8WQJquWFXkEC4bcu1rLZZSnZRMtAqwtrF/Ib9Ddtpa/Gkge9Q==", + "version": "1.0.0-rc.13", + "resolved": "https://registry.npmjs.org/@rolldown/binding-freebsd-x64/-/binding-freebsd-x64-1.0.0-rc.13.tgz", + "integrity": "sha512-4wBQFfjDuXYN/SVI8inBF3Aa+isq40rc6VMFbk5jcpolUBTe5cYnMsHZ51nFWsx3PVyyNN3vgoESki0Hmr/4BA==", "cpu": [ "x64" ], @@ -390,9 +392,9 @@ } }, "node_modules/@analogjs/vite-plugin-angular/node_modules/@rolldown/binding-linux-arm-gnueabihf": { - "version": "1.0.0-rc.12", - "resolved": "https://registry.npmjs.org/@rolldown/binding-linux-arm-gnueabihf/-/binding-linux-arm-gnueabihf-1.0.0-rc.12.tgz", - "integrity": "sha512-YqWjAgGC/9M1lz3GR1r1rP79nMgo3mQiiA+Hfo+pvKFK1fAJ1bCi0ZQVh8noOqNacuY1qIcfyVfP6HoyBRZ85Q==", + "version": "1.0.0-rc.13", + "resolved": "https://registry.npmjs.org/@rolldown/binding-linux-arm-gnueabihf/-/binding-linux-arm-gnueabihf-1.0.0-rc.13.tgz", + "integrity": "sha512-JW/e4yPIXLms+jmnbwwy5LA/LxVwZUWLN8xug+V200wzaVi5TEGIWQlh8o91gWYFxW609euI98OCCemmWGuPrw==", "cpu": [ "arm" ], @@ -407,9 +409,9 @@ } }, "node_modules/@analogjs/vite-plugin-angular/node_modules/@rolldown/binding-linux-arm64-gnu": { - "version": "1.0.0-rc.12", - "resolved": "https://registry.npmjs.org/@rolldown/binding-linux-arm64-gnu/-/binding-linux-arm64-gnu-1.0.0-rc.12.tgz", - "integrity": "sha512-/I5AS4cIroLpslsmzXfwbe5OmWvSsrFuEw3mwvbQ1kDxJ822hFHIx+vsN/TAzNVyepI/j/GSzrtCIwQPeKCLIg==", + "version": "1.0.0-rc.13", + "resolved": "https://registry.npmjs.org/@rolldown/binding-linux-arm64-gnu/-/binding-linux-arm64-gnu-1.0.0-rc.13.tgz", + "integrity": "sha512-ZfKWpXiUymDnavepCaM6KG/uGydJ4l2nBmMxg60Ci4CbeefpqjPWpfaZM7PThOhk2dssqBAcwLc6rAyr0uTdXg==", "cpu": [ "arm64" ], @@ -424,9 +426,9 @@ } }, "node_modules/@analogjs/vite-plugin-angular/node_modules/@rolldown/binding-linux-arm64-musl": { - "version": "1.0.0-rc.12", - "resolved": "https://registry.npmjs.org/@rolldown/binding-linux-arm64-musl/-/binding-linux-arm64-musl-1.0.0-rc.12.tgz", - "integrity": "sha512-V6/wZztnBqlx5hJQqNWwFdxIKN0m38p8Jas+VoSfgH54HSj9tKTt1dZvG6JRHcjh6D7TvrJPWFGaY9UBVOaWPw==", + "version": "1.0.0-rc.13", + "resolved": "https://registry.npmjs.org/@rolldown/binding-linux-arm64-musl/-/binding-linux-arm64-musl-1.0.0-rc.13.tgz", + "integrity": "sha512-bmRg3O6Z0gq9yodKKWCIpnlH051sEfdVwt+6m5UDffAQMUUqU0xjnQqqAUm+Gu7ofAAly9DqiQDtKu2nPDEABA==", "cpu": [ "arm64" ], @@ -441,9 +443,9 @@ } }, "node_modules/@analogjs/vite-plugin-angular/node_modules/@rolldown/binding-linux-x64-gnu": { - "version": "1.0.0-rc.12", - "resolved": "https://registry.npmjs.org/@rolldown/binding-linux-x64-gnu/-/binding-linux-x64-gnu-1.0.0-rc.12.tgz", - "integrity": "sha512-RNrafz5bcwRy+O9e6P8Z/OCAJW/A+qtBczIqVYwTs14pf4iV1/+eKEjdOUta93q2TsT/FI0XYDP3TCky38LMAg==", + "version": "1.0.0-rc.13", + "resolved": "https://registry.npmjs.org/@rolldown/binding-linux-x64-gnu/-/binding-linux-x64-gnu-1.0.0-rc.13.tgz", + "integrity": "sha512-eRrPvat2YaVQcwwKi/JzOP6MKf1WRnOCr+VaI3cTWz3ZoLcP/654z90lVCJ4dAuMEpPdke0n+qyAqXDZdIC4rA==", "cpu": [ "x64" ], @@ -458,9 +460,9 @@ } }, "node_modules/@analogjs/vite-plugin-angular/node_modules/@rolldown/binding-linux-x64-musl": { - "version": "1.0.0-rc.12", - "resolved": "https://registry.npmjs.org/@rolldown/binding-linux-x64-musl/-/binding-linux-x64-musl-1.0.0-rc.12.tgz", - "integrity": "sha512-Jpw/0iwoKWx3LJ2rc1yjFrj+T7iHZn2JDg1Yny1ma0luviFS4mhAIcd1LFNxK3EYu3DHWCps0ydXQ5i/rrJ2ig==", + "version": "1.0.0-rc.13", + "resolved": "https://registry.npmjs.org/@rolldown/binding-linux-x64-musl/-/binding-linux-x64-musl-1.0.0-rc.13.tgz", + "integrity": "sha512-PsdONiFRp8hR8KgVjTWjZ9s7uA3uueWL0t74/cKHfM4dR5zXYv4AjB8BvA+QDToqxAFg4ZkcVEqeu5F7inoz5w==", "cpu": [ "x64" ], @@ -475,9 +477,9 @@ } }, "node_modules/@analogjs/vite-plugin-angular/node_modules/@rolldown/binding-openharmony-arm64": { - "version": "1.0.0-rc.12", - "resolved": "https://registry.npmjs.org/@rolldown/binding-openharmony-arm64/-/binding-openharmony-arm64-1.0.0-rc.12.tgz", - "integrity": "sha512-vRugONE4yMfVn0+7lUKdKvN4D5YusEiPilaoO2sgUWpCvrncvWgPMzK00ZFFJuiPgLwgFNP5eSiUlv2tfc+lpA==", + "version": "1.0.0-rc.13", + "resolved": "https://registry.npmjs.org/@rolldown/binding-openharmony-arm64/-/binding-openharmony-arm64-1.0.0-rc.13.tgz", + "integrity": "sha512-hCNXgC5dI3TVOLrPT++PKFNZ+1EtS0mLQwfXXXSUD/+rGlB65gZDwN/IDuxLpQP4x8RYYHqGomlUXzpO8aVI2w==", "cpu": [ "arm64" ], @@ -492,9 +494,9 @@ } }, "node_modules/@analogjs/vite-plugin-angular/node_modules/@rolldown/binding-wasm32-wasi": { - "version": "1.0.0-rc.12", - "resolved": "https://registry.npmjs.org/@rolldown/binding-wasm32-wasi/-/binding-wasm32-wasi-1.0.0-rc.12.tgz", - "integrity": "sha512-ykGiLr/6kkiHc0XnBfmFJuCjr5ZYKKofkx+chJWDjitX+KsJuAmrzWhwyOMSHzPhzOHOy7u9HlFoa5MoAOJ/Zg==", + "version": "1.0.0-rc.13", + "resolved": "https://registry.npmjs.org/@rolldown/binding-wasm32-wasi/-/binding-wasm32-wasi-1.0.0-rc.13.tgz", + "integrity": "sha512-viLS5C5et8NFtLWw9Sw3M/w4vvnVkbWkO7wSNh3C+7G1+uCkGpr6PcjNDSFcNtmXY/4trjPBqUfcOL+P3sWy/g==", "cpu": [ "wasm32" ], @@ -502,16 +504,18 @@ "license": "MIT", "optional": true, "dependencies": { - "@napi-rs/wasm-runtime": "^1.1.1" + "@emnapi/core": "1.9.1", + "@emnapi/runtime": "1.9.1", + "@napi-rs/wasm-runtime": "^1.1.2" }, "engines": { "node": ">=14.0.0" } }, "node_modules/@analogjs/vite-plugin-angular/node_modules/@rolldown/binding-win32-arm64-msvc": { - "version": "1.0.0-rc.12", - "resolved": "https://registry.npmjs.org/@rolldown/binding-win32-arm64-msvc/-/binding-win32-arm64-msvc-1.0.0-rc.12.tgz", - "integrity": "sha512-5eOND4duWkwx1AzCxadcOrNeighiLwMInEADT0YM7xeEOOFcovWZCq8dadXgcRHSf3Ulh1kFo/qvzoFiCLOL1Q==", + "version": "1.0.0-rc.13", + "resolved": "https://registry.npmjs.org/@rolldown/binding-win32-arm64-msvc/-/binding-win32-arm64-msvc-1.0.0-rc.13.tgz", + "integrity": "sha512-Fqa3Tlt1xL4wzmAYxGNFV36Hb+VfPc9PYU+E25DAnswXv3ODDu/yyWjQDbXMo5AGWkQVjLgQExuVu8I/UaZhPQ==", "cpu": [ "arm64" ], @@ -526,9 +530,9 @@ } }, "node_modules/@analogjs/vite-plugin-angular/node_modules/@rolldown/binding-win32-x64-msvc": { - "version": "1.0.0-rc.12", - "resolved": "https://registry.npmjs.org/@rolldown/binding-win32-x64-msvc/-/binding-win32-x64-msvc-1.0.0-rc.12.tgz", - "integrity": "sha512-PyqoipaswDLAZtot351MLhrlrh6lcZPo2LSYE+VDxbVk24LVKAGOuE4hb8xZQmrPAuEtTZW8E6D2zc5EUZX4Lw==", + "version": "1.0.0-rc.13", + "resolved": "https://registry.npmjs.org/@rolldown/binding-win32-x64-msvc/-/binding-win32-x64-msvc-1.0.0-rc.13.tgz", + "integrity": "sha512-/pLI5kPkGEi44TDlnbio3St/5gUFeN51YWNAk/Gnv6mEQBOahRBh52qVFVBpmrnU01n2yysvBML9Ynu7K4kGAQ==", "cpu": [ "x64" ], @@ -543,21 +547,21 @@ } }, "node_modules/@analogjs/vite-plugin-angular/node_modules/@rolldown/pluginutils": { - "version": "1.0.0-rc.12", - "resolved": "https://registry.npmjs.org/@rolldown/pluginutils/-/pluginutils-1.0.0-rc.12.tgz", - "integrity": "sha512-HHMwmarRKvoFsJorqYlFeFRzXZqCt2ETQlEDOb9aqssrnVBB1/+xgTGtuTrIk5vzLNX1MjMtTf7W9z3tsSbrxw==", + "version": "1.0.0-rc.13", + "resolved": "https://registry.npmjs.org/@rolldown/pluginutils/-/pluginutils-1.0.0-rc.13.tgz", + "integrity": "sha512-3ngTAv6F/Py35BsYbeeLeecvhMKdsKm4AoOETVhAA+Qc8nrA2I0kF7oa93mE9qnIurngOSpMnQ0x2nQY2FPviA==", "dev": true, "license": "MIT" }, "node_modules/@analogjs/vite-plugin-angular/node_modules/rolldown": { - "version": "1.0.0-rc.12", - "resolved": "https://registry.npmjs.org/rolldown/-/rolldown-1.0.0-rc.12.tgz", - "integrity": "sha512-yP4USLIMYrwpPHEFB5JGH1uxhcslv6/hL0OyvTuY+3qlOSJvZ7ntYnoWpehBxufkgN0cvXxppuTu5hHa/zPh+A==", + "version": "1.0.0-rc.13", + "resolved": "https://registry.npmjs.org/rolldown/-/rolldown-1.0.0-rc.13.tgz", + "integrity": "sha512-bvVj8YJmf0rq4pSFmH7laLa6pYrhghv3PRzrCdRAr23g66zOKVJ4wkvFtgohtPLWmthgg8/rkaqRHrpUEh0Zbw==", "dev": true, "license": "MIT", "dependencies": { - "@oxc-project/types": "=0.122.0", - "@rolldown/pluginutils": "1.0.0-rc.12" + "@oxc-project/types": "=0.123.0", + "@rolldown/pluginutils": "1.0.0-rc.13" }, "bin": { "rolldown": "bin/cli.mjs" @@ -566,31 +570,31 @@ "node": "^20.19.0 || >=22.12.0" }, "optionalDependencies": { - "@rolldown/binding-android-arm64": "1.0.0-rc.12", - "@rolldown/binding-darwin-arm64": "1.0.0-rc.12", - "@rolldown/binding-darwin-x64": "1.0.0-rc.12", - "@rolldown/binding-freebsd-x64": "1.0.0-rc.12", - "@rolldown/binding-linux-arm-gnueabihf": "1.0.0-rc.12", - "@rolldown/binding-linux-arm64-gnu": "1.0.0-rc.12", - "@rolldown/binding-linux-arm64-musl": "1.0.0-rc.12", - "@rolldown/binding-linux-ppc64-gnu": "1.0.0-rc.12", - "@rolldown/binding-linux-s390x-gnu": "1.0.0-rc.12", - "@rolldown/binding-linux-x64-gnu": "1.0.0-rc.12", - "@rolldown/binding-linux-x64-musl": "1.0.0-rc.12", - "@rolldown/binding-openharmony-arm64": "1.0.0-rc.12", - "@rolldown/binding-wasm32-wasi": "1.0.0-rc.12", - "@rolldown/binding-win32-arm64-msvc": "1.0.0-rc.12", - "@rolldown/binding-win32-x64-msvc": "1.0.0-rc.12" + "@rolldown/binding-android-arm64": "1.0.0-rc.13", + "@rolldown/binding-darwin-arm64": "1.0.0-rc.13", + "@rolldown/binding-darwin-x64": "1.0.0-rc.13", + "@rolldown/binding-freebsd-x64": "1.0.0-rc.13", + "@rolldown/binding-linux-arm-gnueabihf": "1.0.0-rc.13", + "@rolldown/binding-linux-arm64-gnu": "1.0.0-rc.13", + "@rolldown/binding-linux-arm64-musl": "1.0.0-rc.13", + "@rolldown/binding-linux-ppc64-gnu": "1.0.0-rc.13", + "@rolldown/binding-linux-s390x-gnu": "1.0.0-rc.13", + "@rolldown/binding-linux-x64-gnu": "1.0.0-rc.13", + "@rolldown/binding-linux-x64-musl": "1.0.0-rc.13", + "@rolldown/binding-openharmony-arm64": "1.0.0-rc.13", + "@rolldown/binding-wasm32-wasi": "1.0.0-rc.13", + "@rolldown/binding-win32-arm64-msvc": "1.0.0-rc.13", + "@rolldown/binding-win32-x64-msvc": "1.0.0-rc.13" } }, "node_modules/@analogjs/vitest-angular": { - "version": "3.0.0-alpha.18", - "resolved": "https://registry.npmjs.org/@analogjs/vitest-angular/-/vitest-angular-3.0.0-alpha.18.tgz", - "integrity": "sha512-TeYWAJYnFhKiDa67BJ+8aPrUXLJbkufl5M+5KR8O3hMzvWc96OVM7JFB3GaVm5bzxrA+affSPkLBKY9NQwvPuA==", + "version": "3.0.0-alpha.26", + "resolved": "https://registry.npmjs.org/@analogjs/vitest-angular/-/vitest-angular-3.0.0-alpha.26.tgz", + "integrity": "sha512-h5Z3arvEpJcDcCF15PwojShERHcE0tDvJedZ3s3+ymuaBZsr4p7iS1rzGqYH3hSGk9oxucPghJkR8u75brIApA==", "dev": true, "license": "MIT", "dependencies": { - "oxc-transform": "^0.121.0" + "oxc-transform": "^0.123.0" }, "funding": { "type": "github", @@ -610,13 +614,13 @@ } }, "node_modules/@angular-devkit/architect": { - "version": "0.2102.5", - "resolved": "https://registry.npmjs.org/@angular-devkit/architect/-/architect-0.2102.5.tgz", - "integrity": "sha512-9xE7G177R9G9Kte+4AtbEMlEeZUupnvdBUMVBlZRa/n4UDUyAkB/vj58KrzRCCIVQ/ypHVMwUilaDTO484dd+g==", + "version": "0.2102.6", + "resolved": "https://registry.npmjs.org/@angular-devkit/architect/-/architect-0.2102.6.tgz", + "integrity": "sha512-h4qybKypR7OuwcTHPQI1zRm7abXgmPiV49vI2UeMtVVY/GKzru9gMexcYmWabzEyBY8w6VSfWjV2X+eit2EhDQ==", "dev": true, "license": "MIT", "dependencies": { - "@angular-devkit/core": "21.2.5", + "@angular-devkit/core": "21.2.6", "rxjs": "7.8.2" }, "bin": { @@ -629,9 +633,9 @@ } }, "node_modules/@angular-devkit/core": { - "version": "21.2.5", - "resolved": "https://registry.npmjs.org/@angular-devkit/core/-/core-21.2.5.tgz", - "integrity": "sha512-9z9w7UxKKVmib5QHFZTOfJpAiSudqQwwEZFpQy31yaXR3tJw85xO5owi+66sgTpEvNh9Ix2THhcUq//ToP/0VA==", + "version": "21.2.6", + "resolved": "https://registry.npmjs.org/@angular-devkit/core/-/core-21.2.6.tgz", + "integrity": "sha512-u5gPTAY7MC02uACQE39xxiFcm1hslF+ih/f2borMWnhER0JNTpHjLiLRXFkq7or7+VVHU30zfhK4XNAuO4WTIg==", "license": "MIT", "dependencies": { "ajv": "8.18.0", @@ -656,12 +660,12 @@ } }, "node_modules/@angular-devkit/schematics": { - "version": "21.2.5", - "resolved": "https://registry.npmjs.org/@angular-devkit/schematics/-/schematics-21.2.5.tgz", - "integrity": "sha512-gEg84eipTX6lcpNTDVUXBBwp0vs3rXM319Qom+sCLOKBGyqE0mvb1RM1WwfNcyOqeSMQC/vLUwRKqnP0wg1UDg==", + "version": "21.2.6", + "resolved": "https://registry.npmjs.org/@angular-devkit/schematics/-/schematics-21.2.6.tgz", + "integrity": "sha512-hk2duJlPJyiMaI9MVWA5XpmlpD9C4n8qgquV/MJ7/n+ZRSwW3w1ndL5qUmA1ki+4Da54v/Rc8Wt5tUS955+93w==", "license": "MIT", "dependencies": { - "@angular-devkit/core": "21.2.5", + "@angular-devkit/core": "21.2.6", "jsonc-parser": "3.3.1", "magic-string": "0.30.21", "ora": "9.3.0", @@ -674,14 +678,14 @@ } }, "node_modules/@angular/build": { - "version": "21.2.5", - "resolved": "https://registry.npmjs.org/@angular/build/-/build-21.2.5.tgz", - "integrity": "sha512-AfE09K+pkgS3VB84R74XG/XB9LQmO6Q6YfpssjDwMnWGwDGGwUGydXn8AKdhnhI4mM2nFKoe+QYszFgrzu5HeQ==", + "version": "21.2.6", + "resolved": "https://registry.npmjs.org/@angular/build/-/build-21.2.6.tgz", + "integrity": "sha512-PJltYl9/INfz8nZ/KHf39nqlmt3c9PR0jJaZt6hhCPENyAf4PwQpm28erkJmbOYO864goIuws41lduYXyDqQ0Q==", "dev": true, "license": "MIT", "dependencies": { "@ampproject/remapping": "2.3.0", - "@angular-devkit/architect": "0.2102.5", + "@angular-devkit/architect": "0.2102.6", "@babel/core": "7.29.0", "@babel/helper-annotate-as-pure": "7.27.3", "@babel/helper-split-export-declaration": "7.24.7", @@ -724,7 +728,7 @@ "@angular/platform-browser": "^21.0.0", "@angular/platform-server": "^21.0.0", "@angular/service-worker": "^21.0.0", - "@angular/ssr": "^21.2.5", + "@angular/ssr": "^21.2.6", "karma": "^6.4.0", "less": "^4.2.0", "ng-packagr": "^21.0.0", @@ -774,9 +778,9 @@ } }, "node_modules/@angular/cdk": { - "version": "21.2.4", - "resolved": "https://registry.npmjs.org/@angular/cdk/-/cdk-21.2.4.tgz", - "integrity": "sha512-Zv+q9Z/wVWTt0ckuO3gnU7PbpCLTr1tKPEsofLGGzDufA5/85aBLn2UiLcjlY6wQ+V3EMqANhGo/8XJgvBEYFA==", + "version": "21.2.5", + "resolved": "https://registry.npmjs.org/@angular/cdk/-/cdk-21.2.5.tgz", + "integrity": "sha512-F1sVqMAGYoiJNYYaR2cerqTo7IqpxQ3ZtMDxR3rtB0rSSd5UPOIQoqpsfSd6uH8FVnuzKaBII8Mg6YrjClFsng==", "license": "MIT", "dependencies": { "parse5": "^8.0.0", @@ -790,19 +794,19 @@ } }, "node_modules/@angular/cli": { - "version": "21.2.5", - "resolved": "https://registry.npmjs.org/@angular/cli/-/cli-21.2.5.tgz", - "integrity": "sha512-nLpyqXQ0s96jC/vR8CsKM3q94/F/nZwtbjM3E6g5lXpKe7cHfJkCfERPexx+jzzYP5JBhtm+u61aH6auu9KYQw==", + "version": "21.2.6", + "resolved": "https://registry.npmjs.org/@angular/cli/-/cli-21.2.6.tgz", + "integrity": "sha512-I5DOFcIT1HKymyy2f78fjgD0Iv6jG46GbBZ/VxejcnhjubFpuN4CwPdugXf9rIDs8KZQqBzDBFUbq11vnk8h0A==", "dev": true, "license": "MIT", "dependencies": { - "@angular-devkit/architect": "0.2102.5", - "@angular-devkit/core": "21.2.5", - "@angular-devkit/schematics": "21.2.5", + "@angular-devkit/architect": "0.2102.6", + "@angular-devkit/core": "21.2.6", + "@angular-devkit/schematics": "21.2.6", "@inquirer/prompts": "7.10.1", "@listr2/prompt-adapter-inquirer": "3.0.5", "@modelcontextprotocol/sdk": "1.26.0", - "@schematics/angular": "21.2.5", + "@schematics/angular": "21.2.6", "@yarnpkg/lockfile": "1.1.0", "algoliasearch": "5.48.1", "ini": "6.0.0", @@ -825,9 +829,9 @@ } }, "node_modules/@angular/common": { - "version": "21.2.6", - "resolved": "https://registry.npmjs.org/@angular/common/-/common-21.2.6.tgz", - "integrity": "sha512-2FcpZ1h6AZ4JwCIlnpHCYrbRTGQTOj/RFXkuX/qw7K6cFmJGfWFMmr++xWtHZEvUddfbR9hqDo+v1mkqEKE/Kw==", + "version": "21.2.7", + "resolved": "https://registry.npmjs.org/@angular/common/-/common-21.2.7.tgz", + "integrity": "sha512-YFdnU5z8JloJjLYa52OyCOULQhqEE/ym7vKfABySWDsiVXZr9FNmKMeZi/lUcg7ZO22UbBihqW9a9D6VSHOo+g==", "license": "MIT", "dependencies": { "tslib": "^2.3.0" @@ -836,14 +840,14 @@ "node": "^20.19.0 || ^22.12.0 || >=24.0.0" }, "peerDependencies": { - "@angular/core": "21.2.6", + "@angular/core": "21.2.7", "rxjs": "^6.5.3 || ^7.4.0" } }, "node_modules/@angular/compiler": { - "version": "21.2.6", - "resolved": "https://registry.npmjs.org/@angular/compiler/-/compiler-21.2.6.tgz", - "integrity": "sha512-shGkb/aAIPbG8oSYkVJ0msGlRdDVcJBVaUVx2KenMltifQjfLn5N8DFMAzOR6haaA3XeugFExxKqmvySjrVq+A==", + "version": "21.2.7", + "resolved": "https://registry.npmjs.org/@angular/compiler/-/compiler-21.2.7.tgz", + "integrity": "sha512-4J0Nl5gGmr5SKgR3FHK4J6rdG0aP5zAsY3AJU8YXH+D98CeNTjQUD8XHsdD2cTwo08V5mDdFa5VCsREpMPJ5gQ==", "license": "MIT", "dependencies": { "tslib": "^2.3.0" @@ -853,9 +857,9 @@ } }, "node_modules/@angular/compiler-cli": { - "version": "21.2.6", - "resolved": "https://registry.npmjs.org/@angular/compiler-cli/-/compiler-cli-21.2.6.tgz", - "integrity": "sha512-CiPmat4+D+hWXMTAY++09WeII/5D0r6iTjdLdaTq8tlo0uJcrOlazib4CpA94kJ2CRdzfhmC1H+ttwBI1xIlTg==", + "version": "21.2.7", + "resolved": "https://registry.npmjs.org/@angular/compiler-cli/-/compiler-cli-21.2.7.tgz", + "integrity": "sha512-r76vKBM7Wu0N8PTeec7340Gtv1wC7IBQGJOQnukshPgzaabgNKxmUiChGxi+RJNo/Tsdiw9ZfddcBgBjq79ZIg==", "dev": true, "license": "MIT", "dependencies": { @@ -876,7 +880,7 @@ "node": "^20.19.0 || ^22.12.0 || >=24.0.0" }, "peerDependencies": { - "@angular/compiler": "21.2.6", + "@angular/compiler": "21.2.7", "typescript": ">=5.9 <6.1" }, "peerDependenciesMeta": { @@ -886,9 +890,9 @@ } }, "node_modules/@angular/core": { - "version": "21.2.6", - "resolved": "https://registry.npmjs.org/@angular/core/-/core-21.2.6.tgz", - "integrity": "sha512-svgK5DhFlQlS+sMybXftn08rHHRiDGY/uIKT5LZUaKgyffnkPb8uClpMIW0NzANtU8qs8pwgDZFoJw85Ia3oqQ==", + "version": "21.2.7", + "resolved": "https://registry.npmjs.org/@angular/core/-/core-21.2.7.tgz", + "integrity": "sha512-4bnskeRNNOZMn3buVw47Zz9Py4B8AZgYHe5xBEMOY5/yrldb7OFje5gWCWls23P18FKwhl+Xx1hgnOEPSs29gw==", "license": "MIT", "dependencies": { "tslib": "^2.3.0" @@ -897,7 +901,7 @@ "node": "^20.19.0 || ^22.12.0 || >=24.0.0" }, "peerDependencies": { - "@angular/compiler": "21.2.6", + "@angular/compiler": "21.2.7", "rxjs": "^6.5.3 || ^7.4.0", "zone.js": "~0.15.0 || ~0.16.0" }, @@ -911,9 +915,9 @@ } }, "node_modules/@angular/forms": { - "version": "21.2.6", - "resolved": "https://registry.npmjs.org/@angular/forms/-/forms-21.2.6.tgz", - "integrity": "sha512-i8BoWxBAm0g2xOMcQ8wTdj07gqMPIFYIyefCOo0ezcGj5XhYjd+C2UrYnKsup0aMZqqEAO1l2aZbmfHx9xLheQ==", + "version": "21.2.7", + "resolved": "https://registry.npmjs.org/@angular/forms/-/forms-21.2.7.tgz", + "integrity": "sha512-YD/h07cdEeAUs41ysTk6820T0lG/XiQmFiq02d3IsiHYI5Vaj2pg9Ti1wWZYEBM//hVAPTzV0dwdV7Q1Gxju1w==", "license": "MIT", "dependencies": { "@standard-schema/spec": "^1.0.0", @@ -923,16 +927,16 @@ "node": "^20.19.0 || ^22.12.0 || >=24.0.0" }, "peerDependencies": { - "@angular/common": "21.2.6", - "@angular/core": "21.2.6", - "@angular/platform-browser": "21.2.6", + "@angular/common": "21.2.7", + "@angular/core": "21.2.7", + "@angular/platform-browser": "21.2.7", "rxjs": "^6.5.3 || ^7.4.0" } }, "node_modules/@angular/platform-browser": { - "version": "21.2.6", - "resolved": "https://registry.npmjs.org/@angular/platform-browser/-/platform-browser-21.2.6.tgz", - "integrity": "sha512-LW1vPXVHvy71LBahn+fSzPlWQl25kJIdcXq+ptG7HsMVgbPQ3/vvkKXAHYaRdppLGCFL+v+3dQGHYLNLiYL9qg==", + "version": "21.2.7", + "resolved": "https://registry.npmjs.org/@angular/platform-browser/-/platform-browser-21.2.7.tgz", + "integrity": "sha512-nklVhstRZL4wpYg9Cyae/Eyfa7LMpgb0TyD/F//qCuohhM8nM7F+O0ekykGD6H+I34jsvqx6yLS7MicndWVz7Q==", "license": "MIT", "dependencies": { "tslib": "^2.3.0" @@ -941,9 +945,9 @@ "node": "^20.19.0 || ^22.12.0 || >=24.0.0" }, "peerDependencies": { - "@angular/animations": "21.2.6", - "@angular/common": "21.2.6", - "@angular/core": "21.2.6" + "@angular/animations": "21.2.7", + "@angular/common": "21.2.7", + "@angular/core": "21.2.7" }, "peerDependenciesMeta": { "@angular/animations": { @@ -952,9 +956,9 @@ } }, "node_modules/@angular/router": { - "version": "21.2.6", - "resolved": "https://registry.npmjs.org/@angular/router/-/router-21.2.6.tgz", - "integrity": "sha512-0ajhkKYeOqHQEEH88+Q0HrheR3helwTvdTqD/0gTaapCe+HOoC+SYwmzzsYP2zwAxBNQEg4JHOGKQ30X9/gwgw==", + "version": "21.2.7", + "resolved": "https://registry.npmjs.org/@angular/router/-/router-21.2.7.tgz", + "integrity": "sha512-Ina6XgtpvXT1OsLAomURHJGQDOkIVGrguWAOZ7+gOjsJEjUfpxTktFter+/K59KMC2yv6yneLvYSn3AswTYx7A==", "license": "MIT", "dependencies": { "tslib": "^2.3.0" @@ -963,9 +967,9 @@ "node": "^20.19.0 || ^22.12.0 || >=24.0.0" }, "peerDependencies": { - "@angular/common": "21.2.6", - "@angular/core": "21.2.6", - "@angular/platform-browser": "21.2.6", + "@angular/common": "21.2.7", + "@angular/core": "21.2.7", + "@angular/platform-browser": "21.2.7", "rxjs": "^6.5.3 || ^7.4.0" } }, @@ -2642,9 +2646,9 @@ ] }, "node_modules/@mermaid-js/parser": { - "version": "1.0.1", - "resolved": "https://registry.npmjs.org/@mermaid-js/parser/-/parser-1.0.1.tgz", - "integrity": "sha512-opmV19kN1JsK0T6HhhokHpcVkqKpF+x2pPDKKM2ThHtZAB5F4PROopk0amuVYK5qMrIA4erzpNm8gmPNJgMDxQ==", + "version": "1.1.0", + "resolved": "https://registry.npmjs.org/@mermaid-js/parser/-/parser-1.1.0.tgz", + "integrity": "sha512-gxK9ZX2+Fex5zu8LhRQoMeMPEHbc73UKZ0FQ54YrQtUxE1VVhMwzeNtKRPAu5aXks4FasbMe4xB4bWrmq6Jlxw==", "license": "MIT", "dependencies": { "langium": "^4.0.0" @@ -3105,20 +3109,22 @@ } }, "node_modules/@napi-rs/wasm-runtime": { - "version": "1.1.1", - "resolved": "https://registry.npmjs.org/@napi-rs/wasm-runtime/-/wasm-runtime-1.1.1.tgz", - "integrity": "sha512-p64ah1M1ld8xjWv3qbvFwHiFVWrq1yFvV4f7w+mzaqiR4IlSgkqhcRdHwsGgomwzBH51sRY4NEowLxnaBjcW/A==", + "version": "1.1.2", + "resolved": "https://registry.npmjs.org/@napi-rs/wasm-runtime/-/wasm-runtime-1.1.2.tgz", + "integrity": "sha512-sNXv5oLJ7ob93xkZ1XnxisYhGYXfaG9f65/ZgYuAu3qt7b3NadcOEhLvx28hv31PgX8SZJRYrAIPQilQmFpLVw==", "dev": true, "license": "MIT", "optional": true, "dependencies": { - "@emnapi/core": "^1.7.1", - "@emnapi/runtime": "^1.7.1", "@tybys/wasm-util": "^0.10.1" }, "funding": { "type": "github", "url": "https://github.com/sponsors/Brooooooklyn" + }, + "peerDependencies": { + "@emnapi/core": "^1.7.1", + "@emnapi/runtime": "^1.7.1" } }, "node_modules/@ng-icons/core": { @@ -3355,9 +3361,9 @@ } }, "node_modules/@oxc-parser/binding-android-arm-eabi": { - "version": "0.121.0", - "resolved": "https://registry.npmjs.org/@oxc-parser/binding-android-arm-eabi/-/binding-android-arm-eabi-0.121.0.tgz", - "integrity": "sha512-n07FQcySwOlzap424/PLMtOkbS7xOu8nsJduKL8P3COGHKgKoDYXwoAHCbChfgFpHnviehrLWIPX0lKGtbEk/A==", + "version": "0.123.0", + "resolved": "https://registry.npmjs.org/@oxc-parser/binding-android-arm-eabi/-/binding-android-arm-eabi-0.123.0.tgz", + "integrity": "sha512-EHQ58z+6DbZWokMOKg5AB1KuwrXVgfbBLuuLFfzdc7bI5A4igvdvjKMhUv1VBV+0FABiUCOjNKUmMF7ugprwbQ==", "cpu": [ "arm" ], @@ -3372,9 +3378,9 @@ } }, "node_modules/@oxc-parser/binding-android-arm64": { - "version": "0.121.0", - "resolved": "https://registry.npmjs.org/@oxc-parser/binding-android-arm64/-/binding-android-arm64-0.121.0.tgz", - "integrity": "sha512-/Dd1xIXboYAicw+twT2utxPD7bL8qh7d3ej0qvaYIMj3/EgIrGR+tSnjCUkiCT6g6uTC0neSS4JY8LxhdSU/sA==", + "version": "0.123.0", + "resolved": "https://registry.npmjs.org/@oxc-parser/binding-android-arm64/-/binding-android-arm64-0.123.0.tgz", + "integrity": "sha512-BK1E0zqNoHf38nTHjnGZ+olKHSKNHh65pChjY06yhaWYP8X7yNDqhQDA4neMPRqnPBgpN4/OW1oSMrdJgDi2aw==", "cpu": [ "arm64" ], @@ -3389,9 +3395,9 @@ } }, "node_modules/@oxc-parser/binding-darwin-arm64": { - "version": "0.121.0", - "resolved": "https://registry.npmjs.org/@oxc-parser/binding-darwin-arm64/-/binding-darwin-arm64-0.121.0.tgz", - "integrity": "sha512-A0jNEvv7QMtCO1yk205t3DWU9sWUjQ2KNF0hSVO5W9R9r/R1BIvzG01UQAfmtC0dQm7sCrs5puixurKSfr2bRQ==", + "version": "0.123.0", + "resolved": "https://registry.npmjs.org/@oxc-parser/binding-darwin-arm64/-/binding-darwin-arm64-0.123.0.tgz", + "integrity": "sha512-dkMPbtTbqU+cm+k4YGOBs4zAuq3Xu+wqjbGQvLAuVO7qHhNY4p5LBNudOmOoi0jxS8h1W6Jmlzv8MAKGpK+iDg==", "cpu": [ "arm64" ], @@ -3406,9 +3412,9 @@ } }, "node_modules/@oxc-parser/binding-darwin-x64": { - "version": "0.121.0", - "resolved": "https://registry.npmjs.org/@oxc-parser/binding-darwin-x64/-/binding-darwin-x64-0.121.0.tgz", - "integrity": "sha512-SsHzipdxTKUs3I9EOAPmnIimEeJOemqRlRDOp9LIj+96wtxZejF51gNibmoGq8KoqbT1ssAI5po/E3J+vEtXGA==", + "version": "0.123.0", + "resolved": "https://registry.npmjs.org/@oxc-parser/binding-darwin-x64/-/binding-darwin-x64-0.123.0.tgz", + "integrity": "sha512-85pic0rCd59DGdM69jI9xE/Snb2KtrfiU48QigjJXjzxUOenGvH4SAFIjFpO/2ZnI3Kz50D8pht4jKN3t2022Q==", "cpu": [ "x64" ], @@ -3423,9 +3429,9 @@ } }, "node_modules/@oxc-parser/binding-freebsd-x64": { - "version": "0.121.0", - "resolved": "https://registry.npmjs.org/@oxc-parser/binding-freebsd-x64/-/binding-freebsd-x64-0.121.0.tgz", - "integrity": "sha512-v1APOTkCp+RWOIDAHRoaeW/UoaHF15a60E8eUL6kUQXh+i4K7PBwq2Wi7jm8p0ymID5/m/oC1w3W31Z/+r7HQw==", + "version": "0.123.0", + "resolved": "https://registry.npmjs.org/@oxc-parser/binding-freebsd-x64/-/binding-freebsd-x64-0.123.0.tgz", + "integrity": "sha512-mjEiW6z7JtaiHMK/8aJic1lfjkKpzFwK2XFNmm187BFbtDamjGVuKNr2TEyrFEYJyZc217wokR1wrYeZGBQo4Q==", "cpu": [ "x64" ], @@ -3440,9 +3446,9 @@ } }, "node_modules/@oxc-parser/binding-linux-arm-gnueabihf": { - "version": "0.121.0", - "resolved": "https://registry.npmjs.org/@oxc-parser/binding-linux-arm-gnueabihf/-/binding-linux-arm-gnueabihf-0.121.0.tgz", - "integrity": "sha512-PmqPQuqHZyFVWA4ycr0eu4VnTMmq9laOHZd+8R359w6kzuNZPvmmunmNJ8ybkm769A0nCoVp3TJ6dUz7B3FYIQ==", + "version": "0.123.0", + "resolved": "https://registry.npmjs.org/@oxc-parser/binding-linux-arm-gnueabihf/-/binding-linux-arm-gnueabihf-0.123.0.tgz", + "integrity": "sha512-mYxigPtGt6SZfhNZBIJfuDM92cLo8XUW08WuKxzHvcmWu6xndLqwLp99Vg4uHke1AXicQEHU3Wri2X9bHF0Vlw==", "cpu": [ "arm" ], @@ -3457,9 +3463,9 @@ } }, "node_modules/@oxc-parser/binding-linux-arm-musleabihf": { - "version": "0.121.0", - "resolved": "https://registry.npmjs.org/@oxc-parser/binding-linux-arm-musleabihf/-/binding-linux-arm-musleabihf-0.121.0.tgz", - "integrity": "sha512-vF24htj+MOH+Q7y9A8NuC6pUZu8t/C2Fr/kDOi2OcNf28oogr2xadBPXAbml802E8wRAVfbta6YLDQTearz+jw==", + "version": "0.123.0", + "resolved": "https://registry.npmjs.org/@oxc-parser/binding-linux-arm-musleabihf/-/binding-linux-arm-musleabihf-0.123.0.tgz", + "integrity": "sha512-ttWirDC9eUBn0R4Tzz3aeDaLrx9drPdNiLJ8MXeDBFxd6cwLfTIC27qjsdfGpn942tkVIZY3sjWAnvbwDDjX7g==", "cpu": [ "arm" ], @@ -3474,9 +3480,9 @@ } }, "node_modules/@oxc-parser/binding-linux-arm64-gnu": { - "version": "0.121.0", - "resolved": "https://registry.npmjs.org/@oxc-parser/binding-linux-arm64-gnu/-/binding-linux-arm64-gnu-0.121.0.tgz", - "integrity": "sha512-wjH8cIG2Lu/3d64iZpbYr73hREMgKAfu7fqpXjgM2S16y2zhTfDIp8EQjxO8vlDtKP5Rc7waZW72lh8nZtWrpA==", + "version": "0.123.0", + "resolved": "https://registry.npmjs.org/@oxc-parser/binding-linux-arm64-gnu/-/binding-linux-arm64-gnu-0.123.0.tgz", + "integrity": "sha512-apAHyoMNRYT+2G98Y14caZmsr5LD9PsWpGI7nXmSwK26LGiQneCU6HvHQ+d+AX+RJ5TTWZtEb2RD7OLqAC0cYQ==", "cpu": [ "arm64" ], @@ -3491,9 +3497,9 @@ } }, "node_modules/@oxc-parser/binding-linux-arm64-musl": { - "version": "0.121.0", - "resolved": "https://registry.npmjs.org/@oxc-parser/binding-linux-arm64-musl/-/binding-linux-arm64-musl-0.121.0.tgz", - "integrity": "sha512-qT663J/W8yQFw3dtscbEi9LKJevr20V7uWs2MPGTnvNZ3rm8anhhE16gXGpxDOHeg9raySaSHKhd4IGa3YZvuw==", + "version": "0.123.0", + "resolved": "https://registry.npmjs.org/@oxc-parser/binding-linux-arm64-musl/-/binding-linux-arm64-musl-0.123.0.tgz", + "integrity": "sha512-3r99Qa4egjO/iXUBxTlN6Ddt1YkLifG6olzvj8gkoKEK2U/MOW7mQfXRyBmuoMgmZ7O4vk41gO3d21c6VcN3yQ==", "cpu": [ "arm64" ], @@ -3508,9 +3514,9 @@ } }, "node_modules/@oxc-parser/binding-linux-ppc64-gnu": { - "version": "0.121.0", - "resolved": "https://registry.npmjs.org/@oxc-parser/binding-linux-ppc64-gnu/-/binding-linux-ppc64-gnu-0.121.0.tgz", - "integrity": "sha512-mYNe4NhVvDBbPkAP8JaVS8lC1dsoJZWH5WCjpw5E+sjhk1R08wt3NnXYUzum7tIiWPfgQxbCMcoxgeemFASbRw==", + "version": "0.123.0", + "resolved": "https://registry.npmjs.org/@oxc-parser/binding-linux-ppc64-gnu/-/binding-linux-ppc64-gnu-0.123.0.tgz", + "integrity": "sha512-Hr/Z24kUE4pjJs346g80WDwjyJGrxiw6hExJuOiME/76ZFz68y5L11UzprRkW9FN4HxBB7tLZ/fytczV2fEsiA==", "cpu": [ "ppc64" ], @@ -3525,9 +3531,9 @@ } }, "node_modules/@oxc-parser/binding-linux-riscv64-gnu": { - "version": "0.121.0", - "resolved": "https://registry.npmjs.org/@oxc-parser/binding-linux-riscv64-gnu/-/binding-linux-riscv64-gnu-0.121.0.tgz", - "integrity": "sha512-+QiFoGxhAbaI/amqX567784cDyyuZIpinBrJNxUzb+/L2aBRX67mN6Jv40pqduHf15yYByI+K5gUEygCuv0z9w==", + "version": "0.123.0", + "resolved": "https://registry.npmjs.org/@oxc-parser/binding-linux-riscv64-gnu/-/binding-linux-riscv64-gnu-0.123.0.tgz", + "integrity": "sha512-sxjbhs+8WXeuoLnZ2rBmQ96gPdq3SCmz24reIltsKLUt1EDMgdaQsr7RqwBphw3QAImkMtlPQfAWDWwZyo0xDg==", "cpu": [ "riscv64" ], @@ -3542,9 +3548,9 @@ } }, "node_modules/@oxc-parser/binding-linux-riscv64-musl": { - "version": "0.121.0", - "resolved": "https://registry.npmjs.org/@oxc-parser/binding-linux-riscv64-musl/-/binding-linux-riscv64-musl-0.121.0.tgz", - "integrity": "sha512-9ykEgyTa5JD/Uhv2sttbKnCfl2PieUfOjyxJC/oDL2UO0qtXOtjPLl7H8Kaj5G7p3hIvFgu3YWvAxvE0sqY+hQ==", + "version": "0.123.0", + "resolved": "https://registry.npmjs.org/@oxc-parser/binding-linux-riscv64-musl/-/binding-linux-riscv64-musl-0.123.0.tgz", + "integrity": "sha512-d6xHHhqldA/W+VC7v8uHs24zM69Ad3HnHQ45h+uuBhCsbZx3d0E0wL2K3uJ5mYKTR6UPMFk9VMXcHWwvg1PRZQ==", "cpu": [ "riscv64" ], @@ -3559,9 +3565,9 @@ } }, "node_modules/@oxc-parser/binding-linux-s390x-gnu": { - "version": "0.121.0", - "resolved": "https://registry.npmjs.org/@oxc-parser/binding-linux-s390x-gnu/-/binding-linux-s390x-gnu-0.121.0.tgz", - "integrity": "sha512-DB1EW5VHZdc1lIRjOI3bW/wV6R6y0xlfvdVrqj6kKi7Ayu2U3UqUBdq9KviVkcUGd5Oq+dROqvUEEFRXGAM7EQ==", + "version": "0.123.0", + "resolved": "https://registry.npmjs.org/@oxc-parser/binding-linux-s390x-gnu/-/binding-linux-s390x-gnu-0.123.0.tgz", + "integrity": "sha512-+di9A5wJQlv0VodyhADjJ2rC4geyHY+uhJDl3TFjMgYhhlgLZchi9uHD5mfiUEDWHt1x7/eU2u1ge3LLazZmFw==", "cpu": [ "s390x" ], @@ -3576,9 +3582,9 @@ } }, "node_modules/@oxc-parser/binding-linux-x64-gnu": { - "version": "0.121.0", - "resolved": "https://registry.npmjs.org/@oxc-parser/binding-linux-x64-gnu/-/binding-linux-x64-gnu-0.121.0.tgz", - "integrity": "sha512-s4lfobX9p4kPTclvMiH3gcQUd88VlnkMTF6n2MTMDAyX5FPNRhhRSFZK05Ykhf8Zy5NibV4PbGR6DnK7FGNN6A==", + "version": "0.123.0", + "resolved": "https://registry.npmjs.org/@oxc-parser/binding-linux-x64-gnu/-/binding-linux-x64-gnu-0.123.0.tgz", + "integrity": "sha512-sh7pw2g/u6LE1TaRRQsV9Kv9+1y+CywaaNwWWP+3bnEPk/L692oTG0hmEviUlawI8v3OGC+AhbjtAD+HXWQAkg==", "cpu": [ "x64" ], @@ -3593,9 +3599,9 @@ } }, "node_modules/@oxc-parser/binding-linux-x64-musl": { - "version": "0.121.0", - "resolved": "https://registry.npmjs.org/@oxc-parser/binding-linux-x64-musl/-/binding-linux-x64-musl-0.121.0.tgz", - "integrity": "sha512-P9KlyTpuBuMi3NRGpJO8MicuGZfOoqZVRP1WjOecwx8yk4L/+mrCRNc5egSi0byhuReblBF2oVoDSMgV9Bj4Hw==", + "version": "0.123.0", + "resolved": "https://registry.npmjs.org/@oxc-parser/binding-linux-x64-musl/-/binding-linux-x64-musl-0.123.0.tgz", + "integrity": "sha512-S+LoD8PiJ639JwIqK1knIeqAyYkeCbLHtAgfapszKX0yVCaYP+aer8dJxL25de9qcDjvYWVrYCkuDZzHmOl2Xw==", "cpu": [ "x64" ], @@ -3610,9 +3616,9 @@ } }, "node_modules/@oxc-parser/binding-openharmony-arm64": { - "version": "0.121.0", - "resolved": "https://registry.npmjs.org/@oxc-parser/binding-openharmony-arm64/-/binding-openharmony-arm64-0.121.0.tgz", - "integrity": "sha512-R+4jrWOfF2OAPPhj3Eb3U5CaKNAH9/btMveMULIrcNW/hjfysFQlF8wE0GaVBr81dWz8JLgQlsxwctoL78JwXw==", + "version": "0.123.0", + "resolved": "https://registry.npmjs.org/@oxc-parser/binding-openharmony-arm64/-/binding-openharmony-arm64-0.123.0.tgz", + "integrity": "sha512-/65vryK11q1I+k+7ukDlwZOxUFCLYsoZBZPGZHyet5bIP5e3D8mV3uCuvpWZ9Hoe6vUZFw/nAfCrX59MeuJPgw==", "cpu": [ "arm64" ], @@ -3627,9 +3633,9 @@ } }, "node_modules/@oxc-parser/binding-wasm32-wasi": { - "version": "0.121.0", - "resolved": "https://registry.npmjs.org/@oxc-parser/binding-wasm32-wasi/-/binding-wasm32-wasi-0.121.0.tgz", - "integrity": "sha512-5TFISkPTymKvsmIlKasPVTPuWxzCcrT8pM+p77+mtQbIZDd1UC8zww4CJcRI46kolmgrEX6QpKO8AvWMVZ+ifw==", + "version": "0.123.0", + "resolved": "https://registry.npmjs.org/@oxc-parser/binding-wasm32-wasi/-/binding-wasm32-wasi-0.123.0.tgz", + "integrity": "sha512-y4OsMGQiAbZzj2Rq0LEfvhR48rQDvbvqsl/dPdn4tdf+z3H79nZuR+lQ/+KUGjD30vpVGem138sBWHFj9UR+Vg==", "cpu": [ "wasm32" ], @@ -3637,16 +3643,16 @@ "license": "MIT", "optional": true, "dependencies": { - "@napi-rs/wasm-runtime": "^1.1.1" + "@napi-rs/wasm-runtime": "^1.1.2" }, "engines": { "node": ">=14.0.0" } }, "node_modules/@oxc-parser/binding-win32-arm64-msvc": { - "version": "0.121.0", - "resolved": "https://registry.npmjs.org/@oxc-parser/binding-win32-arm64-msvc/-/binding-win32-arm64-msvc-0.121.0.tgz", - "integrity": "sha512-V0pxh4mql4XTt3aiEtRNUeBAUFOw5jzZNxPABLaOKAWrVzSr9+XUaB095lY7jqMf5t8vkfh8NManGB28zanYKw==", + "version": "0.123.0", + "resolved": "https://registry.npmjs.org/@oxc-parser/binding-win32-arm64-msvc/-/binding-win32-arm64-msvc-0.123.0.tgz", + "integrity": "sha512-9lBqI6AXAkjYavkdpizNU3Q51uoVYfp9FJPx19hnCEdPku1jSgzSnvgmCvhCue0GziIvIvIdWgZ41wXQ3EOoBw==", "cpu": [ "arm64" ], @@ -3661,9 +3667,9 @@ } }, "node_modules/@oxc-parser/binding-win32-ia32-msvc": { - "version": "0.121.0", - "resolved": "https://registry.npmjs.org/@oxc-parser/binding-win32-ia32-msvc/-/binding-win32-ia32-msvc-0.121.0.tgz", - "integrity": "sha512-4Ob1qvYMPnlF2N9rdmKdkQFdrq16QVcQwBsO8yiPZXof0fHKFF+LmQV501XFbi7lHyrKm8rlJRfQ/M8bZZPVLw==", + "version": "0.123.0", + "resolved": "https://registry.npmjs.org/@oxc-parser/binding-win32-ia32-msvc/-/binding-win32-ia32-msvc-0.123.0.tgz", + "integrity": "sha512-zJbqBHwSUB7CyvAONy9ewGtQwcQj+ylOhYGETvUPp3KIYx7lolj4Gayof7iA22SU5eMSjO5COL0c8wYhmn9agA==", "cpu": [ "ia32" ], @@ -3678,9 +3684,9 @@ } }, "node_modules/@oxc-parser/binding-win32-x64-msvc": { - "version": "0.121.0", - "resolved": "https://registry.npmjs.org/@oxc-parser/binding-win32-x64-msvc/-/binding-win32-x64-msvc-0.121.0.tgz", - "integrity": "sha512-BOp1KCzdboB1tPqoCPXgntgFs0jjeSyOXHzgxVFR7B/qfr3F8r4YDacHkTOUNXtDgM8YwKnkf3rE5gwALYX7NA==", + "version": "0.123.0", + "resolved": "https://registry.npmjs.org/@oxc-parser/binding-win32-x64-msvc/-/binding-win32-x64-msvc-0.123.0.tgz", + "integrity": "sha512-q7RZvglQvGo3RX5ljtcGSabu2B2c0oDU/6xC3sBMhsV5KRo0PvyxLdordbEN31NTfuZu4Sgl86C76cAURZIHWA==", "cpu": [ "x64" ], @@ -3988,9 +3994,9 @@ ] }, "node_modules/@oxc-transform/binding-android-arm-eabi": { - "version": "0.121.0", - "resolved": "https://registry.npmjs.org/@oxc-transform/binding-android-arm-eabi/-/binding-android-arm-eabi-0.121.0.tgz", - "integrity": "sha512-NNYkyDjTID7oVW0LUZ04kDShtyY6hgsTakd2u3mz/hN765JviCuyBIi5qT9dDOmgX0t1y74nuS7FwiLgaCcZ4g==", + "version": "0.123.0", + "resolved": "https://registry.npmjs.org/@oxc-transform/binding-android-arm-eabi/-/binding-android-arm-eabi-0.123.0.tgz", + "integrity": "sha512-glB9LSiKsRmhb8yuBcbaCByx+JQ/KbAZe9U5+iUuLuLaRr7llg/saPybaDiiEaz3IcVxnodKgsA4IxUnPV3+fw==", "cpu": [ "arm" ], @@ -4005,9 +4011,9 @@ } }, "node_modules/@oxc-transform/binding-android-arm64": { - "version": "0.121.0", - "resolved": "https://registry.npmjs.org/@oxc-transform/binding-android-arm64/-/binding-android-arm64-0.121.0.tgz", - "integrity": "sha512-zO5az3E5JUmF/k7xOOL9TCipqaVn/d8QHK5T8/bcw6qTWAPVFJjQRK8+5MSmp2ItO2Dmxed5DdWMSxG2NNfA5w==", + "version": "0.123.0", + "resolved": "https://registry.npmjs.org/@oxc-transform/binding-android-arm64/-/binding-android-arm64-0.123.0.tgz", + "integrity": "sha512-qge60UoJalkq8ftU9vHyq5Xu+kDtPF8sSSqQavzNWURGFLtXKyuxSl+7ovTurvUAwgVkaHcvEZsXWip71tKlqg==", "cpu": [ "arm64" ], @@ -4022,9 +4028,9 @@ } }, "node_modules/@oxc-transform/binding-darwin-arm64": { - "version": "0.121.0", - "resolved": "https://registry.npmjs.org/@oxc-transform/binding-darwin-arm64/-/binding-darwin-arm64-0.121.0.tgz", - "integrity": "sha512-3vcZdmL8OAdYzXfPDeXrO9KagTgUbXPSFXotoww9N0jVNbdCvSpKJHia1aqdltyevrCWF4KqJyOeeUfGcw7AJw==", + "version": "0.123.0", + "resolved": "https://registry.npmjs.org/@oxc-transform/binding-darwin-arm64/-/binding-darwin-arm64-0.123.0.tgz", + "integrity": "sha512-uJv6bgXTwVlJvmYmGjv/IeAPUn5MTUeU8Uf+nLEUpPW0QDP0g7ttZWEI+OjY9seHO0DQ5dNi0+wzcTCk+UmoJA==", "cpu": [ "arm64" ], @@ -4039,9 +4045,9 @@ } }, "node_modules/@oxc-transform/binding-darwin-x64": { - "version": "0.121.0", - "resolved": "https://registry.npmjs.org/@oxc-transform/binding-darwin-x64/-/binding-darwin-x64-0.121.0.tgz", - "integrity": "sha512-R63ZXF4Fuer3FEZYX9UmzIKAENSEYQZTglTkzWoyNPyuHDhSfyJIK+X+wgy2Wc1lTad1XquCUq5SDuRSd37fcQ==", + "version": "0.123.0", + "resolved": "https://registry.npmjs.org/@oxc-transform/binding-darwin-x64/-/binding-darwin-x64-0.123.0.tgz", + "integrity": "sha512-Bkm2zhQ10D9xI/ZyMErQi3GOWouYMR8SqI+yvBggLz/EE1moo0Hpm0qQTJYwpFsi+uO64tAu1asaNKxCmVpaFw==", "cpu": [ "x64" ], @@ -4056,9 +4062,9 @@ } }, "node_modules/@oxc-transform/binding-freebsd-x64": { - "version": "0.121.0", - "resolved": "https://registry.npmjs.org/@oxc-transform/binding-freebsd-x64/-/binding-freebsd-x64-0.121.0.tgz", - "integrity": "sha512-0krk8L6iOJ6fobs3f9XHo4RSgEas0yLq9/xGZMuwxFs+rI/rnpYPX+1LLSmreHqeZM77a7r+UF12WjwI1odVUA==", + "version": "0.123.0", + "resolved": "https://registry.npmjs.org/@oxc-transform/binding-freebsd-x64/-/binding-freebsd-x64-0.123.0.tgz", + "integrity": "sha512-pEbYQN2OPHL6khErdZ6Q0XI+VriAz1TZglm9euj4qX2a30PobOyzebaHEZMpmiPTS82rB6kPcSjsBbjY4bXVaA==", "cpu": [ "x64" ], @@ -4073,9 +4079,9 @@ } }, "node_modules/@oxc-transform/binding-linux-arm-gnueabihf": { - "version": "0.121.0", - "resolved": "https://registry.npmjs.org/@oxc-transform/binding-linux-arm-gnueabihf/-/binding-linux-arm-gnueabihf-0.121.0.tgz", - "integrity": "sha512-cNkTaw77UaNiGOCIv2R1kHZ3OkTVlr/059agLCUaeQmZGl76Ad7DrDcDyhC0Iugw0jEdWZ9zeUS5VLmzblnTXQ==", + "version": "0.123.0", + "resolved": "https://registry.npmjs.org/@oxc-transform/binding-linux-arm-gnueabihf/-/binding-linux-arm-gnueabihf-0.123.0.tgz", + "integrity": "sha512-oEZS8HsrtHON4ph/a35ILBH4Nra5Y0uP3CsGOc7SUSftEt8GZ+Xr3lXj67ZXsEZiZbsw3cUte23YhUf09nfaFQ==", "cpu": [ "arm" ], @@ -4090,9 +4096,9 @@ } }, "node_modules/@oxc-transform/binding-linux-arm-musleabihf": { - "version": "0.121.0", - "resolved": "https://registry.npmjs.org/@oxc-transform/binding-linux-arm-musleabihf/-/binding-linux-arm-musleabihf-0.121.0.tgz", - "integrity": "sha512-eDwTIN0UUCQePgFR41doxorzsxoMoUTbXo6bEbvdFH7P4ZoaUXgHYN10Qjd9K6k0x/bBnU6oC4YPSWYKvQDr9Q==", + "version": "0.123.0", + "resolved": "https://registry.npmjs.org/@oxc-transform/binding-linux-arm-musleabihf/-/binding-linux-arm-musleabihf-0.123.0.tgz", + "integrity": "sha512-869HBeT1tXl6GsmxZJTET7Lbx6hW8XoM8pw6PyTQ82GjodFSlk6if4rWifYNrPOsgMw1/q4mwYJcX850eFPJow==", "cpu": [ "arm" ], @@ -4107,9 +4113,9 @@ } }, "node_modules/@oxc-transform/binding-linux-arm64-gnu": { - "version": "0.121.0", - "resolved": "https://registry.npmjs.org/@oxc-transform/binding-linux-arm64-gnu/-/binding-linux-arm64-gnu-0.121.0.tgz", - "integrity": "sha512-UthSp+L23xeV0lIVloiRDU1d3aOvq0KRif3s6vszeSGnWf69+EVcZcondqLuX9optUhKV0/L8xwe2wLr9WkaDA==", + "version": "0.123.0", + "resolved": "https://registry.npmjs.org/@oxc-transform/binding-linux-arm64-gnu/-/binding-linux-arm64-gnu-0.123.0.tgz", + "integrity": "sha512-4OUNnatZNNvMwnylsfr+IeaCByBKiXPk4wQFMUf0xS8cUnOdjOtb6qMQ94nWuPA9d+Ywu32qfY+N4Fdaf3sNRA==", "cpu": [ "arm64" ], @@ -4124,9 +4130,9 @@ } }, "node_modules/@oxc-transform/binding-linux-arm64-musl": { - "version": "0.121.0", - "resolved": "https://registry.npmjs.org/@oxc-transform/binding-linux-arm64-musl/-/binding-linux-arm64-musl-0.121.0.tgz", - "integrity": "sha512-J5vKUF8Jml1m9Fl48fKp2/wPl8LhGdjJWZ3PrrT+S16SbW7yEKixq5upzO2arhrky5elRYMXWwfi60ex1tBi6g==", + "version": "0.123.0", + "resolved": "https://registry.npmjs.org/@oxc-transform/binding-linux-arm64-musl/-/binding-linux-arm64-musl-0.123.0.tgz", + "integrity": "sha512-C54h8AoUpwzw3+Ge+Vv2YYuuVh7XwVB5Mi/KiwByPPS/WFoJpmkSPvtFeAazdYbo4iKEGLrRI8vt+gEib1lDMw==", "cpu": [ "arm64" ], @@ -4141,9 +4147,9 @@ } }, "node_modules/@oxc-transform/binding-linux-ppc64-gnu": { - "version": "0.121.0", - "resolved": "https://registry.npmjs.org/@oxc-transform/binding-linux-ppc64-gnu/-/binding-linux-ppc64-gnu-0.121.0.tgz", - "integrity": "sha512-ya+/TL/YH/VcfWeRs95pMIgEj1eQgKg3kR/9AkQgSi8i9jIDEXrgrcQ8cwRYSZ3THlT6cxe3KGJa6vwcHG6JEg==", + "version": "0.123.0", + "resolved": "https://registry.npmjs.org/@oxc-transform/binding-linux-ppc64-gnu/-/binding-linux-ppc64-gnu-0.123.0.tgz", + "integrity": "sha512-X+obOgFjX/61UZ1Wm5ncNZYC43R3bV9eU7DdCAEO6VXubSXcwIjxaf3QrUvBDYPifrdWSy/OerzJbhI9TgHYPg==", "cpu": [ "ppc64" ], @@ -4158,9 +4164,9 @@ } }, "node_modules/@oxc-transform/binding-linux-riscv64-gnu": { - "version": "0.121.0", - "resolved": "https://registry.npmjs.org/@oxc-transform/binding-linux-riscv64-gnu/-/binding-linux-riscv64-gnu-0.121.0.tgz", - "integrity": "sha512-XhUBS/6bxL3maLMvkyY5jM23jFCORl+noYc7KkMydpb0Ot08XSu+8c2o7QpGVHWf85eTH/1Tx0aOTrcWek7EAw==", + "version": "0.123.0", + "resolved": "https://registry.npmjs.org/@oxc-transform/binding-linux-riscv64-gnu/-/binding-linux-riscv64-gnu-0.123.0.tgz", + "integrity": "sha512-EzerdFa2KvEzYHuzFp9W/KZaulI4OIKE8FIC0X21V757ljZKRfskIqtGAFX/CAvoIF3C2zNepDWFZlpcJ5nJ1g==", "cpu": [ "riscv64" ], @@ -4175,9 +4181,9 @@ } }, "node_modules/@oxc-transform/binding-linux-riscv64-musl": { - "version": "0.121.0", - "resolved": "https://registry.npmjs.org/@oxc-transform/binding-linux-riscv64-musl/-/binding-linux-riscv64-musl-0.121.0.tgz", - "integrity": "sha512-kAcZZrU2Wxopcpt38D1u5OeLUwV78EXyOu3VfFNkP/vrMiKB4Tbca8ZxBq+XTkpijuKE4DdCQaLZylsFj7L00w==", + "version": "0.123.0", + "resolved": "https://registry.npmjs.org/@oxc-transform/binding-linux-riscv64-musl/-/binding-linux-riscv64-musl-0.123.0.tgz", + "integrity": "sha512-WFh7tcPYqxo2YQXnIuQ/ZZ4uFHeR06tDEFD8qNl1egRrqTZskHvV/NBelOthfHmkizWiGJx8ZnvN69UrL3q12A==", "cpu": [ "riscv64" ], @@ -4192,9 +4198,9 @@ } }, "node_modules/@oxc-transform/binding-linux-s390x-gnu": { - "version": "0.121.0", - "resolved": "https://registry.npmjs.org/@oxc-transform/binding-linux-s390x-gnu/-/binding-linux-s390x-gnu-0.121.0.tgz", - "integrity": "sha512-jHyHS+NwPAlUEuY6BzFBDoT4LfSBEW/Ne2FeMzdK8LXOvgHFrJiBf6x8FgekatrTGrDpy1hLiACNnPA81Hs2pQ==", + "version": "0.123.0", + "resolved": "https://registry.npmjs.org/@oxc-transform/binding-linux-s390x-gnu/-/binding-linux-s390x-gnu-0.123.0.tgz", + "integrity": "sha512-A5ahPjG/2Zg5/3RndWRSaKO/9uIirjYuv8OBWa+HBA1Im607dCceSfc9k1PCHt0MdjtsfiyArO+kk2TP5R0Ebg==", "cpu": [ "s390x" ], @@ -4209,9 +4215,9 @@ } }, "node_modules/@oxc-transform/binding-linux-x64-gnu": { - "version": "0.121.0", - "resolved": "https://registry.npmjs.org/@oxc-transform/binding-linux-x64-gnu/-/binding-linux-x64-gnu-0.121.0.tgz", - "integrity": "sha512-KedV2jkFxeMvUqfh6SgXjCnO5SBZ+SorTUxSBeql7zp59ONZgAcehWAqDX+YWsK8wEpt23Q8ydC/0d6ebJIAzQ==", + "version": "0.123.0", + "resolved": "https://registry.npmjs.org/@oxc-transform/binding-linux-x64-gnu/-/binding-linux-x64-gnu-0.123.0.tgz", + "integrity": "sha512-9g1rEynmIh0qkJWc/1Zbd1VRFzYkk6KcmwcCoq3hslgGBIJEvrjPlP7cQgAiCaTFCVjfoPYWAy+5xjf9sCNY1g==", "cpu": [ "x64" ], @@ -4226,9 +4232,9 @@ } }, "node_modules/@oxc-transform/binding-linux-x64-musl": { - "version": "0.121.0", - "resolved": "https://registry.npmjs.org/@oxc-transform/binding-linux-x64-musl/-/binding-linux-x64-musl-0.121.0.tgz", - "integrity": "sha512-jFAZwvgjsswiHET2xxxNvxhKCI74yVmewl0F00i3vzt9C088ZVaUvvWlqDS1GRvD4ORBmpJWOYkHdscpIJijEA==", + "version": "0.123.0", + "resolved": "https://registry.npmjs.org/@oxc-transform/binding-linux-x64-musl/-/binding-linux-x64-musl-0.123.0.tgz", + "integrity": "sha512-/eoNDuGDfEjNVqmgDNkFlGmoo5MOnRxaO9IhwKyWoXXUn7tzA5C45op7Kv/Njb6BcGr4RN2KH7OjsEAqjMDmuA==", "cpu": [ "x64" ], @@ -4243,9 +4249,9 @@ } }, "node_modules/@oxc-transform/binding-openharmony-arm64": { - "version": "0.121.0", - "resolved": "https://registry.npmjs.org/@oxc-transform/binding-openharmony-arm64/-/binding-openharmony-arm64-0.121.0.tgz", - "integrity": "sha512-xn9nxaq31f19PUyGh1xKMOSs8MVPImeaESWNOHtAIznckE+qa5/oHtYALzF3z8uvy1EC/eZODWcHrsYOVNaWug==", + "version": "0.123.0", + "resolved": "https://registry.npmjs.org/@oxc-transform/binding-openharmony-arm64/-/binding-openharmony-arm64-0.123.0.tgz", + "integrity": "sha512-rGeHHsE/KZ7G/iEtSsQAk4HZ3Wl2v4oMgcOjSvlVJejl+5ttUcKAjxgW2j+c1zFREJVpCHEyspi3fFxJkdJ/Ww==", "cpu": [ "arm64" ], @@ -4260,9 +4266,9 @@ } }, "node_modules/@oxc-transform/binding-wasm32-wasi": { - "version": "0.121.0", - "resolved": "https://registry.npmjs.org/@oxc-transform/binding-wasm32-wasi/-/binding-wasm32-wasi-0.121.0.tgz", - "integrity": "sha512-7lj6FBMX8zLfTqIY4YHHTE/b6oyCzZaUwqi2n9KX4FkgjtBpfmq5KSUgi/I+YiE7JJHu1g8Bd3uWJq1lbehL8Q==", + "version": "0.123.0", + "resolved": "https://registry.npmjs.org/@oxc-transform/binding-wasm32-wasi/-/binding-wasm32-wasi-0.123.0.tgz", + "integrity": "sha512-JMFXeeWvFDioW2gP9dgD6LDbPmCMCrXNwDWMAXcKDmZILx0rARt+z79GACKTBSyyKURkYGe3+wJj+oI3JKnvug==", "cpu": [ "wasm32" ], @@ -4270,16 +4276,16 @@ "license": "MIT", "optional": true, "dependencies": { - "@napi-rs/wasm-runtime": "^1.1.1" + "@napi-rs/wasm-runtime": "^1.1.2" }, "engines": { "node": ">=14.0.0" } }, "node_modules/@oxc-transform/binding-win32-arm64-msvc": { - "version": "0.121.0", - "resolved": "https://registry.npmjs.org/@oxc-transform/binding-win32-arm64-msvc/-/binding-win32-arm64-msvc-0.121.0.tgz", - "integrity": "sha512-+ve3UajNq2ldcCEEmpMVn7Ic3v/qCykPTSx3lZfe0iCW6tisIWvkYiXpf6B5dvwSY7SDyrdt9EyPMS75b41iPA==", + "version": "0.123.0", + "resolved": "https://registry.npmjs.org/@oxc-transform/binding-win32-arm64-msvc/-/binding-win32-arm64-msvc-0.123.0.tgz", + "integrity": "sha512-hSQ7VokhPAO0NMrsRz+2Zh4fcxx28qFlX78/7jG/+tWZgiB/aEukadf3XPcYQ3ymqoL8SvDN3nQ7bNTHAiZSCg==", "cpu": [ "arm64" ], @@ -4294,9 +4300,9 @@ } }, "node_modules/@oxc-transform/binding-win32-ia32-msvc": { - "version": "0.121.0", - "resolved": "https://registry.npmjs.org/@oxc-transform/binding-win32-ia32-msvc/-/binding-win32-ia32-msvc-0.121.0.tgz", - "integrity": "sha512-9ZUHa4bXWlPRLzbjYsU3VBSvqwSVHAknQlN+nUO1DVu6j958Ui9ux0I9pZHwxb07I26VMdDhd7AjJyz1ZtZlkg==", + "version": "0.123.0", + "resolved": "https://registry.npmjs.org/@oxc-transform/binding-win32-ia32-msvc/-/binding-win32-ia32-msvc-0.123.0.tgz", + "integrity": "sha512-7bIydPGt68qdfPXYLzBHYUia8Wi0dP6g/8zmrXN1HfUugkdt4Kh121fmw4KH+kcIT1BTICDHcXU4bJ6k3QmSgg==", "cpu": [ "ia32" ], @@ -4311,9 +4317,9 @@ } }, "node_modules/@oxc-transform/binding-win32-x64-msvc": { - "version": "0.121.0", - "resolved": "https://registry.npmjs.org/@oxc-transform/binding-win32-x64-msvc/-/binding-win32-x64-msvc-0.121.0.tgz", - "integrity": "sha512-vV/rzJsmJeeXI1q/xuy93PnoL/IYMwCCyYMX9MmIgMx2a4Lu3vIjUNBLJx1R5CqP/NnvAelsuz05sKlO017FmQ==", + "version": "0.123.0", + "resolved": "https://registry.npmjs.org/@oxc-transform/binding-win32-x64-msvc/-/binding-win32-x64-msvc-0.123.0.tgz", + "integrity": "sha512-pVmtG6GGI3eZ5J4NP75rR5yA1EuwEq+94kBQipq1rZXsukj6ghNkd3OGgzOA+W/fQL3V9AlnY9BriqCT21eVQw==", "cpu": [ "x64" ], @@ -4765,9 +4771,9 @@ } }, "node_modules/@rolldown/binding-linux-ppc64-gnu": { - "version": "1.0.0-rc.12", - "resolved": "https://registry.npmjs.org/@rolldown/binding-linux-ppc64-gnu/-/binding-linux-ppc64-gnu-1.0.0-rc.12.tgz", - "integrity": "sha512-AP3E9BpcUYliZCxa3w5Kwj9OtEVDYK6sVoUzy4vTOJsjPOgdaJZKFmN4oOlX0Wp0RPV2ETfmIra9x1xuayFB7g==", + "version": "1.0.0-rc.13", + "resolved": "https://registry.npmjs.org/@rolldown/binding-linux-ppc64-gnu/-/binding-linux-ppc64-gnu-1.0.0-rc.13.tgz", + "integrity": "sha512-8Wtnbw4k7pMYN9B/mOEAsQ8HOiq7AZ31Ig4M9BKn2So4xRaFEhtCSa4ZJaOutOWq50zpgR4N5+L/opnlaCx8wQ==", "cpu": [ "ppc64" ], @@ -4782,9 +4788,9 @@ } }, "node_modules/@rolldown/binding-linux-s390x-gnu": { - "version": "1.0.0-rc.12", - "resolved": "https://registry.npmjs.org/@rolldown/binding-linux-s390x-gnu/-/binding-linux-s390x-gnu-1.0.0-rc.12.tgz", - "integrity": "sha512-nWwpvUSPkoFmZo0kQazZYOrT7J5DGOJ/+QHHzjvNlooDZED8oH82Yg67HvehPPLAg5fUff7TfWFHQS8IV1n3og==", + "version": "1.0.0-rc.13", + "resolved": "https://registry.npmjs.org/@rolldown/binding-linux-s390x-gnu/-/binding-linux-s390x-gnu-1.0.0-rc.13.tgz", + "integrity": "sha512-D/0Nlo8mQuxSMohNJUF2lDXWRsFDsHldfRRgD9bRgktj+EndGPj4DOV37LqDKPYS+osdyhZEH7fTakTAEcW7qg==", "cpu": [ "s390x" ], @@ -5258,13 +5264,13 @@ ] }, "node_modules/@schematics/angular": { - "version": "21.2.5", - "resolved": "https://registry.npmjs.org/@schematics/angular/-/angular-21.2.5.tgz", - "integrity": "sha512-orOiXcG86t34ejqbkm7ZHEkGfwTU/ySYFgY7BOQdaYFCoNQXxtU87fZoHckJ2xYpVitoKTvbf1bxDDphXb3ycw==", + "version": "21.2.6", + "resolved": "https://registry.npmjs.org/@schematics/angular/-/angular-21.2.6.tgz", + "integrity": "sha512-KpLD8R2S762jbLdNEepE+b7KjhVOKPFHHdgNqhPv0NiGLdsvXSOx1e63JvFacoCZdmP7n3/gwmyT/utcVvnsag==", "license": "MIT", "dependencies": { - "@angular-devkit/core": "21.2.5", - "@angular-devkit/schematics": "21.2.5", + "@angular-devkit/core": "21.2.6", + "@angular-devkit/schematics": "21.2.6", "jsonc-parser": "3.3.1" }, "engines": { @@ -6463,9 +6469,9 @@ "license": "ISC" }, "node_modules/brace-expansion": { - "version": "5.0.4", - "resolved": "https://registry.npmjs.org/brace-expansion/-/brace-expansion-5.0.4.tgz", - "integrity": "sha512-h+DEnpVvxmfVefa4jFbCf5HdH5YMDXRsmKflpf1pILZWRFlTbJpxeU55nJl4Smt5HQaGzg1o6RHFPJaOqnmBDg==", + "version": "5.0.5", + "resolved": "https://registry.npmjs.org/brace-expansion/-/brace-expansion-5.0.5.tgz", + "integrity": "sha512-VZznLgtwhn+Mact9tfiwx64fA9erHH/MCXEUfB/0bX/6Fz6ny5EGTXYltMocqg4xFAQZtnO3DHWWXi8RiuN7cQ==", "dev": true, "license": "MIT", "dependencies": { @@ -8839,9 +8845,9 @@ "license": "MIT" }, "node_modules/katex": { - "version": "0.16.44", - "resolved": "https://registry.npmjs.org/katex/-/katex-0.16.44.tgz", - "integrity": "sha512-EkxoDTk8ufHqHlf9QxGwcxeLkWRR3iOuYfRpfORgYfqc8s13bgb+YtRY59NK5ZpRaCwq1kqA6a5lpX8C/eLphQ==", + "version": "0.16.45", + "resolved": "https://registry.npmjs.org/katex/-/katex-0.16.45.tgz", + "integrity": "sha512-pQpZbdBu7wCTmQUh7ufPmLr0pFoObnGUoL/yhtwJDgmmQpbkg/0HSVti25Fu4rmd1oCR6NGWe9vqTWuWv3GcNA==", "funding": [ "https://opencollective.com/katex", "https://github.com/sponsors/katex" @@ -9376,9 +9382,9 @@ } }, "node_modules/marked": { - "version": "17.0.5", - "resolved": "https://registry.npmjs.org/marked/-/marked-17.0.5.tgz", - "integrity": "sha512-6hLvc0/JEbRjRgzI6wnT2P1XuM1/RrrDEX0kPt0N7jGm1133g6X7DlxFasUIx+72aKAr904GTxhSLDrd5DIlZg==", + "version": "17.0.6", + "resolved": "https://registry.npmjs.org/marked/-/marked-17.0.6.tgz", + "integrity": "sha512-gB0gkNafnonOw0obSTEGZTT86IuhILt2Wfx0mWH/1Au83kybTayroZ/V6nS25mN7u8ASy+5fMhgB3XPNrOZdmA==", "license": "MIT", "bin": { "marked": "bin/marked.js" @@ -9428,14 +9434,14 @@ } }, "node_modules/mermaid": { - "version": "11.13.0", - "resolved": "https://registry.npmjs.org/mermaid/-/mermaid-11.13.0.tgz", - "integrity": "sha512-fEnci+Immw6lKMFI8sqzjlATTyjLkRa6axrEgLV2yHTfv8r+h1wjFbV6xeRtd4rUV1cS4EpR9rwp3Rci7TRWDw==", + "version": "11.14.0", + "resolved": "https://registry.npmjs.org/mermaid/-/mermaid-11.14.0.tgz", + "integrity": "sha512-GSGloRsBs+JINmmhl0JDwjpuezCsHB4WGI4NASHxL3fHo3o/BRXTxhDLKnln8/Q0lRFRyDdEjmk1/d5Sn1Xz8g==", "license": "MIT", "dependencies": { "@braintree/sanitize-url": "^7.1.1", "@iconify/utils": "^3.0.2", - "@mermaid-js/parser": "^1.0.1", + "@mermaid-js/parser": "^1.1.0", "@types/d3": "^7.4.3", "@upsetjs/venn.js": "^2.0.0", "cytoscape": "^3.33.1", @@ -10129,13 +10135,13 @@ "optional": true }, "node_modules/oxc-parser": { - "version": "0.121.0", - "resolved": "https://registry.npmjs.org/oxc-parser/-/oxc-parser-0.121.0.tgz", - "integrity": "sha512-ek9o58+SCv6AV7nchiAcUJy1DNE2CC5WRdBcO0mF+W4oRjNQfPO7b3pLjTHSFECpHkKGOZSQxx3hk8viIL5YCg==", + "version": "0.123.0", + "resolved": "https://registry.npmjs.org/oxc-parser/-/oxc-parser-0.123.0.tgz", + "integrity": "sha512-F6ak0tFc01ZGbl5KxvLDQ2K005Z086mp3ByCQBDhUjqXLkapGUkMuJSsYixncdEpkLlcRDcruHR71LD339ADUA==", "dev": true, "license": "MIT", "dependencies": { - "@oxc-project/types": "^0.121.0" + "@oxc-project/types": "^0.123.0" }, "engines": { "node": "^20.19.0 || >=22.12.0" @@ -10144,32 +10150,32 @@ "url": "https://github.com/sponsors/Boshen" }, "optionalDependencies": { - "@oxc-parser/binding-android-arm-eabi": "0.121.0", - "@oxc-parser/binding-android-arm64": "0.121.0", - "@oxc-parser/binding-darwin-arm64": "0.121.0", - "@oxc-parser/binding-darwin-x64": "0.121.0", - "@oxc-parser/binding-freebsd-x64": "0.121.0", - "@oxc-parser/binding-linux-arm-gnueabihf": "0.121.0", - "@oxc-parser/binding-linux-arm-musleabihf": "0.121.0", - "@oxc-parser/binding-linux-arm64-gnu": "0.121.0", - "@oxc-parser/binding-linux-arm64-musl": "0.121.0", - "@oxc-parser/binding-linux-ppc64-gnu": "0.121.0", - "@oxc-parser/binding-linux-riscv64-gnu": "0.121.0", - "@oxc-parser/binding-linux-riscv64-musl": "0.121.0", - "@oxc-parser/binding-linux-s390x-gnu": "0.121.0", - "@oxc-parser/binding-linux-x64-gnu": "0.121.0", - "@oxc-parser/binding-linux-x64-musl": "0.121.0", - "@oxc-parser/binding-openharmony-arm64": "0.121.0", - "@oxc-parser/binding-wasm32-wasi": "0.121.0", - "@oxc-parser/binding-win32-arm64-msvc": "0.121.0", - "@oxc-parser/binding-win32-ia32-msvc": "0.121.0", - "@oxc-parser/binding-win32-x64-msvc": "0.121.0" + "@oxc-parser/binding-android-arm-eabi": "0.123.0", + "@oxc-parser/binding-android-arm64": "0.123.0", + "@oxc-parser/binding-darwin-arm64": "0.123.0", + "@oxc-parser/binding-darwin-x64": "0.123.0", + "@oxc-parser/binding-freebsd-x64": "0.123.0", + "@oxc-parser/binding-linux-arm-gnueabihf": "0.123.0", + "@oxc-parser/binding-linux-arm-musleabihf": "0.123.0", + "@oxc-parser/binding-linux-arm64-gnu": "0.123.0", + "@oxc-parser/binding-linux-arm64-musl": "0.123.0", + "@oxc-parser/binding-linux-ppc64-gnu": "0.123.0", + "@oxc-parser/binding-linux-riscv64-gnu": "0.123.0", + "@oxc-parser/binding-linux-riscv64-musl": "0.123.0", + "@oxc-parser/binding-linux-s390x-gnu": "0.123.0", + "@oxc-parser/binding-linux-x64-gnu": "0.123.0", + "@oxc-parser/binding-linux-x64-musl": "0.123.0", + "@oxc-parser/binding-openharmony-arm64": "0.123.0", + "@oxc-parser/binding-wasm32-wasi": "0.123.0", + "@oxc-parser/binding-win32-arm64-msvc": "0.123.0", + "@oxc-parser/binding-win32-ia32-msvc": "0.123.0", + "@oxc-parser/binding-win32-x64-msvc": "0.123.0" } }, "node_modules/oxc-parser/node_modules/@oxc-project/types": { - "version": "0.121.0", - "resolved": "https://registry.npmjs.org/@oxc-project/types/-/types-0.121.0.tgz", - "integrity": "sha512-CGtOARQb9tyv7ECgdAlFxi0Fv7lmzvmlm2rpD/RdijOO9rfk/JvB1CjT8EnoD+tjna/IYgKKw3IV7objRb+aYw==", + "version": "0.123.0", + "resolved": "https://registry.npmjs.org/@oxc-project/types/-/types-0.123.0.tgz", + "integrity": "sha512-YtECP/y8Mj1lSHiUWGSRzy/C6teUKlS87dEfuVKT09LgQbUsBW1rNg+MiJ4buGu3yuADV60gbIvo9/HplA56Ew==", "dev": true, "license": "MIT", "funding": { @@ -10209,9 +10215,9 @@ } }, "node_modules/oxc-transform": { - "version": "0.121.0", - "resolved": "https://registry.npmjs.org/oxc-transform/-/oxc-transform-0.121.0.tgz", - "integrity": "sha512-Kf243wJU/vWF/ThV+ZyfLMQIrViVFRSyYO7UPKpZMMPGGMzxxcHgsNGWy0Uy+pcXD78+jdUnxVTR9rYT73Qw3A==", + "version": "0.123.0", + "resolved": "https://registry.npmjs.org/oxc-transform/-/oxc-transform-0.123.0.tgz", + "integrity": "sha512-uuuNWbCDv391SEeF2id/TvSAMUKU8U9347cbNcpRkwcv5sobBS6C5kXE0ZLuxVEUlWatr2kfsolrA10zdPogDg==", "dev": true, "license": "MIT", "engines": { @@ -10221,26 +10227,26 @@ "url": "https://github.com/sponsors/Boshen" }, "optionalDependencies": { - "@oxc-transform/binding-android-arm-eabi": "0.121.0", - "@oxc-transform/binding-android-arm64": "0.121.0", - "@oxc-transform/binding-darwin-arm64": "0.121.0", - "@oxc-transform/binding-darwin-x64": "0.121.0", - "@oxc-transform/binding-freebsd-x64": "0.121.0", - "@oxc-transform/binding-linux-arm-gnueabihf": "0.121.0", - "@oxc-transform/binding-linux-arm-musleabihf": "0.121.0", - "@oxc-transform/binding-linux-arm64-gnu": "0.121.0", - "@oxc-transform/binding-linux-arm64-musl": "0.121.0", - "@oxc-transform/binding-linux-ppc64-gnu": "0.121.0", - "@oxc-transform/binding-linux-riscv64-gnu": "0.121.0", - "@oxc-transform/binding-linux-riscv64-musl": "0.121.0", - "@oxc-transform/binding-linux-s390x-gnu": "0.121.0", - "@oxc-transform/binding-linux-x64-gnu": "0.121.0", - "@oxc-transform/binding-linux-x64-musl": "0.121.0", - "@oxc-transform/binding-openharmony-arm64": "0.121.0", - "@oxc-transform/binding-wasm32-wasi": "0.121.0", - "@oxc-transform/binding-win32-arm64-msvc": "0.121.0", - "@oxc-transform/binding-win32-ia32-msvc": "0.121.0", - "@oxc-transform/binding-win32-x64-msvc": "0.121.0" + "@oxc-transform/binding-android-arm-eabi": "0.123.0", + "@oxc-transform/binding-android-arm64": "0.123.0", + "@oxc-transform/binding-darwin-arm64": "0.123.0", + "@oxc-transform/binding-darwin-x64": "0.123.0", + "@oxc-transform/binding-freebsd-x64": "0.123.0", + "@oxc-transform/binding-linux-arm-gnueabihf": "0.123.0", + "@oxc-transform/binding-linux-arm-musleabihf": "0.123.0", + "@oxc-transform/binding-linux-arm64-gnu": "0.123.0", + "@oxc-transform/binding-linux-arm64-musl": "0.123.0", + "@oxc-transform/binding-linux-ppc64-gnu": "0.123.0", + "@oxc-transform/binding-linux-riscv64-gnu": "0.123.0", + "@oxc-transform/binding-linux-riscv64-musl": "0.123.0", + "@oxc-transform/binding-linux-s390x-gnu": "0.123.0", + "@oxc-transform/binding-linux-x64-gnu": "0.123.0", + "@oxc-transform/binding-linux-x64-musl": "0.123.0", + "@oxc-transform/binding-openharmony-arm64": "0.123.0", + "@oxc-transform/binding-wasm32-wasi": "0.123.0", + "@oxc-transform/binding-win32-arm64-msvc": "0.123.0", + "@oxc-transform/binding-win32-ia32-msvc": "0.123.0", + "@oxc-transform/binding-win32-x64-msvc": "0.123.0" } }, "node_modules/p-map": { @@ -10413,9 +10419,9 @@ } }, "node_modules/path-to-regexp": { - "version": "8.3.0", - "resolved": "https://registry.npmjs.org/path-to-regexp/-/path-to-regexp-8.3.0.tgz", - "integrity": "sha512-7jdwVIRtsP8MYpdXSwOS0YdD0Du+qOoF/AEPIt88PcCFrZCzx41oxku1jD88hZBwbNUIEfpqvuhjFaMAqMTWnA==", + "version": "8.4.2", + "resolved": "https://registry.npmjs.org/path-to-regexp/-/path-to-regexp-8.4.2.tgz", + "integrity": "sha512-qRcuIdP69NPm4qbACK+aDogI5CBDMi1jKe0ry5rSQJz8JVLsC7jV8XpiJjGRLLol3N+R5ihGYcrPLTno6pAdBA==", "dev": true, "license": "MIT", "funding": { diff --git a/frontend/ai.client/package.json b/frontend/ai.client/package.json index 5b6183b8..a9afdf23 100644 --- a/frontend/ai.client/package.json +++ b/frontend/ai.client/package.json @@ -1,6 +1,6 @@ { "name": "ai.client", - "version": "1.0.0-beta.20", + "version": "1.0.0-beta.22", "scripts": { "ng": "ng", "start": "ng serve", @@ -24,21 +24,21 @@ "private": true, "packageManager": "npm@11.2.0", "dependencies": { - "@angular/cdk": "21.2.4", - "@angular/common": "21.2.6", - "@angular/compiler": "21.2.6", - "@angular/core": "21.2.6", - "@angular/forms": "21.2.6", - "@angular/platform-browser": "21.2.6", - "@angular/router": "21.2.6", + "@angular/cdk": "21.2.5", + "@angular/common": "21.2.7", + "@angular/compiler": "21.2.7", + "@angular/core": "21.2.7", + "@angular/forms": "21.2.7", + "@angular/platform-browser": "21.2.7", + "@angular/router": "21.2.7", "@ctrl/ngx-emoji-mart": "9.3.0", "@microsoft/fetch-event-source": "2.0.1", "@ng-icons/core": "33.2.0", "@ng-icons/heroicons": "33.2.0", "chart.js": "4.5.1", - "katex": "0.16.44", - "marked": "17.0.5", - "mermaid": "11.13.0", + "katex": "0.16.45", + "marked": "17.0.6", + "mermaid": "11.14.0", "ng2-charts": "10.0.0", "ngx-markdown": "21.1.0", "prismjs": "1.30.0", @@ -47,11 +47,11 @@ "uuid": "13.0.0" }, "devDependencies": { - "@analogjs/vite-plugin-angular": "3.0.0-alpha.18", - "@analogjs/vitest-angular": "3.0.0-alpha.18", - "@angular/build": "21.2.5", - "@angular/cli": "21.2.5", - "@angular/compiler-cli": "21.2.6", + "@analogjs/vite-plugin-angular": "3.0.0-alpha.26", + "@analogjs/vitest-angular": "3.0.0-alpha.26", + "@angular/build": "21.2.6", + "@angular/cli": "21.2.6", + "@angular/compiler-cli": "21.2.7", "@tailwindcss/postcss": "4.2.2", "@vitest/coverage-v8": "4.1.2", "fast-check": "4.6.0", diff --git a/frontend/ai.client/src/app/admin/auth-providers/pages/provider-form.page.ts b/frontend/ai.client/src/app/admin/auth-providers/pages/provider-form.page.ts index 46fd872a..c686932a 100644 --- a/frontend/ai.client/src/app/admin/auth-providers/pages/provider-form.page.ts +++ b/frontend/ai.client/src/app/admin/auth-providers/pages/provider-form.page.ts @@ -21,6 +21,7 @@ import { heroInformationCircle, } from '@ng-icons/heroicons/outline'; import { AuthProvidersService } from '../services/auth-providers.service'; +import { ConfigService } from '../../../services/config.service'; import { AuthProviderCreateRequest, AuthProviderUpdateRequest, @@ -183,6 +184,35 @@ interface ProviderFormGroup { Core OIDC settings. Enter the issuer URL and click Discover to auto-fill endpoints.

+ + @if (cognitoRedirectUri()) { +
+
+ +
+

+ Required: Add this Redirect URI to your identity provider +

+

+ In your IdP's app registration (e.g., Azure Portal, Okta Admin), add the following as an allowed redirect URI: +

+
+ + {{ cognitoRedirectUri() }} + + +
+
+
+
+ } +
@@ -647,6 +677,7 @@ export class AuthProviderFormPage implements OnInit { private router = inject(Router); private route = inject(ActivatedRoute); private authProvidersService = inject(AuthProvidersService); + private config = inject(ConfigService); readonly isEditMode = signal(false); readonly providerId = signal(null); @@ -655,6 +686,13 @@ export class AuthProviderFormPage implements OnInit { readonly discovering = signal(false); readonly discoveryResult = signal(null); readonly discoveryError = signal(null); + readonly copiedRedirectUri = signal(false); + + /** The Cognito redirect URI that must be registered in the external IdP */ + readonly cognitoRedirectUri = computed(() => { + const domain = this.config.cognitoDomainUrl(); + return domain ? `${domain}/oauth2/idpresponse` : ''; + }); readonly providerForm: FormGroup = this.fb.group({ providerId: this.fb.control('', { @@ -888,6 +926,15 @@ export class AuthProviderFormPage implements OnInit { } } + async copyRedirectUri(): Promise { + const uri = this.cognitoRedirectUri(); + if (uri) { + await navigator.clipboard.writeText(uri); + this.copiedRedirectUri.set(true); + setTimeout(() => this.copiedRedirectUri.set(false), 2000); + } + } + goBack(): void { this.router.navigate(['/admin/auth-providers']); } diff --git a/frontend/ai.client/src/app/admin/auth-providers/pages/provider-list.page.ts b/frontend/ai.client/src/app/admin/auth-providers/pages/provider-list.page.ts index 4eabc459..2472f7b5 100644 --- a/frontend/ai.client/src/app/admin/auth-providers/pages/provider-list.page.ts +++ b/frontend/ai.client/src/app/admin/auth-providers/pages/provider-list.page.ts @@ -4,7 +4,6 @@ import { inject, signal, computed, - effect, } from '@angular/core'; import { Router, RouterLink } from '@angular/router'; import { FormsModule } from '@angular/forms'; @@ -20,11 +19,7 @@ import { heroFingerPrint, heroCheckCircle, heroXCircle, - heroExclamationTriangle, - heroServerStack, - heroLink, } from '@ng-icons/heroicons/outline'; -import { heroClockSolid } from '@ng-icons/heroicons/solid'; import { AuthProvidersService } from '../services/auth-providers.service'; import { AuthProvider } from '../models/auth-provider.model'; @@ -44,10 +39,6 @@ import { AuthProvider } from '../models/auth-provider.model'; heroFingerPrint, heroCheckCircle, heroXCircle, - heroExclamationTriangle, - heroClockSolid, - heroServerStack, - heroLink, }), ], host: { @@ -79,39 +70,6 @@ import { AuthProvider } from '../models/auth-provider.model';
- - @if (currentImageTag() && hasAnyRuntimeInfo()) { -
-
-
- -
-

Runtime Version Status

-
-
- Current Image Tag: - {{ currentImageTag() }} -
-
-
- Active Runtimes: - {{ getProvidersWithRuntimes().length }} -
- @if (getOutdatedRuntimesCount() > 0) { -
-
- - Outdated: - {{ getOutdatedRuntimesCount() }} -
- } -
-
-
-
-
- } -
@@ -250,115 +208,6 @@ import { AuthProvider } from '../models/auth-provider.model';
- - @if (hasRuntimeInfo(provider)) { -
-
-
- - AgentCore Runtime - - - {{ getRuntimeStatusLabel(provider.agentcore_runtime_status) }} - -
- - - @if (provider.agentcore_runtime_status === 'READY' && hasVersionMismatch(provider)) { - - } -
- -
- - @if (provider.agentcore_runtime_id) { -
- Runtime ID: -
- {{ provider.agentcore_runtime_id }} -
-
- } - - - @if (provider.agentcore_runtime_arn) { -
- Runtime ARN: -
- {{ provider.agentcore_runtime_arn }} -
-
- } - - - @if (provider.agentcore_runtime_endpoint_url) { -
- Endpoint URL: -
- - - {{ provider.agentcore_runtime_endpoint_url }} - -
-
- } - - - @if (provider.agentcore_runtime_image_tag) { -
- Image Tag: -
- - {{ provider.agentcore_runtime_image_tag }} - - @if (hasVersionMismatch(provider)) { - - - Outdated - - } -
-
- } -
- - - @if (provider.agentcore_runtime_error) { -
-
- -
-

Error Details:

-

- {{ provider.agentcore_runtime_error }} -

-
-
-
- } -
- }
@@ -428,28 +277,10 @@ export class AuthProviderListPage { searchQuery = signal(''); enabledFilter = signal(''); testing = signal(null); - currentImageTag = signal(null); - updatingRuntime = signal(null); readonly providers = computed(() => this.authProvidersService.getProviders()); - constructor() { - // Fetch current image tag when providers are loaded - effect(() => { - if (this.providers().length > 0 && !this.currentImageTag()) { - this.fetchCurrentImageTag(); - } - }); - } - - async fetchCurrentImageTag(): Promise { - try { - const result = await this.authProvidersService.getCurrentImageTag(); - this.currentImageTag.set(result.image_tag); - } catch (error) { - console.error('Failed to fetch current image tag:', error); - } - } + constructor() {} readonly filteredProviders = computed(() => { let providers = this.providers(); @@ -518,85 +349,4 @@ export class AuthProviderListPage { } } - getRuntimeStatusBadgeClass(status?: string): string { - switch (status) { - case 'READY': - return 'bg-green-100 text-green-800 dark:bg-green-900/30 dark:text-green-300'; - case 'CREATING': - case 'UPDATING': - return 'bg-blue-100 text-blue-800 dark:bg-blue-900/30 dark:text-blue-300'; - case 'PENDING': - return 'bg-yellow-100 text-yellow-800 dark:bg-yellow-900/30 dark:text-yellow-300'; - case 'FAILED': - case 'UPDATE_FAILED': - return 'bg-red-100 text-red-800 dark:bg-red-900/30 dark:text-red-300'; - default: - return 'bg-gray-100 text-gray-600 dark:bg-gray-700 dark:text-gray-400'; - } - } - - getRuntimeStatusIcon(status?: string): string { - switch (status) { - case 'READY': - return 'heroCheckCircle'; - case 'CREATING': - case 'UPDATING': - return 'heroArrowPath'; - case 'PENDING': - return 'heroClockSolid'; - case 'FAILED': - case 'UPDATE_FAILED': - return 'heroExclamationTriangle'; - default: - return 'heroXCircle'; - } - } - - getRuntimeStatusLabel(status?: string): string { - if (!status) return 'No Runtime'; - return status.replace(/_/g, ' '); - } - - hasRuntimeInfo(provider: AuthProvider): boolean { - return !!(provider.agentcore_runtime_arn || provider.agentcore_runtime_status); - } - - hasVersionMismatch(provider: AuthProvider): boolean { - if (!provider.agentcore_runtime_image_tag || !this.currentImageTag()) { - return false; - } - return provider.agentcore_runtime_image_tag !== this.currentImageTag(); - } - - getProvidersWithRuntimes(): AuthProvider[] { - return this.providers().filter(p => p.agentcore_runtime_status === 'READY'); - } - - hasAnyRuntimeInfo(): boolean { - return this.providers().some(p => this.hasRuntimeInfo(p)); - } - - getOutdatedRuntimesCount(): number { - return this.getProvidersWithRuntimes().filter(p => this.hasVersionMismatch(p)).length; - } - - async updateRuntime(provider: AuthProvider): Promise { - if (!confirm(`Trigger manual runtime update for "${provider.display_name}"?\n\nThis will update the runtime to use the latest container image.`)) { - return; - } - - this.updatingRuntime.set(provider.provider_id); - try { - const result = await this.authProvidersService.triggerRuntimeUpdate(provider.provider_id); - alert(`Runtime update triggered successfully.\n\n${result.message}`); - // Reload providers to get updated status - this.authProvidersService.reload(); - } catch (error: any) { - console.error('Error updating runtime:', error); - const message = error?.error?.detail || error?.message || 'Failed to trigger runtime update.'; - alert(`Failed to update runtime:\n\n${message}`); - } finally { - this.updatingRuntime.set(null); - } - } } diff --git a/frontend/ai.client/src/app/admin/manage-models/manage-models.page.html b/frontend/ai.client/src/app/admin/manage-models/manage-models.page.html index 50165923..49c5651c 100644 --- a/frontend/ai.client/src/app/admin/manage-models/manage-models.page.html +++ b/frontend/ai.client/src/app/admin/manage-models/manage-models.page.html @@ -17,7 +17,7 @@

Manage Models

- + @@ -102,7 +102,7 @@

Search &

Showing {{ filteredModels().length }} model{{ filteredModels().length !== 1 ? 's' : '' }}

- + diff --git a/frontend/ai.client/src/app/admin/manage-models/model-form.page.html b/frontend/ai.client/src/app/admin/manage-models/model-form.page.html index 39336473..897db2c5 100644 --- a/frontend/ai.client/src/app/admin/manage-models/model-form.page.html +++ b/frontend/ai.client/src/app/admin/manage-models/model-form.page.html @@ -461,7 +461,50 @@

-
+
+ @if (modelForm.invalid) { +
+

+ Please fix the following before saving: +

+
    + @if (modelForm.controls.modelId.invalid) { +
  • Model ID is required
    • + } + @if (modelForm.controls.modelName.invalid) { +
  • Model Name is required
    • + } + @if (modelForm.controls.provider.invalid) { +
  • Provider is required
    • + } + @if (modelForm.controls.providerName.invalid) { +
  • Provider Name is required
    • + } + @if (modelForm.controls.inputModalities.invalid) { +
  • Select at least one input modality
    • + } + @if (modelForm.controls.outputModalities.invalid) { +
  • Select at least one output modality
    • + } + @if (modelForm.controls.maxInputTokens.invalid) { +
  • Max Input Tokens must be 1 or greater
    • + } + @if (modelForm.controls.maxOutputTokens.invalid) { +
  • Max Output Tokens must be 1 or greater
    • + } + @if (modelForm.controls.allowedAppRoles.invalid) { +
  • Select at least one allowed role
    • + } + @if (modelForm.controls.inputPricePerMillionTokens.invalid) { +
  • Input price is required (0 or greater)
    • + } + @if (modelForm.controls.outputPricePerMillionTokens.invalid) { +
  • Output price is required (0 or greater)
    • + } +
+
+ } +
+
diff --git a/frontend/ai.client/src/app/admin/roles/pages/role-form.page.ts b/frontend/ai.client/src/app/admin/roles/pages/role-form.page.ts index 0fac95ac..0389f55f 100644 --- a/frontend/ai.client/src/app/admin/roles/pages/role-form.page.ts +++ b/frontend/ai.client/src/app/admin/roles/pages/role-form.page.ts @@ -443,7 +443,7 @@ export class RoleFormPage implements OnInit { grantedModels: this.fb.control([], { nonNullable: true }), priority: this.fb.control(0, { nonNullable: true, - validators: [Validators.min(0), Validators.max(999)], + validators: [Validators.min(0), Validators.max(1000)], }), enabled: this.fb.control(true, { nonNullable: true }), }); diff --git a/frontend/ai.client/src/app/app.routes.ts b/frontend/ai.client/src/app/app.routes.ts index 3d47b361..a750cf21 100644 --- a/frontend/ai.client/src/app/app.routes.ts +++ b/frontend/ai.client/src/app/app.routes.ts @@ -1,6 +1,7 @@ import { Routes } from '@angular/router'; import { authGuard } from './auth/auth.guard'; import { adminGuard } from './auth/admin.guard'; +import { firstBootGuard } from './auth/first-boot.guard'; export const routes: Routes = [ { @@ -13,6 +14,11 @@ export const routes: Routes = [ loadComponent: () => import('./session/session.page').then(m => m.ConversationPage), canActivate: [authGuard], }, + { + path: 'auth/first-boot', + loadComponent: () => import('./auth/first-boot/first-boot.page').then(m => m.FirstBootPage), + canActivate: [firstBootGuard], + }, { path: 'shared/:shareId', loadComponent: () => import('./shared/shared-view.page').then(m => m.SharedViewPage), diff --git a/frontend/ai.client/src/app/assistants/assistant-form/services/preview-chat.service.spec.ts b/frontend/ai.client/src/app/assistants/assistant-form/services/preview-chat.service.spec.ts index 23a8d56d..46dc83a8 100644 --- a/frontend/ai.client/src/app/assistants/assistant-form/services/preview-chat.service.spec.ts +++ b/frontend/ai.client/src/app/assistants/assistant-form/services/preview-chat.service.spec.ts @@ -1,9 +1,9 @@ import { TestBed } from '@angular/core/testing'; import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest'; +import { signal } from '@angular/core'; import { PreviewChatService } from './preview-chat.service'; import { AuthService } from '../../../auth/auth.service'; -import { AuthApiService } from '../../../auth/auth-api.service'; -import { of } from 'rxjs'; +import { ConfigService } from '../../../services/config.service'; // Mock fetchEventSource vi.mock('@microsoft/fetch-event-source', () => ({ @@ -13,7 +13,6 @@ vi.mock('@microsoft/fetch-event-source', () => ({ describe('PreviewChatService', () => { let service: PreviewChatService; let authService: any; - let authApiService: any; beforeEach(() => { TestBed.resetTestingModule(); @@ -24,21 +23,20 @@ describe('PreviewChatService', () => { refreshAccessToken: vi.fn(), }; - const authApiServiceMock = { - getRuntimeEndpoint: vi.fn(), + const configServiceMock = { + inferenceApiUrl: signal('http://localhost:8001'), }; TestBed.configureTestingModule({ providers: [ PreviewChatService, { provide: AuthService, useValue: authServiceMock }, - { provide: AuthApiService, useValue: authApiServiceMock }, + { provide: ConfigService, useValue: configServiceMock }, ], }); service = TestBed.inject(PreviewChatService); authService = TestBed.inject(AuthService); - authApiService = TestBed.inject(AuthApiService); }); afterEach(() => { @@ -57,9 +55,6 @@ describe('PreviewChatService', () => { }); it('should send message', async () => { - const mockEndpoint = { runtime_endpoint_url: 'http://test.com' }; - authApiService.getRuntimeEndpoint.mockReturnValue(of(mockEndpoint)); - const { fetchEventSource } = await import('@microsoft/fetch-event-source'); (fetchEventSource as any).mockResolvedValue(undefined); @@ -112,9 +107,6 @@ describe('PreviewChatService', () => { it('should handle auth token refresh', async () => { authService.isTokenExpired.mockReturnValue(true); authService.refreshAccessToken.mockResolvedValue(undefined); - - const mockEndpoint = { runtime_endpoint_url: 'http://test.com' }; - authApiService.getRuntimeEndpoint.mockReturnValue(of(mockEndpoint)); const { fetchEventSource } = await import('@microsoft/fetch-event-source'); (fetchEventSource as any).mockResolvedValue(undefined); @@ -123,4 +115,4 @@ describe('PreviewChatService', () => { expect(authService.refreshAccessToken).toHaveBeenCalled(); }); -}); \ No newline at end of file +}); diff --git a/frontend/ai.client/src/app/assistants/assistant-form/services/preview-chat.service.ts b/frontend/ai.client/src/app/assistants/assistant-form/services/preview-chat.service.ts index 72f6b893..5c9dea3d 100644 --- a/frontend/ai.client/src/app/assistants/assistant-form/services/preview-chat.service.ts +++ b/frontend/ai.client/src/app/assistants/assistant-form/services/preview-chat.service.ts @@ -1,9 +1,8 @@ import { Injectable, inject, signal, computed } from '@angular/core'; import { v4 as uuidv4 } from 'uuid'; -import { firstValueFrom } from 'rxjs'; import { fetchEventSource, EventSourceMessage } from '@microsoft/fetch-event-source'; import { AuthService } from '../../../auth/auth.service'; -import { AuthApiService } from '../../../auth/auth-api.service'; +import { ConfigService } from '../../../services/config.service'; import { Message } from '../../../session/services/models/message.model'; import { PREVIEW_SESSION_PREFIX } from '../../../shared/constants/session.constants'; import { @@ -28,7 +27,7 @@ import { @Injectable() export class PreviewChatService { private authService = inject(AuthService); - private authApiService = inject(AuthApiService); + private config = inject(ConfigService); // Local state signals (isolated from global ChatStateService) private readonly messagesSignal = signal([]); @@ -191,14 +190,12 @@ export class PreviewChatService { try { const token = await this.getBearerTokenForStreamingResponse(); - // Resolve runtime endpoint dynamically via App API - const runtimeEndpoint = await firstValueFrom( - this.authApiService.getRuntimeEndpoint() - ); - if (!runtimeEndpoint || !runtimeEndpoint.runtime_endpoint_url) { - throw new Error('Invalid runtime endpoint response from server'); + // Single runtime endpoint from configuration + const runtimeEndpointUrl = this.config.inferenceApiUrl(); + if (!runtimeEndpointUrl) { + throw new Error('Inference API URL not configured. Please check your configuration.'); } - const url = `${runtimeEndpoint.runtime_endpoint_url}?qualifier=DEFAULT`; + const url = `${runtimeEndpointUrl}/invocations?qualifier=DEFAULT`; // NOTE: Field name is 'rag_assistant_id' to avoid collision with AWS Bedrock // AgentCore Runtime's internal 'assistant_id' field handling (causes 424 error) diff --git a/frontend/ai.client/src/app/auth/auth-api.service.spec.ts b/frontend/ai.client/src/app/auth/auth-api.service.spec.ts deleted file mode 100644 index b3846662..00000000 --- a/frontend/ai.client/src/app/auth/auth-api.service.spec.ts +++ /dev/null @@ -1,101 +0,0 @@ -import { TestBed } from '@angular/core/testing'; -import { HttpClientTestingModule, HttpTestingController } from '@angular/common/http/testing'; -import { AuthApiService, RuntimeEndpointResponse } from './auth-api.service'; -import { ConfigService } from '../services/config.service'; -import { signal } from '@angular/core'; - -describe('AuthApiService', () => { - let service: AuthApiService; - let httpMock: HttpTestingController; - let configService: Partial; - - beforeEach(() => { - TestBed.resetTestingModule(); - configService = { - appApiUrl: signal('http://localhost:8000') - }; - - TestBed.configureTestingModule({ - imports: [HttpClientTestingModule], - providers: [ - AuthApiService, - { provide: ConfigService, useValue: configService } - ] - }); - - service = TestBed.inject(AuthApiService); - httpMock = TestBed.inject(HttpTestingController); - }); - - afterEach(() => { - TestBed.resetTestingModule(); - httpMock.match(() => true); - }); - - it('should be created', () => { - expect(service).toBeTruthy(); - }); - - describe('getRuntimeEndpoint', () => { - it('should fetch runtime endpoint URL', async () => { - const mockResponse: RuntimeEndpointResponse = { - runtime_endpoint_url: 'https://bedrock-agentcore.us-east-1.amazonaws.com/runtimes/arn:aws:bedrock-agentcore:us-east-1:123456789012:agent/abc-123/invocations', - provider_id: 'entra-id' - }; - - const promise = new Promise((resolve, reject) => { - service.getRuntimeEndpoint().subscribe({ - next: resolve, - error: reject - }); - }); - - const req = httpMock.expectOne('http://localhost:8000/auth/runtime-endpoint'); - expect(req.request.method).toBe('GET'); - req.flush(mockResponse); - - const response = await promise; - expect(response).toEqual(mockResponse); - expect(response.runtime_endpoint_url).toBe(mockResponse.runtime_endpoint_url); - expect(response.provider_id).toBe('entra-id'); - }); - - it('should handle 404 error when provider not found', async () => { - const promise = new Promise((resolve, reject) => { - service.getRuntimeEndpoint().subscribe({ - next: resolve, - error: reject - }); - }); - - const req = httpMock.expectOne('http://localhost:8000/auth/runtime-endpoint'); - req.flush('Runtime not found for provider', { status: 404, statusText: 'Not Found' }); - - try { - await promise; - throw new Error('Should have thrown 404 error'); - } catch (error: any) { - expect(error.status).toBe(404); - } - }); - - it('should handle 401 error when user not authenticated', async () => { - const promise = new Promise((resolve, reject) => { - service.getRuntimeEndpoint().subscribe({ - next: resolve, - error: reject - }); - }); - - const req = httpMock.expectOne('http://localhost:8000/auth/runtime-endpoint'); - req.flush('Unauthorized', { status: 401, statusText: 'Unauthorized' }); - - try { - await promise; - throw new Error('Should have thrown 401 error'); - } catch (error: any) { - expect(error.status).toBe(401); - } - }); - }); -}); diff --git a/frontend/ai.client/src/app/auth/auth-api.service.ts b/frontend/ai.client/src/app/auth/auth-api.service.ts deleted file mode 100644 index a3f2f5f0..00000000 --- a/frontend/ai.client/src/app/auth/auth-api.service.ts +++ /dev/null @@ -1,64 +0,0 @@ -import { Injectable, inject, computed } from '@angular/core'; -import { HttpClient } from '@angular/common/http'; -import { Observable } from 'rxjs'; -import { ConfigService } from '../services/config.service'; - -/** - * Response from the runtime endpoint API. - */ -export interface RuntimeEndpointResponse { - runtime_endpoint_url: string; - provider_id: string; -} - -/** - * Service for authentication-related API calls. - * Handles runtime endpoint resolution for multi-provider authentication. - */ -@Injectable({ - providedIn: 'root' -}) -export class AuthApiService { - private http = inject(HttpClient); - private config = inject(ConfigService); - - // Use computed signal for reactive base URL - private readonly baseUrl = computed(() => `${this.config.appApiUrl()}/auth`); - - /** - * Get the AgentCore Runtime endpoint URL for the user's auth provider. - * - * The backend resolves the provider by extracting the issuer claim from the - * user's JWT token and matching it against configured providers in the database. - * Each provider has its own dedicated runtime with provider-specific JWT validation. - * - * Flow: - * 1. Frontend sends authenticated request (JWT in Authorization header) - * 2. Backend extracts issuer from JWT (e.g., "https://login.microsoftonline.com/{tenant}/v2.0") - * 3. Backend matches issuer to provider in database - * 4. Backend returns runtime endpoint URL for that provider - * - * @returns Observable of runtime endpoint response containing the endpoint URL and provider ID - * @throws HTTP 404 if provider not found or runtime not ready - * @throws HTTP 401 if user is not authenticated - * - * @example - * ```typescript - * this.authApiService.getRuntimeEndpoint().subscribe({ - * next: (response) => { - * console.log('Runtime endpoint:', response.runtime_endpoint_url); - * console.log('Provider:', response.provider_id); - * // Use this endpoint for inference API calls - * }, - * error: (error) => { - * if (error.status === 404) { - * console.error('Runtime not found for provider'); - * } - * } - * }); - * ``` - */ - getRuntimeEndpoint(): Observable { - return this.http.get(`${this.baseUrl()}/runtime-endpoint`); - } -} diff --git a/frontend/ai.client/src/app/auth/auth.guard.spec.ts b/frontend/ai.client/src/app/auth/auth.guard.spec.ts index 3a016cf8..3163e42c 100644 --- a/frontend/ai.client/src/app/auth/auth.guard.spec.ts +++ b/frontend/ai.client/src/app/auth/auth.guard.spec.ts @@ -2,6 +2,7 @@ import { TestBed } from '@angular/core/testing'; import { Router, ActivatedRouteSnapshot, RouterStateSnapshot } from '@angular/router'; import { authGuard } from './auth.guard'; import { AuthService } from './auth.service'; +import { SystemService } from '../services/system.service'; import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest'; describe('authGuard', () => { @@ -11,6 +12,7 @@ describe('authGuard', () => { isTokenExpired: ReturnType; refreshAccessToken: ReturnType; }; + let systemService: { checkStatus: ReturnType }; let router: { navigate: ReturnType }; let route: ActivatedRouteSnapshot; let state: RouterStateSnapshot; @@ -28,6 +30,10 @@ describe('authGuard', () => { navigate: vi.fn(), }; + systemService = { + checkStatus: vi.fn().mockResolvedValue(true), + }; + route = {} as ActivatedRouteSnapshot; state = { url: '/dashboard' } as RouterStateSnapshot; @@ -35,6 +41,7 @@ describe('authGuard', () => { providers: [ { provide: AuthService, useValue: authService }, { provide: Router, useValue: router }, + { provide: SystemService, useValue: systemService }, ], }); }); diff --git a/frontend/ai.client/src/app/auth/auth.guard.ts b/frontend/ai.client/src/app/auth/auth.guard.ts index 1c4b4179..6bdc5c03 100644 --- a/frontend/ai.client/src/app/auth/auth.guard.ts +++ b/frontend/ai.client/src/app/auth/auth.guard.ts @@ -1,18 +1,20 @@ import { inject } from '@angular/core'; import { Router, CanActivateFn } from '@angular/router'; import { AuthService } from './auth.service'; +import { SystemService } from '../services/system.service'; /** * Route guard that protects routes requiring authentication. * * Checks if the user is authenticated. If not authenticated: * - Attempts to refresh token if expired - * - Redirects to /auth/login if refresh fails or no token exists + * - Checks system status to redirect to first-boot or login * * @returns True if user is authenticated, false otherwise (triggers redirect) */ export const authGuard: CanActivateFn = async (route, state) => { const authService = inject(AuthService); + const systemService = inject(SystemService); const router = inject(Router); // Check if user is authenticated @@ -30,15 +32,22 @@ export const authGuard: CanActivateFn = async (route, state) => { return true; } } catch (error) { - // Refresh failed, redirect to login - router.navigate(['/auth/login'], { - queryParams: { returnUrl: state.url } - }); + // Refresh failed — fall through to redirect logic + } + } + + // Check if first-boot is needed before redirecting + try { + const firstBootCompleted = await systemService.checkStatus(); + if (!firstBootCompleted) { + router.navigate(['/auth/first-boot']); return false; } + } catch { + // If status check fails, fall through to login } - // No token or refresh failed, redirect to login + // First-boot done (or check failed), redirect to login router.navigate(['/auth/login'], { queryParams: { returnUrl: state.url } }); diff --git a/frontend/ai.client/src/app/auth/auth.interceptor.spec.ts b/frontend/ai.client/src/app/auth/auth.interceptor.spec.ts index 7445b1d4..763f6c5f 100644 --- a/frontend/ai.client/src/app/auth/auth.interceptor.spec.ts +++ b/frontend/ai.client/src/app/auth/auth.interceptor.spec.ts @@ -67,25 +67,12 @@ describe('authInterceptor', () => { /** * Validates: Requirements 14.3 - * Skips auth endpoints — passes request through without modification + * Skips skip endpoints — passes request through without modification */ - it('should skip adding token for /auth/login endpoint', () => { - authService.getAccessToken.mockReturnValue('my-token'); - - const req = new HttpRequest('GET', 'http://localhost:8000/auth/login?provider_id=test'); - - TestBed.runInInjectionContext(() => { - authInterceptor(req, next); - }); - - const passedReq = (next as ReturnType).mock.calls[0][0] as HttpRequest; - expect(passedReq.headers.has('Authorization')).toBe(false); - }); - - it('should skip adding token for /auth/token endpoint', () => { + it('should skip adding token for /auth/providers endpoint', () => { authService.getAccessToken.mockReturnValue('my-token'); - const req = new HttpRequest('POST', 'http://localhost:8000/auth/token', {}); + const req = new HttpRequest('GET', 'http://localhost:8000/auth/providers'); TestBed.runInInjectionContext(() => { authInterceptor(req, next); @@ -95,10 +82,10 @@ describe('authInterceptor', () => { expect(passedReq.headers.has('Authorization')).toBe(false); }); - it('should skip adding token for /auth/refresh endpoint', () => { + it('should skip adding token for /config.json endpoint', () => { authService.getAccessToken.mockReturnValue('my-token'); - const req = new HttpRequest('POST', 'http://localhost:8000/auth/refresh', {}); + const req = new HttpRequest('GET', '/config.json'); TestBed.runInInjectionContext(() => { authInterceptor(req, next); @@ -108,17 +95,18 @@ describe('authInterceptor', () => { expect(passedReq.headers.has('Authorization')).toBe(false); }); - it('should skip adding token for /auth/providers endpoint', () => { + it('should add token for regular API endpoints', () => { authService.getAccessToken.mockReturnValue('my-token'); + authService.isTokenExpired.mockReturnValue(false); - const req = new HttpRequest('GET', 'http://localhost:8000/auth/providers'); + const req = new HttpRequest('GET', 'http://localhost:8000/api/sessions'); TestBed.runInInjectionContext(() => { authInterceptor(req, next); }); const passedReq = (next as ReturnType).mock.calls[0][0] as HttpRequest; - expect(passedReq.headers.has('Authorization')).toBe(false); + expect(passedReq.headers.get('Authorization')).toBe('Bearer my-token'); }); /** diff --git a/frontend/ai.client/src/app/auth/auth.interceptor.ts b/frontend/ai.client/src/app/auth/auth.interceptor.ts index 885b3f6d..d22f987d 100644 --- a/frontend/ai.client/src/app/auth/auth.interceptor.ts +++ b/frontend/ai.client/src/app/auth/auth.interceptor.ts @@ -12,12 +12,12 @@ export const authInterceptor: HttpInterceptorFn = (req, next) => { const authService = inject(AuthService); const configService = inject(ConfigService); - // Skip adding token for auth endpoints (login, token exchange, refresh) and config bootstrap - const authEndpoints = ['/auth/login', '/auth/token', '/auth/refresh', '/auth/providers', '/config.json']; - const isAuthEndpoint = authEndpoints.some(endpoint => req.url.includes(endpoint)); + // Skip adding token for config bootstrap and auth provider listing + const skipEndpoints = ['/auth/providers', '/config.json']; + const isSkipEndpoint = skipEndpoints.some(endpoint => req.url.includes(endpoint)); - // If it's an auth endpoint, proceed without modification - if (isAuthEndpoint) { + // If it's a skip endpoint, proceed without modification + if (isSkipEndpoint) { return next(req); } @@ -71,7 +71,7 @@ export const authInterceptor: HttpInterceptorFn = (req, next) => { // Handle 401 errors - token might have expired during request return request$.pipe( catchError((error: HttpErrorResponse) => { - if (error.status === 401 && !isAuthEndpoint) { + if (error.status === 401 && !isSkipEndpoint) { // Try refreshing token one more time return from(authService.refreshAccessToken()).pipe( switchMap(() => { diff --git a/frontend/ai.client/src/app/auth/auth.service.spec.ts b/frontend/ai.client/src/app/auth/auth.service.spec.ts index 7d687ae7..f370bd0c 100644 --- a/frontend/ai.client/src/app/auth/auth.service.spec.ts +++ b/frontend/ai.client/src/app/auth/auth.service.spec.ts @@ -1,13 +1,12 @@ +// @vitest-environment jsdom import { TestBed } from '@angular/core/testing'; -import { HttpClientTestingModule, HttpTestingController } from '@angular/common/http/testing'; -import { AuthService, TokenRefreshResponse, LoginResponse } from './auth.service'; +import { AuthService, TokenRefreshResponse } from './auth.service'; import { ConfigService } from '../services/config.service'; import { signal } from '@angular/core'; import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest'; describe('AuthService', () => { let service: AuthService; - let httpMock: HttpTestingController; let configService: Partial; // Mock localStorage @@ -38,7 +37,7 @@ describe('AuthService', () => { // Prevent actual redirects Object.defineProperty(window, 'location', { - value: { href: '' }, + value: { href: '', origin: 'http://localhost:4200' }, writable: true, configurable: true, }); @@ -47,11 +46,13 @@ describe('AuthService', () => { vi.spyOn(window, 'dispatchEvent').mockImplementation(() => true); configService = { - appApiUrl: signal('http://localhost:8000'), + appApiUrl: signal('http://localhost:8000') as any, + cognitoDomainUrl: signal('https://myprefix.auth.us-east-1.amazoncognito.com') as any, + cognitoAppClientId: signal('test-client-id') as any, + cognitoRegion: signal('us-east-1') as any, }; TestBed.configureTestingModule({ - imports: [HttpClientTestingModule], providers: [ AuthService, { provide: ConfigService, useValue: configService }, @@ -59,19 +60,15 @@ describe('AuthService', () => { }); service = TestBed.inject(AuthService); - httpMock = TestBed.inject(HttpTestingController); }); afterEach(() => { TestBed.resetTestingModule(); - httpMock.match(() => true); vi.restoreAllMocks(); }); - /** - * Validates: Requirements 12.2 - * storeTokens stores access_token, refresh_token, and computed expiry to localStorage - */ + // ─── Token Storage ────────────────────────────────────────────────── + describe('storeTokens', () => { it('should store access_token, refresh_token, and expiry in localStorage', () => { const now = Date.now(); @@ -104,10 +101,8 @@ describe('AuthService', () => { }); }); - /** - * Validates: Requirements 12.3 - * getAccessToken returns stored token - */ + // ─── Token Retrieval ──────────────────────────────────────────────── + describe('getAccessToken', () => { it('should return the stored access token', () => { store['access_token'] = 'my-token'; @@ -119,26 +114,30 @@ describe('AuthService', () => { }); }); - /** - * Validates: Requirements 12.4, 12.5, 12.6 - * isTokenExpired behavior for valid, within-buffer, and missing expiry - */ + describe('getRefreshToken', () => { + it('should return stored refresh token', () => { + store['refresh_token'] = 'my-refresh'; + expect(service.getRefreshToken()).toBe('my-refresh'); + }); + it('should return null when no refresh token', () => { + expect(service.getRefreshToken()).toBeNull(); + }); + }); + + // ─── Token Expiry ─────────────────────────────────────────────────── + describe('isTokenExpired', () => { it('should return false when token expiry is in the future beyond the buffer', () => { const now = Date.now(); vi.spyOn(Date, 'now').mockReturnValue(now); - // Expiry is 2 minutes from now, buffer is default 60s store['token_expiry'] = (now + 120_000).toString(); - expect(service.isTokenExpired()).toBe(false); }); it('should return true when token expiry is within the buffer window', () => { const now = Date.now(); vi.spyOn(Date, 'now').mockReturnValue(now); - // Expiry is 30 seconds from now, buffer is default 60s store['token_expiry'] = (now + 30_000).toString(); - expect(service.isTokenExpired()).toBe(true); }); @@ -150,22 +149,18 @@ describe('AuthService', () => { const now = Date.now(); vi.spyOn(Date, 'now').mockReturnValue(now); store['token_expiry'] = (now - 10_000).toString(); - expect(service.isTokenExpired()).toBe(true); }); }); - /** - * Validates: Requirements 12.7, 12.8 - * isAuthenticated true/false based on token presence and expiry - */ + // ─── isAuthenticated ───────────────────────────────────────────────── + describe('isAuthenticated', () => { it('should return true when a valid non-expired token exists', () => { const now = Date.now(); vi.spyOn(Date, 'now').mockReturnValue(now); store['access_token'] = 'valid-token'; store['token_expiry'] = (now + 120_000).toString(); - expect(service.isAuthenticated()).toBe(true); }); @@ -178,17 +173,14 @@ describe('AuthService', () => { vi.spyOn(Date, 'now').mockReturnValue(now); store['access_token'] = 'expired-token'; store['token_expiry'] = (now - 10_000).toString(); - expect(service.isAuthenticated()).toBe(false); }); }); - /** - * Validates: Requirements 12.9 - * clearTokens removes all keys and resets provider signal - */ + // ─── clearTokens ─────────────────────────────────────────────────── + describe('clearTokens', () => { - it('should remove access_token, refresh_token, token_expiry, and provider_id from localStorage', () => { + it('should remove all auth keys from localStorage', () => { store['access_token'] = 'tok'; store['refresh_token'] = 'ref'; store['token_expiry'] = '123'; @@ -204,55 +196,185 @@ describe('AuthService', () => { it('should set currentProviderId signal to null', () => { store['auth_provider_id'] = 'provider1'; - // Re-trigger provider update service.storeTokens({ access_token: 'x', expires_in: 3600 }); - service.clearTokens(); - expect(service.currentProviderId()).toBeNull(); }); }); - /** - * Validates: Requirements 12.10 - * login stores state in sessionStorage and provider_id in localStorage - */ + // ─── Login (Cognito OAuth 2.0 + PKCE) ────────────────────────────── + describe('login', () => { - it('should store state in sessionStorage and provider_id in localStorage before redirecting', async () => { - const loginPromise = service.login('my-provider'); + it('should store state and code_verifier in sessionStorage and redirect to Cognito authorize', async () => { + await service.login(); - const req = httpMock.expectOne( - (r) => r.url.includes('/auth/login') && r.method === 'GET' - ); - req.flush({ - authorization_url: 'https://idp.example.com/authorize?state=abc', - state: 'state-token-123', - } as LoginResponse); + // State and code verifier should be stored in sessionStorage + expect(sessionStorageMock.setItem).toHaveBeenCalledWith('auth_state', expect.any(String)); + expect(sessionStorageMock.setItem).toHaveBeenCalledWith('auth_code_verifier', expect.any(String)); + + // Should redirect to Cognito authorize endpoint + const href = window.location.href; + expect(href).toContain('https://myprefix.auth.us-east-1.amazoncognito.com/oauth2/authorize'); + expect(href).toContain('response_type=code'); + expect(href).toContain('client_id=test-client-id'); + expect(href).toContain('code_challenge_method=S256'); + expect(href).toContain('scope=openid+profile+email'); + }); + + it('should include identity_provider param when providerId is given', async () => { + await service.login('Okta'); - await loginPromise; + const href = window.location.href; + expect(href).toContain('identity_provider=Okta'); + expect(localStorageMock.setItem).toHaveBeenCalledWith('auth_provider_id', 'Okta'); + }); + + it('should not include identity_provider param when no providerId', async () => { + await service.login(); - expect(sessionStorageMock.setItem).toHaveBeenCalledWith('auth_state', 'state-token-123'); - expect(localStorageMock.setItem).toHaveBeenCalledWith('auth_provider_id', 'my-provider'); - expect(window.location.href).toBe('https://idp.example.com/authorize?state=abc'); + const href = window.location.href; + expect(href).not.toContain('identity_provider'); }); + }); - it('should clear state on login error', async () => { - const loginPromise = service.login('bad-provider'); + // ─── handleCallback ────────────────────────────────────────────────── - const req = httpMock.expectOne( - (r) => r.url.includes('/auth/login') && r.method === 'GET' + describe('handleCallback', () => { + it('should exchange code for tokens via Cognito token endpoint', async () => { + // Set up stored state and code verifier + sessionStore['auth_state'] = 'test-state'; + sessionStore['auth_code_verifier'] = 'test-verifier'; + + const mockResponse: TokenRefreshResponse = { + access_token: 'new-access-token', + refresh_token: 'new-refresh-token', + token_type: 'Bearer', + expires_in: 3600, + scope: 'openid profile email', + }; + + vi.stubGlobal('fetch', vi.fn().mockResolvedValue({ + ok: true, + json: () => Promise.resolve(mockResponse), + })); + + await service.handleCallback('auth-code-123', 'test-state'); + + // Verify fetch was called with correct Cognito token endpoint + expect(fetch).toHaveBeenCalledWith( + 'https://myprefix.auth.us-east-1.amazoncognito.com/oauth2/token', + expect.objectContaining({ + method: 'POST', + headers: { 'Content-Type': 'application/x-www-form-urlencoded' }, + }) ); - req.flush('Server error', { status: 500, statusText: 'Internal Server Error' }); - await expect(loginPromise).rejects.toThrow(); + // Verify tokens were stored + expect(localStorageMock.setItem).toHaveBeenCalledWith('access_token', 'new-access-token'); + expect(localStorageMock.setItem).toHaveBeenCalledWith('refresh_token', 'new-refresh-token'); + + // Verify session storage was cleaned up expect(sessionStorageMock.removeItem).toHaveBeenCalledWith('auth_state'); + expect(sessionStorageMock.removeItem).toHaveBeenCalledWith('auth_code_verifier'); + }); + + it('should throw on state mismatch', async () => { + sessionStore['auth_state'] = 'stored-state'; + + await expect(service.handleCallback('code', 'wrong-state')) + .rejects.toThrow(/State mismatch/); + }); + + it('should throw when no code verifier is found', async () => { + sessionStore['auth_state'] = 'test-state'; + // No code verifier stored + + await expect(service.handleCallback('code', 'test-state')) + .rejects.toThrow(/No code verifier found/); + }); + + it('should throw when token exchange fails', async () => { + sessionStore['auth_state'] = 'test-state'; + sessionStore['auth_code_verifier'] = 'test-verifier'; + + vi.stubGlobal('fetch', vi.fn().mockResolvedValue({ + ok: false, + text: () => Promise.resolve('invalid_grant'), + })); + + await expect(service.handleCallback('bad-code', 'test-state')) + .rejects.toThrow(/Token exchange failed/); + }); + }); + + // ─── refreshAccessToken ───────────────────────────────────────────── + + describe('refreshAccessToken', () => { + it('should refresh tokens via Cognito token endpoint', async () => { + store['refresh_token'] = 'my-refresh-token'; + + const mockResponse: TokenRefreshResponse = { + access_token: 'refreshed-access-token', + token_type: 'Bearer', + expires_in: 3600, + scope: 'openid profile email', + }; + + vi.stubGlobal('fetch', vi.fn().mockResolvedValue({ + ok: true, + json: () => Promise.resolve(mockResponse), + })); + + const result = await service.refreshAccessToken(); + + expect(fetch).toHaveBeenCalledWith( + 'https://myprefix.auth.us-east-1.amazoncognito.com/oauth2/token', + expect.objectContaining({ + method: 'POST', + headers: { 'Content-Type': 'application/x-www-form-urlencoded' }, + }) + ); + + expect(result.access_token).toBe('refreshed-access-token'); + expect(localStorageMock.setItem).toHaveBeenCalledWith('access_token', 'refreshed-access-token'); + }); + + it('should throw when no refresh token available', async () => { + await expect(service.refreshAccessToken()).rejects.toThrow(/No refresh token available/); + }); + + it('should clear tokens on 400/401 from Cognito', async () => { + store['refresh_token'] = 'bad-refresh'; + + vi.stubGlobal('fetch', vi.fn().mockResolvedValue({ + ok: false, + status: 400, + text: () => Promise.resolve('invalid_grant'), + })); + + await expect(service.refreshAccessToken()).rejects.toThrow(/Token refresh failed/); + expect(localStorageMock.removeItem).toHaveBeenCalledWith('access_token'); + expect(localStorageMock.removeItem).toHaveBeenCalledWith('refresh_token'); + }); + + it('should NOT clear tokens on 500 from Cognito', async () => { + store['refresh_token'] = 'my-refresh'; + localStorageMock.removeItem.mockClear(); + + vi.stubGlobal('fetch', vi.fn().mockResolvedValue({ + ok: false, + status: 500, + text: () => Promise.resolve('Internal Server Error'), + })); + + await expect(service.refreshAccessToken()).rejects.toThrow(/Token refresh failed/); + expect(localStorageMock.removeItem).not.toHaveBeenCalledWith('access_token'); + expect(localStorageMock.removeItem).not.toHaveBeenCalledWith('refresh_token'); }); }); - /** - * Validates: Requirements 12.11, 12.12, 12.13 - * ensureAuthenticated resolves/refreshes/throws - */ + // ─── ensureAuthenticated ───────────────────────────────────────────── + describe('ensureAuthenticated', () => { it('should resolve without error when token is valid', async () => { const now = Date.now(); @@ -268,33 +390,25 @@ describe('AuthService', () => { vi.spyOn(Date, 'now').mockReturnValue(now); store['access_token'] = 'expired-token'; store['refresh_token'] = 'my-refresh-token'; - // Token expired 10s ago store['token_expiry'] = (now - 10_000).toString(); - const ensurePromise = service.ensureAuthenticated(); - - // The service will call refreshAccessToken which makes an HTTP POST - const req = httpMock.expectOne( - (r) => r.url.includes('/auth/refresh') && r.method === 'POST' - ); - - const refreshResponse: TokenRefreshResponse = { + const mockResponse: TokenRefreshResponse = { access_token: 'new-access-token', refresh_token: 'new-refresh-token', token_type: 'Bearer', expires_in: 3600, scope: 'openid', }; - req.flush(refreshResponse); - // After refresh, storeTokens is called which updates localStorage - // We need the new token to appear valid - // The mock setItem updates our store, so isAuthenticated should now return true - await expect(ensurePromise).resolves.toBeUndefined(); + vi.stubGlobal('fetch', vi.fn().mockResolvedValue({ + ok: true, + json: () => Promise.resolve(mockResponse), + })); + + await expect(service.ensureAuthenticated()).resolves.toBeUndefined(); }); it('should throw when no token exists', async () => { - // No token in store at all await expect(service.ensureAuthenticated()).rejects.toThrow(/not authenticated/i); }); @@ -305,71 +419,66 @@ describe('AuthService', () => { store['refresh_token'] = 'bad-refresh'; store['token_expiry'] = (now - 10_000).toString(); - const ensurePromise = service.ensureAuthenticated(); - - const req = httpMock.expectOne( - (r) => r.url.includes('/auth/refresh') && r.method === 'POST' - ); - req.flush('Refresh failed', { status: 401, statusText: 'Unauthorized' }); + vi.stubGlobal('fetch', vi.fn().mockResolvedValue({ + ok: false, + status: 401, + text: () => Promise.resolve('Unauthorized'), + })); - await expect(ensurePromise).rejects.toThrow(/not authenticated/i); + await expect(service.ensureAuthenticated()).rejects.toThrow(/not authenticated/i); }); }); - /** - * Validates: logout method - */ + // ─── Logout ───────────────────────────────────────────────────────── + describe('logout', () => { - it('should clear tokens and redirect to logout URL', async () => { + it('should clear tokens and redirect to Cognito logout endpoint', async () => { store['access_token'] = 'token'; store['refresh_token'] = 'refresh'; - store['auth_provider_id'] = 'provider1'; - const logoutPromise = service.logout(); - - const req = httpMock.expectOne( - (r) => r.url.includes('/auth/logout') && r.method === 'GET' - ); - req.flush({ logout_url: 'https://idp.example.com/logout' }); - - await logoutPromise; + await service.logout(); expect(localStorageMock.removeItem).toHaveBeenCalledWith('access_token'); expect(localStorageMock.removeItem).toHaveBeenCalledWith('refresh_token'); expect(localStorageMock.removeItem).toHaveBeenCalledWith('token_expiry'); expect(localStorageMock.removeItem).toHaveBeenCalledWith('auth_provider_id'); - expect(window.location.href).toBe('https://idp.example.com/logout'); + + const href = window.location.href; + expect(href).toContain('https://myprefix.auth.us-east-1.amazoncognito.com/logout'); + expect(href).toContain('client_id=test-client-id'); + expect(href).toContain('logout_uri='); }); - it('should handle logout error gracefully', async () => { - const logoutPromise = service.logout(); + it('should redirect to / when Cognito config is not available', async () => { + // Override config to return empty values + (configService as any).cognitoDomainUrl = signal(''); + (configService as any).cognitoAppClientId = signal(''); - const req = httpMock.expectOne( - (r) => r.url.includes('/auth/logout') && r.method === 'GET' - ); - req.flush('Server error', { status: 500, statusText: 'Internal Server Error' }); + // Re-create service with empty config + service = TestBed.inject(AuthService); + + await service.logout(); - // Logout should not throw - it handles errors gracefully - await logoutPromise; + expect(window.location.href).toBe('/'); }); }); - describe('getRefreshToken', () => { - it('should return stored refresh token', () => { - store['refresh_token'] = 'my-refresh'; - expect(service.getRefreshToken()).toBe('my-refresh'); + // ─── Utility Methods ──────────────────────────────────────────────── + + describe('getAuthorizationHeader', () => { + it('should return Bearer header when token exists', () => { + store['access_token'] = 'my-token'; + expect(service.getAuthorizationHeader()).toBe('Bearer my-token'); }); - it('should return null when no refresh token', () => { - expect(service.getRefreshToken()).toBeNull(); + it('should return null when no token', () => { + expect(service.getAuthorizationHeader()).toBeNull(); }); }); describe('getProviderId', () => { - it('should return provider ID after storeTokens with provider', () => { + it('should return provider ID from localStorage', () => { store['auth_provider_id'] = 'provider-1'; - // Re-create service to pick up the stored provider service.storeTokens({ access_token: 'x', expires_in: 3600 }); - // Provider ID is set via localStorage, not storeTokens expect(service.getProviderId()).toBe('provider-1'); }); it('should return null when no provider ID', () => { @@ -377,66 +486,15 @@ describe('AuthService', () => { }); }); - describe('getAuthorizationHeader', () => { - it('should return Bearer header when token exists', () => { - store['access_token'] = 'my-token'; - expect(service.getAuthorizationHeader()).toBe('Bearer my-token'); - }); - it('should return null when no token', () => { - expect(service.getAuthorizationHeader()).toBeNull(); - }); - }); - - describe('storeTokens event dispatching', () => { - it('should dispatch token-stored event', () => { + describe('event dispatching', () => { + it('should dispatch token-stored event on storeTokens', () => { service.storeTokens({ access_token: 'tok', expires_in: 3600 }); expect(window.dispatchEvent).toHaveBeenCalled(); }); - }); - describe('clearTokens event dispatching', () => { - it('should dispatch token-cleared event', () => { + it('should dispatch token-cleared event on clearTokens', () => { service.clearTokens(); expect(window.dispatchEvent).toHaveBeenCalled(); }); }); - - /** - * Validates: Issue #24 fix - * refreshAccessToken only clears tokens on 401, not transient errors - */ - describe('refreshAccessToken selective token clearing', () => { - beforeEach(() => { - store['access_token'] = 'expired-token'; - store['refresh_token'] = 'my-refresh-token'; - store['auth_provider_id'] = 'entra-id'; - localStorageMock.removeItem.mockClear(); - }); - - it('should clear tokens when refresh fails with 401', async () => { - const refreshPromise = service.refreshAccessToken(); - - const req = httpMock.expectOne( - (r) => r.url.includes('/auth/refresh') && r.method === 'POST' - ); - req.flush('Unauthorized', { status: 401, statusText: 'Unauthorized' }); - - await expect(refreshPromise).rejects.toThrow(); - expect(localStorageMock.removeItem).toHaveBeenCalledWith('access_token'); - expect(localStorageMock.removeItem).toHaveBeenCalledWith('refresh_token'); - }); - - it('should NOT clear tokens when refresh fails with a non-401 error', async () => { - const refreshPromise = service.refreshAccessToken(); - - const req = httpMock.expectOne( - (r) => r.url.includes('/auth/refresh') && r.method === 'POST' - ); - req.flush('Internal Server Error', { status: 500, statusText: 'Internal Server Error' }); - - await expect(refreshPromise).rejects.toThrow(); - expect(localStorageMock.removeItem).not.toHaveBeenCalledWith('access_token'); - expect(localStorageMock.removeItem).not.toHaveBeenCalledWith('refresh_token'); - }); - }); }); diff --git a/frontend/ai.client/src/app/auth/auth.service.ts b/frontend/ai.client/src/app/auth/auth.service.ts index 5b90a0ab..1b591a77 100644 --- a/frontend/ai.client/src/app/auth/auth.service.ts +++ b/frontend/ai.client/src/app/auth/auth.service.ts @@ -1,65 +1,53 @@ import { inject, Injectable, computed, signal } from '@angular/core'; -import { HttpClient, HttpErrorResponse } from '@angular/common/http'; -import { firstValueFrom } from 'rxjs'; import { ConfigService } from '../services/config.service'; -export interface TokenRefreshRequest { - refresh_token: string; -} - export interface TokenRefreshResponse { access_token: string; - refresh_token: string; + refresh_token?: string; id_token?: string; token_type: string; expires_in: number; - scope: string; -} - -export interface LoginResponse { - authorization_url: string; - state: string; -} - -export interface LogoutResponse { - logout_url: string; + scope?: string; } @Injectable({ providedIn: 'root' }) export class AuthService { - private http = inject(HttpClient); private config = inject(ConfigService); private readonly tokenKey = 'access_token'; + private readonly idTokenKey = 'id_token'; private readonly refreshTokenKey = 'refresh_token'; private readonly tokenExpiryKey = 'token_expiry'; private readonly stateKey = 'auth_state'; + private readonly codeVerifierKey = 'auth_code_verifier'; private readonly returnUrlKey = 'auth_return_url'; private readonly providerIdKey = 'auth_provider_id'; - // Computed signal for reactive base URL - private readonly baseUrl = computed(() => this.config.appApiUrl()); + // Cognito endpoints derived from runtime config + private readonly cognitoDomain = computed(() => this.config.cognitoDomainUrl()); + private readonly cognitoClientId = computed(() => this.config.cognitoAppClientId()); + + private get redirectUri(): string { + return `${window.location.origin}/auth/callback`; + } + + private get logoutUri(): string { + return window.location.origin; + } /** * Signal tracking the current authentication provider ID. - * Resolved from the JWT token's issuer claim by the backend. * Used for display purposes and tracking which provider the user authenticated with. - * - * Note: The backend resolves the provider by matching the token's issuer claim - * against configured providers. The frontend doesn't need to extract the issuer - * directly - it just tracks the provider_id returned from the backend. */ readonly currentProviderId = signal(null); constructor() { - // Initialize provider ID from localStorage this.updateProviderIdFromStorage(); } /** * Get the current access token from localStorage. - * @returns The access token or null if not found */ getAccessToken(): string | null { return localStorage.getItem(this.tokenKey); @@ -67,7 +55,6 @@ export class AuthService { /** * Get the refresh token from localStorage. - * @returns The refresh token or null if not found */ getRefreshToken(): string | null { return localStorage.getItem(this.refreshTokenKey); @@ -76,12 +63,11 @@ export class AuthService { /** * Check if the current access token is expired or will expire soon. * @param bufferSeconds Buffer time in seconds before expiry to consider token expired (default: 60) - * @returns True if token is expired or will expire soon */ isTokenExpired(bufferSeconds: number = 60): boolean { const expiryStr = localStorage.getItem(this.tokenExpiryKey); if (!expiryStr) { - return true; // No expiry info means expired + return true; } const expiryTime = parseInt(expiryStr, 10); @@ -93,7 +79,6 @@ export class AuthService { /** * Check if user is authenticated (has a valid token). - * @returns True if user has a token that is not expired */ isAuthenticated(): boolean { const token = this.getAccessToken(); @@ -103,9 +88,151 @@ export class AuthService { return !this.isTokenExpired(); } + // ─── PKCE Helpers ─────────────────────────────────────────────────── + + /** + * Generate a cryptographically random code verifier (43-128 chars) for PKCE. + */ + private generateCodeVerifier(): string { + const array = new Uint8Array(32); + crypto.getRandomValues(array); + return this.base64UrlEncode(array); + } + + /** + * Generate a SHA-256 code challenge from the code verifier for PKCE. + */ + private async generateCodeChallenge(verifier: string): Promise { + const encoder = new TextEncoder(); + const data = encoder.encode(verifier); + const digest = await crypto.subtle.digest('SHA-256', data); + return this.base64UrlEncode(new Uint8Array(digest)); + } + + /** + * Generate a random state string for CSRF protection. + */ + private generateRandomState(): string { + const array = new Uint8Array(32); + crypto.getRandomValues(array); + return this.base64UrlEncode(array); + } + + /** + * Base64url encode a Uint8Array (no padding, URL-safe). + */ + private base64UrlEncode(buffer: Uint8Array): string { + let binary = ''; + for (let i = 0; i < buffer.length; i++) { + binary += String.fromCharCode(buffer[i]); + } + return btoa(binary) + .replace(/\+/g, '-') + .replace(/\//g, '_') + .replace(/=+$/, ''); + } + + // ─── Login ─────────────────────────────────────────────────────────── + + /** + * Initiates the Cognito OAuth 2.0 login flow with PKCE. + * Redirects the user to the Cognito authorize endpoint. + * + * @param providerId Optional Cognito identity provider name for federated login + */ + async login(providerId?: string): Promise { + const state = this.generateRandomState(); + const codeVerifier = this.generateCodeVerifier(); + const codeChallenge = await this.generateCodeChallenge(codeVerifier); + + // Store PKCE and state values in sessionStorage + sessionStorage.setItem(this.stateKey, state); + sessionStorage.setItem(this.codeVerifierKey, codeVerifier); + + // Store provider ID in localStorage for display purposes + if (providerId) { + localStorage.setItem(this.providerIdKey, providerId); + } + + const params = new URLSearchParams({ + response_type: 'code', + client_id: this.cognitoClientId(), + redirect_uri: this.redirectUri, + scope: 'openid profile email', + state, + code_challenge: codeChallenge, + code_challenge_method: 'S256', + }); + + // If a specific federated provider is selected, add identity_provider param + if (providerId) { + params.set('identity_provider', providerId); + } + + window.location.href = `${this.cognitoDomain()}/oauth2/authorize?${params}`; + } + + // ─── Callback / Token Exchange ────────────────────────────────────── + + /** + * Handles the OAuth 2.0 callback by exchanging the authorization code + * for Cognito tokens directly via the Cognito token endpoint. + * + * @param code Authorization code from Cognito + * @param state State parameter for CSRF verification + */ + async handleCallback(code: string, state: string): Promise { + // Verify state matches for CSRF protection + const storedState = sessionStorage.getItem(this.stateKey); + if (state !== storedState) { + this.clearStoredState(); + throw new Error('State mismatch. Security validation failed. Please try logging in again.'); + } + + const codeVerifier = sessionStorage.getItem(this.codeVerifierKey); + if (!codeVerifier) { + this.clearStoredState(); + throw new Error('No code verifier found. Please initiate login again.'); + } + + // Exchange code for tokens directly with Cognito + const response = await fetch(`${this.cognitoDomain()}/oauth2/token`, { + method: 'POST', + headers: { 'Content-Type': 'application/x-www-form-urlencoded' }, + body: new URLSearchParams({ + grant_type: 'authorization_code', + client_id: this.cognitoClientId(), + code, + redirect_uri: this.redirectUri, + code_verifier: codeVerifier, + }), + }); + + if (!response.ok) { + this.clearStoredState(); + const errorBody = await response.text(); + throw new Error(`Token exchange failed: ${errorBody}`); + } + + const tokens: TokenRefreshResponse = await response.json(); + + if (!tokens || !tokens.access_token) { + this.clearStoredState(); + throw new Error('Invalid token response from Cognito'); + } + + // Store tokens + this.storeTokens(tokens); + + // Clean up session storage + this.clearStoredState(); + sessionStorage.removeItem(this.codeVerifierKey); + } + + // ─── Token Refresh ─────────────────────────────────────────────────── + /** - * Refresh the access token using the refresh token. - * @returns Promise resolving to the new token response + * Refresh the access token using the refresh token via the Cognito token endpoint. */ async refreshAccessToken(): Promise { const refreshToken = this.getRefreshToken(); @@ -114,48 +241,53 @@ export class AuthService { } try { - const request: TokenRefreshRequest = { - refresh_token: refreshToken - }; - - const providerId = this.getStoredProviderId(); - const refreshParams = new URLSearchParams(); - if (providerId) { - refreshParams.set('provider_id', providerId); + const response = await fetch(`${this.cognitoDomain()}/oauth2/token`, { + method: 'POST', + headers: { 'Content-Type': 'application/x-www-form-urlencoded' }, + body: new URLSearchParams({ + grant_type: 'refresh_token', + client_id: this.cognitoClientId(), + refresh_token: refreshToken, + }), + }); + + if (!response.ok) { + // On 400/401 from Cognito, the refresh token is invalid — clear tokens + if (response.status === 400 || response.status === 401) { + this.clearTokens(); + } + const errorBody = await response.text(); + throw new Error(`Token refresh failed: ${errorBody}`); } - const refreshQuery = refreshParams.toString(); - const refreshUrl = `${this.baseUrl()}/auth/refresh${refreshQuery ? `?${refreshQuery}` : ''}`; - const response = await firstValueFrom( - this.http.post(refreshUrl, request) - ); + const tokens: TokenRefreshResponse = await response.json(); - if (!response || !response.access_token) { + if (!tokens || !tokens.access_token) { throw new Error('Invalid token refresh response'); } - // Store the new tokens - this.storeTokens(response); + // Store the new tokens (Cognito refresh_token grant doesn't return a new refresh_token, + // so we preserve the existing one) + this.storeTokens(tokens); - return response; + return tokens; } catch (error) { - // Only clear tokens on explicit 401 (invalid refresh token). - // Transient errors (network failures, 5xx, HTML parse errors) should - // not destroy a potentially valid session. - if (error instanceof HttpErrorResponse && error.status === 401) { - this.clearTokens(); - } throw error; } } + // ─── Token Storage ────────────────────────────────────────────────── + /** * Store tokens in localStorage. - * @param response Token response containing access_token, refresh_token, and expires_in */ - storeTokens(response: { access_token: string; refresh_token?: string; expires_in: number }): void { + storeTokens(response: { access_token: string; refresh_token?: string; id_token?: string; expires_in: number }): void { localStorage.setItem(this.tokenKey, response.access_token); + if (response.id_token) { + localStorage.setItem(this.idTokenKey, response.id_token); + } + if (response.refresh_token) { localStorage.setItem(this.refreshTokenKey, response.refresh_token); } @@ -180,14 +312,13 @@ export class AuthService { */ clearTokens(): void { localStorage.removeItem(this.tokenKey); + localStorage.removeItem(this.idTokenKey); localStorage.removeItem(this.refreshTokenKey); localStorage.removeItem(this.tokenExpiryKey); localStorage.removeItem(this.providerIdKey); - // Clear provider ID signal this.currentProviderId.set(null); - // Dispatch custom event to notify UserService of token removal in same tab if (typeof window !== 'undefined') { window.dispatchEvent(new CustomEvent('token-cleared')); } @@ -195,7 +326,6 @@ export class AuthService { /** * Get the Authorization header value. - * @returns Bearer token string or null */ getAuthorizationHeader(): string | null { const token = this.getAccessToken(); @@ -203,76 +333,24 @@ export class AuthService { } /** - * Update provider ID from localStorage or clear it. - * The provider ID is set during login and used for routing logout/refresh requests. - * Stored in localStorage (not sessionStorage) so it persists across tabs and - * browser restarts, matching the lifetime of the tokens it's used with. + * Get the stored ID token. Contains user profile claims (email, name, groups). */ - private updateProviderIdFromStorage(): void { - const storedProviderId = this.getStoredProviderId(); - this.currentProviderId.set(storedProviderId); + getIdToken(): string | null { + return localStorage.getItem(this.idTokenKey); } + // ─── State / Return URL / Provider ID ──────────────────────────────── + /** - * Initiates the OIDC login flow by calling the backend login endpoint - * and redirecting the user to the IdP for authentication. - * - * Stores the state token in sessionStorage for CSRF protection and - * the provider ID in localStorage for multi-provider routing. - * - * @param providerId Optional auth provider ID for multi-provider support - * @param redirectUri Optional redirect URI override - * @param prompt Optional prompt parameter (defaults to "select_account") - * @throws Error if login initiation fails + * Update provider ID from localStorage. */ - async login(providerId?: string, redirectUri?: string, prompt: string = 'select_account'): Promise { - try { - // Build query parameters - const params = new URLSearchParams(); - if (providerId) { - params.set('provider_id', providerId); - } - if (redirectUri) { - params.set('redirect_uri', redirectUri); - } - params.set('prompt', prompt); - - const queryString = params.toString(); - const url = `${this.baseUrl()}/auth/login${queryString ? `?${queryString}` : ''}`; - - const response = await firstValueFrom( - this.http.get(url) - ); - - if (!response || !response.authorization_url || !response.state) { - throw new Error('Invalid login response'); - } - - // Store state token in sessionStorage for CSRF protection - sessionStorage.setItem(this.stateKey, response.state); - - // Store provider ID in localStorage for refresh/logout routing - // (must persist across tabs/restarts to match token lifetime) - if (providerId) { - localStorage.setItem(this.providerIdKey, providerId); - } - - // Redirect to authorization URL - window.location.href = response.authorization_url; - } catch (error) { - // Clear any stored state on error - sessionStorage.removeItem(this.stateKey); - - if (error instanceof Error) { - throw error; - } - throw new Error('Failed to initiate login'); - } + private updateProviderIdFromStorage(): void { + const storedProviderId = this.getStoredProviderId(); + this.currentProviderId.set(storedProviderId); } /** * Get the stored state token from sessionStorage. - * @returns The state token or null if not found */ getStoredState(): string | null { return sessionStorage.getItem(this.stateKey); @@ -287,7 +365,6 @@ export class AuthService { /** * Get the stored return URL from sessionStorage. - * @returns The return URL or null if not found */ getStoredReturnUrl(): string | null { return sessionStorage.getItem(this.returnUrlKey); @@ -302,7 +379,6 @@ export class AuthService { /** * Get the stored provider ID from localStorage. - * Used to route refresh and logout requests to the correct provider. */ getStoredProviderId(): string | null { return localStorage.getItem(this.providerIdKey); @@ -310,110 +386,60 @@ export class AuthService { /** * Get the current provider ID from the signal. - * This is extracted from the JWT token or retrieved from localStorage. - * @returns The current provider ID or null if not available */ getProviderId(): string | null { return this.currentProviderId(); } + // ─── Ensure Authenticated ────────────────────────────────────────── + /** * Ensures the user is authenticated before making an HTTP request. - * Attempts to refresh the token if expired, throws an error if authentication fails. - * - * This is a reusable utility for resource loaders and other async operations - * that require authentication before proceeding. - * - * @throws Error if user is not authenticated and token refresh fails - * @returns Promise that resolves when user is authenticated - * - * @example - * ```typescript - * // In a resource loader - * readonly myResource = resource({ - * loader: async () => { - * await this.authService.ensureAuthenticated(); - * return this.http.get('/api/data').toPromise(); - * } - * }); - * ``` + * Attempts to refresh the token if expired. */ async ensureAuthenticated(): Promise { - // Check if user is authenticated if (this.isAuthenticated()) { - return; // User is authenticated, proceed + return; } - // If not authenticated, try to refresh token if expired const token = this.getAccessToken(); if (token && this.isTokenExpired()) { try { await this.refreshAccessToken(); - // Verify authentication after refresh if (this.isAuthenticated()) { - return; // Refresh successful, proceed + return; } } catch (error) { - // Refresh failed, throw authentication error throw new Error('User is not authenticated. Please login again.'); } } - // No token or refresh failed, throw error throw new Error('User is not authenticated. Please login.'); } + // ─── Logout ───────────────────────────────────────────────────────── + /** * Logs the user out by clearing local tokens and redirecting to the - * IdP's logout endpoint. - * - * This performs a complete logout: - * 1. Clears all local tokens from localStorage - * 2. Fetches the IdP logout URL from the backend - * 3. Redirects the user to the IdP to end the session - * - * @param postLogoutRedirectUri Optional URL to redirect to after IdP logout - * @throws Error if logout initiation fails + * Cognito logout endpoint. */ - async logout(postLogoutRedirectUri?: string): Promise { - try { - // Build query parameters - const params = new URLSearchParams(); - const providerId = this.getStoredProviderId(); - if (providerId) { - params.set('provider_id', providerId); - } - if (postLogoutRedirectUri) { - params.set('post_logout_redirect_uri', postLogoutRedirectUri); - } - - const queryString = params.toString(); - const url = `${this.baseUrl()}/auth/logout${queryString ? `?${queryString}` : ''}`; - - const response = await firstValueFrom( - this.http.get(url) - ); - - if (!response || !response.logout_url) { - throw new Error('Invalid logout response'); - } - - // Clear local tokens first - this.clearTokens(); - - // Redirect to IdP logout - window.location.href = response.logout_url; - } catch (error) { - // On error, still clear tokens and redirect to home - this.clearTokens(); - - if (error instanceof Error) { - console.error('Logout error:', error.message); - } - - // Redirect to home page as fallback + async logout(): Promise { + // Clear local tokens first + this.clearTokens(); + + const cognitoDomain = this.cognitoDomain(); + const clientId = this.cognitoClientId(); + + if (cognitoDomain && clientId) { + // Redirect to Cognito logout endpoint + const params = new URLSearchParams({ + client_id: clientId, + logout_uri: this.logoutUri, + }); + window.location.href = `${cognitoDomain}/logout?${params}`; + } else { + // Fallback: redirect to home if Cognito config not available window.location.href = '/'; } } } - diff --git a/frontend/ai.client/src/app/auth/callback/callback.page.ts b/frontend/ai.client/src/app/auth/callback/callback.page.ts index 7c67f560..14fd5741 100644 --- a/frontend/ai.client/src/app/auth/callback/callback.page.ts +++ b/frontend/ai.client/src/app/auth/callback/callback.page.ts @@ -29,7 +29,6 @@ export class CallbackPage implements OnInit { const queryParams = this.route.snapshot.queryParams; const code = queryParams['code']; const state = queryParams['state']; - const redirectUri = queryParams['redirect_uri']; // Validate required parameters if (!code || !state) { @@ -41,7 +40,7 @@ export class CallbackPage implements OnInit { // Exchange code for tokens this.statusMessage.set('Exchanging authorization code for tokens...'); - await this.callbackService.exchangeCodeForTokens(code, state, redirectUri); + await this.callbackService.exchangeCodeForTokens(code, state); // Success - redirect to return URL or home this.statusMessage.set('Authentication successful! Redirecting...'); diff --git a/frontend/ai.client/src/app/auth/callback/callback.service.spec.ts b/frontend/ai.client/src/app/auth/callback/callback.service.spec.ts index 5c93a63d..ff7e8989 100644 --- a/frontend/ai.client/src/app/auth/callback/callback.service.spec.ts +++ b/frontend/ai.client/src/app/auth/callback/callback.service.spec.ts @@ -1,131 +1,66 @@ -import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest'; +import { describe, it, expect, beforeEach, vi } from 'vitest'; import { TestBed } from '@angular/core/testing'; -import { HttpClientTestingModule, HttpTestingController } from '@angular/common/http/testing'; -import { CallbackService, TokenExchangeResponse } from './callback.service'; +import { CallbackService } from './callback.service'; import { AuthService } from '../auth.service'; import { UserService } from '../user.service'; import { SessionService } from '../../session/services/session/session.service'; -import { ConfigService } from '../../services/config.service'; describe('CallbackService', () => { let service: CallbackService; - let httpMock: HttpTestingController; let mockAuthService: any; let mockUserService: any; let mockSessionService: any; - let mockConfigService: any; beforeEach(() => { TestBed.resetTestingModule(); + mockAuthService = { - getStoredState: vi.fn(), - clearStoredState: vi.fn(), - storeTokens: vi.fn() + handleCallback: vi.fn().mockResolvedValue(undefined), }; mockUserService = { refreshUser: vi.fn(), - ensurePermissionsLoaded: vi.fn().mockResolvedValue(undefined) + ensurePermissionsLoaded: vi.fn().mockResolvedValue(undefined), }; mockSessionService = { - enableSessionsLoading: vi.fn() - }; - - mockConfigService = { - appApiUrl: vi.fn(() => 'http://localhost:8000') + enableSessionsLoading: vi.fn(), }; TestBed.configureTestingModule({ - imports: [HttpClientTestingModule], providers: [ CallbackService, { provide: AuthService, useValue: mockAuthService }, { provide: UserService, useValue: mockUserService }, { provide: SessionService, useValue: mockSessionService }, - { provide: ConfigService, useValue: mockConfigService } - ] + ], }); service = TestBed.inject(CallbackService); - httpMock = TestBed.inject(HttpTestingController); - }); - - afterEach(() => { - TestBed.resetTestingModule(); - httpMock.match(() => true); - vi.clearAllMocks(); }); describe('exchangeCodeForTokens', () => { - const mockResponse: TokenExchangeResponse = { - access_token: 'test-access-token', - refresh_token: 'test-refresh-token', - token_type: 'Bearer', - expires_in: 3600 - }; - - it('should exchange code for tokens successfully', async () => { - const code = 'test-code'; - const state = 'test-state'; - - mockAuthService.getStoredState.mockReturnValue(state); - - const promise = service.exchangeCodeForTokens(code, state); - - const req = httpMock.expectOne('http://localhost:8000/auth/token'); - expect(req.request.method).toBe('POST'); - expect(req.request.body).toEqual({ code, state }); + it('should delegate to AuthService.handleCallback and refresh user', async () => { + await service.exchangeCodeForTokens('test-code', 'test-state'); - req.flush(mockResponse); - - const result = await promise; - - expect(result).toEqual(mockResponse); - expect(mockAuthService.storeTokens).toHaveBeenCalledWith(mockResponse); + expect(mockAuthService.handleCallback).toHaveBeenCalledWith('test-code', 'test-state'); expect(mockUserService.refreshUser).toHaveBeenCalled(); + expect(mockUserService.ensurePermissionsLoaded).toHaveBeenCalled(); expect(mockSessionService.enableSessionsLoading).toHaveBeenCalled(); - expect(mockAuthService.clearStoredState).toHaveBeenCalled(); }); - it('should throw error when state mismatch', async () => { - const code = 'test-code'; - const state = 'test-state'; - - mockAuthService.getStoredState.mockReturnValue('different-state'); - - await expect(service.exchangeCodeForTokens(code, state)) - .rejects.toThrow('State token mismatch. Security validation failed. Please try logging in again.'); + it('should propagate errors from AuthService.handleCallback', async () => { + mockAuthService.handleCallback.mockRejectedValue(new Error('State mismatch')); - expect(mockAuthService.clearStoredState).toHaveBeenCalled(); - httpMock.expectNone('http://localhost:8000/auth/token'); + await expect(service.exchangeCodeForTokens('code', 'bad-state')) + .rejects.toThrow('State mismatch'); }); - it('should throw error when missing state', async () => { - const code = 'test-code'; - const state = 'test-state'; - - mockAuthService.getStoredState.mockReturnValue(null); - - await expect(service.exchangeCodeForTokens(code, state)) - .rejects.toThrow('No state token found. Please initiate login again.'); - - httpMock.expectNone('http://localhost:8000/auth/token'); - }); - - it('should handle HTTP error', async () => { - const code = 'test-code'; - const state = 'test-state'; - - mockAuthService.getStoredState.mockReturnValue(state); - - const promise = service.exchangeCodeForTokens(code, state); - - const req = httpMock.expectOne('http://localhost:8000/auth/token'); - req.error(new ProgressEvent('Network error')); + it('should propagate errors from permissions loading', async () => { + mockUserService.ensurePermissionsLoaded.mockRejectedValue(new Error('Permissions failed')); - await expect(promise).rejects.toThrow(); - expect(mockAuthService.clearStoredState).toHaveBeenCalled(); + await expect(service.exchangeCodeForTokens('code', 'state')) + .rejects.toThrow('Permissions failed'); }); }); -}); \ No newline at end of file +}); diff --git a/frontend/ai.client/src/app/auth/callback/callback.service.ts b/frontend/ai.client/src/app/auth/callback/callback.service.ts index 9ce29e43..420ac6a4 100644 --- a/frontend/ai.client/src/app/auth/callback/callback.service.ts +++ b/frontend/ai.client/src/app/auth/callback/callback.service.ts @@ -1,87 +1,31 @@ import { inject, Injectable } from '@angular/core'; -import { HttpClient } from '@angular/common/http'; -import { firstValueFrom } from 'rxjs'; import { AuthService } from '../auth.service'; import { UserService } from '../user.service'; import { SessionService } from '../../session/services/session/session.service'; -import { ConfigService } from '../../services/config.service'; - -export interface TokenExchangeRequest { - code: string; - state: string; - redirect_uri?: string; -} - -export interface TokenExchangeResponse { - access_token: string; - refresh_token?: string; - id_token?: string; - token_type: string; - expires_in: number; - scope?: string; -} @Injectable({ providedIn: 'root' }) export class CallbackService { - private http = inject(HttpClient); private authService = inject(AuthService); private userService = inject(UserService); private sessionService = inject(SessionService); - private config = inject(ConfigService); - - async exchangeCodeForTokens(code: string, state: string, redirectUri?: string): Promise { - // Retrieve stored state token from sessionStorage for CSRF validation - const storedState = this.authService.getStoredState(); - - if (!storedState) { - throw new Error('No state token found. Please initiate login again.'); - } - - // Validate state token matches (CSRF protection) - if (storedState !== state) { - // Clear stored state on mismatch - this.authService.clearStoredState(); - throw new Error('State token mismatch. Security validation failed. Please try logging in again.'); - } - const request: TokenExchangeRequest = { - code, - state, - ...(redirectUri && { redirect_uri: redirectUri }) - }; + /** + * Exchange authorization code for tokens via Cognito token endpoint. + * Delegates to AuthService.handleCallback() for the actual token exchange. + */ + async exchangeCodeForTokens(code: string, state: string): Promise { + // Exchange code for tokens directly with Cognito via AuthService + await this.authService.handleCallback(code, state); - try { - const response = await firstValueFrom( - this.http.post(`${this.config.appApiUrl()}/auth/token`, request) - ); + // Refresh user data from new token + this.userService.refreshUser(); - if (!response || !response.access_token) { - throw new Error('Invalid token response'); - } + // Ensure resolved permissions are available before navigating + await this.userService.ensurePermissionsLoaded(); - // Store tokens using AuthService - this.authService.storeTokens(response); - - // Refresh user data from new token - this.userService.refreshUser(); - - // Ensure resolved permissions are available before navigating - await this.userService.ensurePermissionsLoaded(); - - // Enable sessions loading now that user is authenticated - this.sessionService.enableSessionsLoading(); - - // Clear state token after successful exchange - this.authService.clearStoredState(); - - return response; - } catch (error) { - // Clear state token on error - this.authService.clearStoredState(); - throw error; - } + // Enable sessions loading now that user is authenticated + this.sessionService.enableSessionsLoading(); } } - diff --git a/frontend/ai.client/src/app/auth/first-boot.guard.ts b/frontend/ai.client/src/app/auth/first-boot.guard.ts new file mode 100644 index 00000000..120cff28 --- /dev/null +++ b/frontend/ai.client/src/app/auth/first-boot.guard.ts @@ -0,0 +1,23 @@ +import { inject } from '@angular/core'; +import { Router, CanActivateFn } from '@angular/router'; +import { SystemService } from '../services/system.service'; + +/** + * Route guard for the first-boot page. + * + * Allows access only when first-boot has NOT been completed. + * If first-boot is already done, redirects to /auth/login. + */ +export const firstBootGuard: CanActivateFn = async () => { + const systemService = inject(SystemService); + const router = inject(Router); + + const completed = await systemService.checkStatus(); + + if (completed) { + router.navigate(['/auth/login']); + return false; + } + + return true; +}; diff --git a/frontend/ai.client/src/app/auth/first-boot/first-boot.page.css b/frontend/ai.client/src/app/auth/first-boot/first-boot.page.css new file mode 100644 index 00000000..72609321 --- /dev/null +++ b/frontend/ai.client/src/app/auth/first-boot/first-boot.page.css @@ -0,0 +1,5 @@ +/* First-boot page specific styles */ + +@import "tailwindcss"; + +@custom-variant dark (&:where(.dark, .dark *)); diff --git a/frontend/ai.client/src/app/auth/first-boot/first-boot.page.ts b/frontend/ai.client/src/app/auth/first-boot/first-boot.page.ts new file mode 100644 index 00000000..4c8f81e7 --- /dev/null +++ b/frontend/ai.client/src/app/auth/first-boot/first-boot.page.ts @@ -0,0 +1,315 @@ +import { Component, signal, ChangeDetectionStrategy, inject, OnInit, OnDestroy } from '@angular/core'; +import { CommonModule } from '@angular/common'; +import { ReactiveFormsModule, FormBuilder, FormGroup, Validators, AbstractControl, ValidationErrors } from '@angular/forms'; +import { Router } from '@angular/router'; +import { SidenavService } from '../../services/sidenav/sidenav.service'; +import { SystemService, FirstBootError } from '../../services/system.service'; + +@Component({ + selector: 'app-first-boot', + imports: [CommonModule, ReactiveFormsModule], + styleUrl: './first-boot.page.css', + changeDetection: ChangeDetectionStrategy.OnPush, + template: ` +
+
+ +
+ Logo + +
+ +
+
+
+

+ Welcome +

+

+ Create your admin account to get started +

+
+ + + @if (successMessage()) { +
+
+ +

+ {{ successMessage() }} +

+
+
+ } + + + @if (errorMessage()) { + + } + + + @if (!successMessage()) { +
+ +
+ + + @if (form.get('username')?.touched && form.get('username')?.errors) { +

+ @if (form.get('username')?.errors?.['required']) { + Username is required + } @else if (form.get('username')?.errors?.['minlength']) { + Username must be at least 3 characters + } +

+ } +
+ + +
+ + + @if (form.get('email')?.touched && form.get('email')?.errors) { +

+ @if (form.get('email')?.errors?.['required']) { + Email is required + } @else if (form.get('email')?.errors?.['email']) { + Please enter a valid email address + } +

+ } +
+ + +
+ + + @if (form.get('password')?.touched && form.get('password')?.errors) { +

+ @if (form.get('password')?.errors?.['required']) { + Password is required + } @else if (form.get('password')?.errors?.['passwordStrength']) { + {{ form.get('password')?.errors?.['passwordStrength'] }} + } +

+ } + + +
    +
  • • At least 8 characters
    • +
  • • One uppercase letter
    • +
  • • One lowercase letter
    • +
  • • One digit
    • +
  • • One special character
    • +
+
+ + +
+ + + @if (form.get('confirmPassword')?.touched && form.get('confirmPassword')?.errors) { +

+ @if (form.get('confirmPassword')?.errors?.['required']) { + Please confirm your password + } @else if (form.get('confirmPassword')?.errors?.['passwordMismatch']) { + Passwords do not match + } +

+ } +
+ + + +
+ } +
+
+
+
+ ` +}) +export class FirstBootPage implements OnInit, OnDestroy { + private readonly sidenavService = inject(SidenavService); + private readonly systemService = inject(SystemService); + private readonly router = inject(Router); + private readonly fb = inject(FormBuilder); + + isSubmitting = signal(false); + errorMessage = signal(null); + successMessage = signal(null); + + form: FormGroup = this.fb.group({ + username: ['', [Validators.required, Validators.minLength(3)]], + email: ['', [Validators.required, Validators.email]], + password: ['', [Validators.required, this.passwordStrengthValidator]], + confirmPassword: ['', [Validators.required]], + }, { validators: this.passwordMatchValidator }); + + ngOnInit(): void { + this.sidenavService.hide(); + this.checkFirstBootStatus(); + } + + ngOnDestroy(): void { + this.sidenavService.show(); + } + + private async checkFirstBootStatus(): Promise { + try { + const completed = await this.systemService.checkStatus(); + if (completed) { + this.router.navigate(['/auth/login']); + } + } catch { + // If status check fails, stay on the page — user can still try to submit + } + } + + // ─── Password Requirement Helpers ────────────────────────────────── + + get passwordValue(): string { + return this.form.get('password')?.value || ''; + } + + passwordMeetsLength(): boolean { + return this.passwordValue.length >= 8; + } + + passwordHasUppercase(): boolean { + return /[A-Z]/.test(this.passwordValue); + } + + passwordHasLowercase(): boolean { + return /[a-z]/.test(this.passwordValue); + } + + passwordHasDigit(): boolean { + return /\d/.test(this.passwordValue); + } + + passwordHasSymbol(): boolean { + return /[^A-Za-z0-9]/.test(this.passwordValue); + } + + // ─── Validators ──────────────────────────────────────────────────── + + private passwordStrengthValidator(control: AbstractControl): ValidationErrors | null { + const value = control.value; + if (!value) return null; + + const errors: string[] = []; + if (value.length < 8) errors.push('at least 8 characters'); + if (!/[A-Z]/.test(value)) errors.push('one uppercase letter'); + if (!/[a-z]/.test(value)) errors.push('one lowercase letter'); + if (!/\d/.test(value)) errors.push('one digit'); + if (!/[^A-Za-z0-9]/.test(value)) errors.push('one special character'); + + return errors.length > 0 + ? { passwordStrength: `Password must contain ${errors.join(', ')}` } + : null; + } + + private passwordMatchValidator(group: AbstractControl): ValidationErrors | null { + const password = group.get('password')?.value; + const confirm = group.get('confirmPassword')?.value; + + if (confirm && password !== confirm) { + group.get('confirmPassword')?.setErrors({ passwordMismatch: true }); + return { passwordMismatch: true }; + } + return null; + } + + // ─── Submit ──────────────────────────────────────────────────────── + + async onSubmit(): Promise { + if (this.form.invalid || this.isSubmitting()) return; + + this.isSubmitting.set(true); + this.errorMessage.set(null); + + const { username, email, password } = this.form.value; + + try { + await this.systemService.firstBoot(username, email, password); + this.successMessage.set('Admin account created successfully. Redirecting to login...'); + + // Redirect to login after a short delay + setTimeout(() => { + this.router.navigate(['/auth/login']); + }, 2000); + } catch (error) { + if (error instanceof FirstBootError) { + if (error.statusCode === 409) { + this.errorMessage.set('First-boot setup has already been completed. Redirecting to login...'); + setTimeout(() => this.router.navigate(['/auth/login']), 2000); + } else if (error.statusCode === 400) { + this.errorMessage.set(error.message); + } else { + this.errorMessage.set(error.message); + } + } else { + this.errorMessage.set('An unexpected error occurred. Please try again.'); + } + } finally { + this.isSubmitting.set(false); + } + } +} diff --git a/frontend/ai.client/src/app/auth/index.ts b/frontend/ai.client/src/app/auth/index.ts index 46f34589..8e11b385 100644 --- a/frontend/ai.client/src/app/auth/index.ts +++ b/frontend/ai.client/src/app/auth/index.ts @@ -1,5 +1,4 @@ export * from './auth.service'; -export * from './auth-api.service'; export * from './auth.interceptor'; export * from './user.service'; export * from './user.model'; diff --git a/frontend/ai.client/src/app/auth/login/login.page.ts b/frontend/ai.client/src/app/auth/login/login.page.ts index 2a3c8dd9..69e292bd 100644 --- a/frontend/ai.client/src/app/auth/login/login.page.ts +++ b/frontend/ai.client/src/app/auth/login/login.page.ts @@ -1,11 +1,12 @@ import { Component, signal, ChangeDetectionStrategy, inject, OnInit, OnDestroy } from '@angular/core'; import { CommonModule } from '@angular/common'; import { HttpClient } from '@angular/common/http'; -import { ActivatedRoute } from '@angular/router'; +import { ActivatedRoute, Router } from '@angular/router'; import { firstValueFrom } from 'rxjs'; import { AuthService } from '../auth.service'; import { SidenavService } from '../../services/sidenav/sidenav.service'; import { ConfigService } from '../../services/config.service'; +import { SystemService } from '../../services/system.service'; interface AuthProviderPublicInfo { provider_id: string; @@ -25,10 +26,7 @@ interface AuthProviderPublicListResponse { changeDetection: ChangeDetectionStrategy.OnPush, template: `
- -
+
- - @if (!providersLoading() && providers().length > 0) { -
-
-
-

- Sign In -

-

- @if (providers().length > 1) { - Choose an authentication provider to continue - } @else { - Sign in to continue - } -

+
+
+
+

+ Sign In +

+

+ Sign in to continue +

+
+ + @if (errorMessage()) { + + } + + +
+ + - @if (errorMessage()) { - - } - - - @if (providersLoading()) { -
-
-
- Loading authentication providers -
-
-
- } - - - @if (!providersLoading() && providers().length === 0) { -
-
- -
-
- -
-

- Authentication Not Configured -

-

- No OIDC authentication providers have been set up yet. An administrator needs to seed an initial provider before users can sign in. -

-
- -
- - -
-

- Setup Instructions -

- - -
- -
-

Register an OIDC application with your Identity Provider

-

- Create an app registration in your IdP (e.g., Entra ID, Okta, Auth0, AWS Cognito). You will need: -

-
    -
  • - Issuer URL — the OIDC issuer for your IdP -
      -
    • Entra ID: https://login.microsoftonline.com/{tenant-id}/v2.0
      • -
    • Cognito: https://cognito-idp.{region}.amazonaws.com/{user-pool-id}
      • -
    • Okta: https://{domain}.okta.com/oauth2/default
      • -
    -
    • -
  • Client ID — the OIDC application/client identifier
    • -
  • Client Secret — the OIDC client secret
    • -
-
-
- - -
- -
-

Ensure AWS resources are deployed

-

- The CDK AppApiStack creates the DynamoDB auth providers table and Secrets Manager secret. You can find these values in the CDK stack outputs or in the AWS Console: -

-
    -
  • DynamoDB Table Name — the auth-providers table name
    • -
  • Secrets Manager ARN — the secret ARN for provider client secrets
    • -
-
-
- - -
- -
-

Run the seed script

-

- From the project root, run: -

-
- 
python backend/scripts/seed_auth_provider.py \
-  --provider-id my-provider \
-  --display-name "My Provider" \
-  --issuer-url "https://..." \
-  --client-id "your-client-id" \
-  --client-secret "your-secret" \
-  --discover \
-  --table-name auth-providers \
-  --secrets-arn "arn:aws:secretsmanager:..."
-
-

- Use --discover to auto-detect OIDC endpoints from the issuer URL. Run with no flags for interactive mode. -

-
-
+ } - -
- -
-

Configure environment & restart

-

- The following environment variables must be available to the backend service. For deployed environments, these are set automatically via CDK and SSM parameters. For local development, add them to your .env file: -

-
    -
  • - DYNAMODB_AUTH_PROVIDERS_TABLE_NAME - — set via CDK/SSM on deploy; only needed in .env for local dev -
    • -
  • - AUTH_PROVIDER_SECRETS_ARN - — set via CDK/SSM on deploy; only needed in .env for local dev -
    • -
  • - SEED_ADMIN_JWT_ROLE=YourAdminRole - — set via the bootstrap seed script to map a JWT role to the system_admin AppRole. Must match a role your IdP issues in the token’s roles claim. The first user who logs in with this role can then manage providers, models, and roles from the admin dashboard. -
    • -
-

- After configuring, restart the backend service and refresh this page. -

+ + @if (providersLoading()) { +
+
+ Loading federated providers
-
- -
- - -
- - - Optional seed script flags - -
-
- --scopes - OIDC scopes (default: openid profile email) - --pkce-enabled - Enable PKCE (default: true) - --redirect-uri - Override redirect URI - --user-id-claim - JWT claim for user ID (default: sub) - --roles-claim - JWT claim for roles (default: roles) - --button-color - Hex color for login button (e.g., #0078D4) - --logo-url - URL to provider logo for login button - --dry-run - Preview changes without writing to AWS -
-
-
+ }
+ +

+ You will be redirected to complete authentication +

- } +
` @@ -279,6 +146,8 @@ export class LoginPage implements OnInit, OnDestroy { private config = inject(ConfigService); private http = inject(HttpClient); private route = inject(ActivatedRoute); + private router = inject(Router); + private systemService = inject(SystemService); isLoading = signal(false); errorMessage = signal(null); @@ -288,6 +157,7 @@ export class LoginPage implements OnInit, OnDestroy { ngOnInit(): void { this.sidenavService.hide(); + this.checkFirstBootStatus(); this.loadProviders(); } @@ -295,6 +165,17 @@ export class LoginPage implements OnInit, OnDestroy { this.sidenavService.show(); } + private async checkFirstBootStatus(): Promise { + try { + const completed = await this.systemService.checkStatus(); + if (!completed) { + this.router.navigate(['/auth/first-boot']); + } + } catch { + // If status check fails, stay on login page + } + } + private async loadProviders(): Promise { try { const url = `${this.config.appApiUrl()}/auth/providers`; @@ -302,21 +183,30 @@ export class LoginPage implements OnInit, OnDestroy { this.http.get(url) ); - const providerList = response?.providers ?? []; - this.providers.set(providerList); - - // Auto-login if exactly one provider (skip selection screen) - if (providerList.length === 1) { - this.storeReturnUrl(); - await this.authService.login(providerList[0].provider_id); - } + this.providers.set(response?.providers ?? []); } catch (error) { + // Federated providers failed to load — Cognito button still works this.providers.set([]); } finally { this.providersLoading.set(false); } } + async handleCognitoLogin(): Promise { + this.isLoading.set(true); + this.activeProviderId.set(null); + this.errorMessage.set(null); + + try { + this.storeReturnUrl(); + await this.authService.login(); + } catch (error) { + this.isLoading.set(false); + const errorMsg = error instanceof Error ? error.message : 'An error occurred during login'; + this.errorMessage.set(errorMsg); + } + } + async handleProviderLogin(provider: AuthProviderPublicInfo): Promise { this.isLoading.set(true); this.activeProviderId.set(provider.provider_id); diff --git a/frontend/ai.client/src/app/auth/parse-roles.spec.ts b/frontend/ai.client/src/app/auth/parse-roles.spec.ts new file mode 100644 index 00000000..e1522458 --- /dev/null +++ b/frontend/ai.client/src/app/auth/parse-roles.spec.ts @@ -0,0 +1,118 @@ +import { describe, it, expect } from 'vitest'; +import { parseRolesFromToken } from './parse-roles'; + +describe('parseRolesFromToken', () => { + // -- custom:roles preferred over cognito:groups -- + + it('should prefer custom:roles over cognito:groups', () => { + const roles = parseRolesFromToken({ + 'cognito:groups': ['us-west-2_Pool_ms-entra-id'], + 'custom:roles': 'admin,editor', + }); + expect(roles).toEqual(['admin', 'editor']); + }); + + it('should prefer custom:roles JSON array over cognito:groups', () => { + const roles = parseRolesFromToken({ + 'cognito:groups': ['us-west-2_Pool_ms-entra-id'], + 'custom:roles': '["DotNetDevelopers","Staff"]', + }); + expect(roles).toEqual(['DotNetDevelopers', 'Staff']); + }); + + // -- JSON array parsing -- + + it('should parse JSON array string (Entra ID format)', () => { + const roles = parseRolesFromToken({ + 'custom:roles': '["DotNetDevelopers","All-Employees Entra Sync","Staff"]', + }); + expect(roles).toEqual(['DotNetDevelopers', 'All-Employees Entra Sync', 'Staff']); + }); + + it('should parse single-element JSON array', () => { + const roles = parseRolesFromToken({ 'custom:roles': '["Admin"]' }); + expect(roles).toEqual(['Admin']); + }); + + it('should return empty array for empty JSON array', () => { + const roles = parseRolesFromToken({ 'custom:roles': '[]' }); + expect(roles).toEqual([]); + }); + + it('should trim whitespace in JSON array elements', () => { + const roles = parseRolesFromToken({ + 'custom:roles': '[" Admin ", " Staff "]', + }); + expect(roles).toEqual(['Admin', 'Staff']); + }); + + it('should filter out empty strings from JSON array', () => { + const roles = parseRolesFromToken({ + 'custom:roles': '["Admin", "", "Staff"]', + }); + expect(roles).toEqual(['Admin', 'Staff']); + }); + + // -- comma-separated fallback -- + + it('should parse comma-separated string', () => { + const roles = parseRolesFromToken({ 'custom:roles': 'admin,editor' }); + expect(roles).toEqual(['admin', 'editor']); + }); + + it('should trim spaces in comma-separated roles', () => { + const roles = parseRolesFromToken({ + 'custom:roles': ' admin , editor , viewer ', + }); + expect(roles).toEqual(['admin', 'editor', 'viewer']); + }); + + it('should handle single comma-separated role', () => { + const roles = parseRolesFromToken({ 'custom:roles': 'admin' }); + expect(roles).toEqual(['admin']); + }); + + // -- cognito:groups fallback -- + + it('should fall back to cognito:groups when custom:roles is absent', () => { + const roles = parseRolesFromToken({ + 'cognito:groups': ['admin', 'editor'], + }); + expect(roles).toEqual(['admin', 'editor']); + }); + + it('should fall back to cognito:groups when custom:roles is empty string', () => { + const roles = parseRolesFromToken({ + 'custom:roles': '', + 'cognito:groups': ['admin'], + }); + expect(roles).toEqual(['admin']); + }); + + it('should fall back to cognito:groups when custom:roles is whitespace', () => { + const roles = parseRolesFromToken({ + 'custom:roles': ' ', + 'cognito:groups': ['admin'], + }); + expect(roles).toEqual(['admin']); + }); + + // -- generic roles claim fallback -- + + it('should fall back to roles claim when no Cognito claims present', () => { + const roles = parseRolesFromToken({ roles: ['Admin'] }); + expect(roles).toEqual(['Admin']); + }); + + // -- no roles at all -- + + it('should return empty array when no role claims present', () => { + const roles = parseRolesFromToken({}); + expect(roles).toEqual([]); + }); + + it('should return empty array when custom:roles is null', () => { + const roles = parseRolesFromToken({ 'custom:roles': null }); + expect(roles).toEqual([]); + }); +}); diff --git a/frontend/ai.client/src/app/auth/parse-roles.ts b/frontend/ai.client/src/app/auth/parse-roles.ts new file mode 100644 index 00000000..e6458b1b --- /dev/null +++ b/frontend/ai.client/src/app/auth/parse-roles.ts @@ -0,0 +1,44 @@ +/** + * Parse roles from Cognito JWT token claims. + * + * Priority: + * 1. `custom:roles` – IdP roles mapped via Cognito attribute mapping. + * May be a JSON array string (e.g. Entra ID: '["Admin","Staff"]') + * or a comma-separated string. + * 2. `cognito:groups` – Cognito User Pool Groups. For federated users + * this typically contains the provider group name, not IdP roles. + * 3. `roles` – Generic OIDC roles claim. + * + * @param payload Decoded JWT payload object + * @returns Array of role strings + */ +export function parseRolesFromToken(payload: Record): string[] { + const customRolesRaw = payload['custom:roles']; + + if (typeof customRolesRaw === 'string' && customRolesRaw.trim()) { + try { + const parsed = JSON.parse(customRolesRaw); + if (Array.isArray(parsed)) { + return parsed.map((r: unknown) => String(r).trim()).filter(Boolean); + } + // Parsed but not an array — treat as comma-separated + return customRolesRaw.split(',').map(r => r.trim()).filter(Boolean); + } catch { + // Not valid JSON — fall back to comma-separated + return customRolesRaw.split(',').map(r => r.trim()).filter(Boolean); + } + } + + if (Array.isArray(customRolesRaw)) { + return customRolesRaw; + } + + // Fallback: cognito:groups, then generic roles claim + const groups = payload['cognito:groups']; + if (Array.isArray(groups)) return groups; + + const roles = payload['roles']; + if (Array.isArray(roles)) return roles; + + return []; +} diff --git a/frontend/ai.client/src/app/auth/user.model.ts b/frontend/ai.client/src/app/auth/user.model.ts index 5208b0f0..f08b8747 100644 --- a/frontend/ai.client/src/app/auth/user.model.ts +++ b/frontend/ai.client/src/app/auth/user.model.ts @@ -10,6 +10,7 @@ export interface User { fullName: string; roles: string[]; picture?: string; + providerSub?: string; } /** diff --git a/frontend/ai.client/src/app/auth/user.service.spec.ts b/frontend/ai.client/src/app/auth/user.service.spec.ts index b2ea4421..8e464c2f 100644 --- a/frontend/ai.client/src/app/auth/user.service.spec.ts +++ b/frontend/ai.client/src/app/auth/user.service.spec.ts @@ -1,11 +1,19 @@ import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest'; import { TestBed } from '@angular/core/testing'; +import { HttpClientTestingModule } from '@angular/common/http/testing'; import { UserService } from './user.service'; import { AuthService } from './auth.service'; +import { ConfigService } from '../services/config.service'; describe('UserService', () => { let service: UserService; - let mockAuthService: { getAccessToken: ReturnType }; + let mockAuthService: { + getAccessToken: ReturnType; + getIdToken: ReturnType; + }; + let mockConfigService: { + appApiUrl: ReturnType; + }; // Create base64url-encoded JWT token const createJWT = (payload: any) => { @@ -15,6 +23,7 @@ describe('UserService', () => { return `${headerB64}.${payloadB64}.sig`; }; + // ID token payload (has email, name, cognito:groups) const testPayload = { sub: 'user-123', email: 'test@example.com', @@ -27,16 +36,28 @@ describe('UserService', () => { const testJWT = createJWT(testPayload); + /** Helper: set both tokens (simulates a real login where both are stored). */ + function setTokens(idToken: string | null, accessToken?: string | null) { + mockAuthService.getIdToken.mockReturnValue(idToken); + mockAuthService.getAccessToken.mockReturnValue(accessToken ?? idToken); + } + beforeEach(() => { TestBed.resetTestingModule(); mockAuthService = { - getAccessToken: vi.fn() + getAccessToken: vi.fn(), + getIdToken: vi.fn(), + }; + mockConfigService = { + appApiUrl: vi.fn().mockReturnValue('http://localhost:8000'), }; TestBed.configureTestingModule({ + imports: [HttpClientTestingModule], providers: [ UserService, - { provide: AuthService, useValue: mockAuthService } + { provide: AuthService, useValue: mockAuthService }, + { provide: ConfigService, useValue: mockConfigService }, ] }); @@ -50,16 +71,16 @@ describe('UserService', () => { describe('getUser', () => { it('should return null when no token', () => { - mockAuthService.getAccessToken.mockReturnValue(null); + setTokens(null); service.refreshUser(); - + expect(service.getUser()).toBeNull(); }); it('should return User when token exists', () => { - mockAuthService.getAccessToken.mockReturnValue(testJWT); + setTokens(testJWT); service.refreshUser(); - + const user = service.getUser(); expect(user).toEqual({ email: 'test@example.com', @@ -68,73 +89,74 @@ describe('UserService', () => { lastName: 'User', fullName: 'Test User', roles: ['Admin'], - picture: 'https://example.com/pic.jpg' + picture: 'https://example.com/pic.jpg', + providerSub: '', }); }); }); describe('hasRole', () => { it('should return false when no user', () => { - mockAuthService.getAccessToken.mockReturnValue(null); + setTokens(null); service.refreshUser(); - + expect(service.hasRole('Admin')).toBe(false); }); it('should return true when user has role', () => { - mockAuthService.getAccessToken.mockReturnValue(testJWT); + setTokens(testJWT); service.refreshUser(); - + expect(service.hasRole('Admin')).toBe(true); }); it('should return false when user does not have role', () => { - mockAuthService.getAccessToken.mockReturnValue(testJWT); + setTokens(testJWT); service.refreshUser(); - + expect(service.hasRole('User')).toBe(false); }); }); describe('hasAnyRole', () => { it('should return false when no user', () => { - mockAuthService.getAccessToken.mockReturnValue(null); + setTokens(null); service.refreshUser(); - + expect(service.hasAnyRole(['Admin', 'User'])).toBe(false); }); it('should return true when user has any role', () => { - mockAuthService.getAccessToken.mockReturnValue(testJWT); + setTokens(testJWT); service.refreshUser(); - + expect(service.hasAnyRole(['Admin', 'User'])).toBe(true); }); it('should return false when user has no matching roles', () => { - mockAuthService.getAccessToken.mockReturnValue(testJWT); + setTokens(testJWT); service.refreshUser(); - + expect(service.hasAnyRole(['User', 'Guest'])).toBe(false); }); }); describe('refreshUser', () => { it('should update user when token is available', () => { - mockAuthService.getAccessToken.mockReturnValue(testJWT); - + setTokens(testJWT); + service.refreshUser(); - + expect(service.getUser()).not.toBeNull(); expect(service.getUser()?.email).toBe('test@example.com'); }); it('should set user to null when no token', () => { - mockAuthService.getAccessToken.mockReturnValue(null); - + setTokens(null); + service.refreshUser(); - + expect(service.getUser()).toBeNull(); }); }); -}); \ No newline at end of file +}); diff --git a/frontend/ai.client/src/app/auth/user.service.ts b/frontend/ai.client/src/app/auth/user.service.ts index f6e56ad3..4ea7afba 100644 --- a/frontend/ai.client/src/app/auth/user.service.ts +++ b/frontend/ai.client/src/app/auth/user.service.ts @@ -4,6 +4,7 @@ import { firstValueFrom } from 'rxjs'; import { AuthService } from './auth.service'; import { ConfigService } from '../services/config.service'; import { User, JWTPayload, UserPermissions } from './user.model'; +import { parseRolesFromToken } from './parse-roles'; /** * Service for managing current user information decoded from JWT tokens. @@ -38,12 +39,13 @@ export class UserService { // If user has a token on page load, fetch permissions from backend if (this.authService.getAccessToken()) { this._permissionsPromise = this.fetchPermissions(); + this.syncProfileToBackend(); } if (typeof window !== 'undefined') { // Listen for storage events to sync when tokens change in other tabs/windows window.addEventListener('storage', (event) => { - if (event.key === 'access_token' || event.key === null) { + if (event.key === 'access_token' || event.key === 'id_token' || event.key === null) { this.refreshUser(); } }); @@ -52,6 +54,7 @@ export class UserService { window.addEventListener('token-stored', () => { this.refreshUser(); this._permissionsPromise = this.fetchPermissions(); + this.syncProfileToBackend(); }); window.addEventListener('token-cleared', () => { @@ -103,8 +106,10 @@ export class UserService { } // Build full name from available claims + // ID tokens have name/given_name/family_name; Cognito tokens have cognito:username const fullName = jwtPayload.name || `${jwtPayload.given_name || ''} ${jwtPayload.family_name || ''}`.trim() || + jwtPayload['cognito:username'] || email; // Extract first and last name - prefer JWT claims, fall back to parsing fullName @@ -118,7 +123,11 @@ export class UserService { lastName = nameParts.slice(1).join(' ') || ''; } - const roles = jwtPayload.roles || []; + // Extract roles using shared parser (handles JSON arrays, comma-separated, fallbacks) + const roles = parseRolesFromToken(jwtPayload); + + // Extract IdP user identifier (mapped via custom:provider_sub) + const providerSub = jwtPayload['custom:provider_sub'] || ''; const user: User = { email, @@ -127,7 +136,8 @@ export class UserService { lastName, fullName, roles, - picture: jwtPayload.picture + picture: jwtPayload.picture, + providerSub, }; return user; @@ -208,6 +218,32 @@ export class UserService { } } + /** + * Sync user profile from the ID token to the backend Users table. + * Called after each login/token refresh so the backend has current + * identity data (email, name, picture) that isn't in the access token. + */ + private async syncProfileToBackend(): Promise { + const user = this.currentUser(); + if (!user?.email) return; + + try { + const url = `${this.config.appApiUrl()}/users/me/sync`; + await firstValueFrom( + this.http.post(url, { + email: user.email, + name: user.fullName, + picture: user.picture || null, + roles: user.roles || [], + provider_sub: user.providerSub || null, + }) + ); + } catch (error) { + // Non-critical — don't break the login flow + console.warn('Failed to sync profile to backend:', error); + } + } + /** * Ensure permissions have been loaded. Awaits any in-flight fetch * or starts a new one if needed. Used by guards to handle direct navigation. @@ -231,10 +267,13 @@ export class UserService { /** * Manually refresh user data from current token. - * Useful when token has been updated externally. + * Decodes user profile from the ID token (which contains email, name, groups). + * Falls back to the access token if no ID token is available. */ refreshUser(): void { - const token = this.authService.getAccessToken(); + const idToken = this.authService.getIdToken(); + const accessToken = this.authService.getAccessToken(); + const token = idToken || accessToken; if (token) { this.updateUserFromToken(token); } else { diff --git a/frontend/ai.client/src/app/components/sidenav/sidenav.spec.ts b/frontend/ai.client/src/app/components/sidenav/sidenav.spec.ts index b97a1cf1..d9218f7b 100644 --- a/frontend/ai.client/src/app/components/sidenav/sidenav.spec.ts +++ b/frontend/ai.client/src/app/components/sidenav/sidenav.spec.ts @@ -70,9 +70,9 @@ describe('Sidenav', () => { expect(mockSidenavService.toggleCollapsed).toHaveBeenCalled(); }); - it('should handle logout with redirect', async () => { + it('should handle logout', async () => { const component = await createComponent(); component.handleLogout(); - expect(mockAuthService.logout).toHaveBeenCalledWith(window.location.origin); + expect(mockAuthService.logout).toHaveBeenCalled(); }); }); diff --git a/frontend/ai.client/src/app/components/sidenav/sidenav.ts b/frontend/ai.client/src/app/components/sidenav/sidenav.ts index f2bfce42..e105fc5c 100644 --- a/frontend/ai.client/src/app/components/sidenav/sidenav.ts +++ b/frontend/ai.client/src/app/components/sidenav/sidenav.ts @@ -52,8 +52,6 @@ export class Sidenav { } handleLogout() { - // Redirect to home page after logout - const postLogoutRedirectUri = window.location.origin; - this.authService.logout(postLogoutRedirectUri); + this.authService.logout(); } } diff --git a/frontend/ai.client/src/app/services/config.service.spec.ts b/frontend/ai.client/src/app/services/config.service.spec.ts index 945d39be..cbe3ec4a 100644 --- a/frontend/ai.client/src/app/services/config.service.spec.ts +++ b/frontend/ai.client/src/app/services/config.service.spec.ts @@ -8,8 +8,12 @@ describe('ConfigService', () => { const validConfig: RuntimeConfig = { appApiUrl: 'https://api.example.com', + inferenceApiUrl: 'https://inference.example.com', environment: 'production', - version: '1.0.0-beta.1' + version: '1.0.0-beta.1', + cognitoDomainUrl: 'https://myprefix.auth.us-east-1.amazoncognito.com', + cognitoAppClientId: 'test-client-id', + cognitoRegion: 'us-east-1', }; beforeEach(() => { diff --git a/frontend/ai.client/src/app/services/config.service.ts b/frontend/ai.client/src/app/services/config.service.ts index 95777a9d..712acdcd 100644 --- a/frontend/ai.client/src/app/services/config.service.ts +++ b/frontend/ai.client/src/app/services/config.service.ts @@ -19,6 +19,18 @@ export interface RuntimeConfig { /** Application version from VERSION file (injected via config.json or environment fallback) */ version: string; + + /** Cognito User Pool domain URL (e.g., https://myprefix.auth.us-east-1.amazoncognito.com) */ + cognitoDomainUrl: string; + + /** Cognito App Client ID */ + cognitoAppClientId: string; + + /** AWS region for Cognito (e.g., us-east-1) */ + cognitoRegion: string; + + /** Single inference API URL (replaces per-provider runtime endpoint resolution) */ + inferenceApiUrl: string; } /** @@ -76,6 +88,44 @@ export class ConfigService { * Returns 'unknown' if config not loaded or version not set */ readonly version = computed(() => this.config()?.version ?? 'unknown'); + + /** + * Computed signal for Cognito domain URL + * Returns empty string if config not loaded + */ + readonly cognitoDomainUrl = computed(() => this.config()?.cognitoDomainUrl ?? ''); + + /** + * Computed signal for Cognito App Client ID + * Returns empty string if config not loaded + */ + readonly cognitoAppClientId = computed(() => this.config()?.cognitoAppClientId ?? ''); + + /** + * Computed signal for Cognito region + * Returns 'us-east-1' if config not loaded + */ + readonly cognitoRegion = computed(() => this.config()?.cognitoRegion ?? 'us-east-1'); + + /** + * Computed signal for Inference API URL (single runtime endpoint). + * URL-encodes the ARN portion of the path since AgentCore runtime ARNs + * contain colons and slashes that break the URL if left raw. + * Input: https://bedrock-agentcore.us-west-2.amazonaws.com/runtimes/arn:aws:bedrock-agentcore:... + * Output: https://bedrock-agentcore.us-west-2.amazonaws.com/runtimes/arn%3Aaws%3Abedrock-agentcore%3A... + */ + readonly inferenceApiUrl = computed(() => { + const raw = this.config()?.inferenceApiUrl ?? ''; + if (!raw) return ''; + + const marker = '/runtimes/'; + const idx = raw.indexOf(marker); + if (idx === -1) return raw; + + const base = raw.substring(0, idx + marker.length); + const arn = raw.substring(idx + marker.length); + return base + encodeURIComponent(arn); + }); /** * Read-only signal indicating if configuration has been loaded @@ -131,6 +181,10 @@ export class ConfigService { appApiUrl: environment.appApiUrl || 'http://localhost:8000', environment: environment.production ? 'production' : 'development', version: (environment as any).version || 'unknown', + cognitoDomainUrl: (environment as any).cognitoDomainUrl || '', + cognitoAppClientId: (environment as any).cognitoAppClientId || '', + cognitoRegion: (environment as any).cognitoRegion || 'us-east-1', + inferenceApiUrl: (environment as any).inferenceApiUrl || 'http://localhost:8001', }; console.log('📋 Using fallback configuration from environment.ts'); diff --git a/frontend/ai.client/src/app/services/system.service.spec.ts b/frontend/ai.client/src/app/services/system.service.spec.ts new file mode 100644 index 00000000..bc332b86 --- /dev/null +++ b/frontend/ai.client/src/app/services/system.service.spec.ts @@ -0,0 +1,92 @@ +import { TestBed } from '@angular/core/testing'; +import { SystemService, FirstBootError } from './system.service'; +import { ConfigService } from './config.service'; +import { signal } from '@angular/core'; +import { describe, it, expect, vi, beforeEach } from 'vitest'; + +describe('SystemService', () => { + let service: SystemService; + + beforeEach(() => { + TestBed.configureTestingModule({ + providers: [ + SystemService, + { provide: ConfigService, useValue: { appApiUrl: signal('http://localhost:8000') } }, + ], + }); + service = TestBed.inject(SystemService); + vi.restoreAllMocks(); + }); + + describe('checkStatus', () => { + it('should return true when first_boot_completed is true', async () => { + vi.spyOn(globalThis, 'fetch').mockResolvedValue(new Response(JSON.stringify({ first_boot_completed: true }), { status: 200 })); + expect(await service.checkStatus()).toBe(true); + }); + + it('should return false when first_boot_completed is false', async () => { + vi.spyOn(globalThis, 'fetch').mockResolvedValue(new Response(JSON.stringify({ first_boot_completed: false }), { status: 200 })); + expect(await service.checkStatus()).toBe(false); + }); + + it('should return cached value on subsequent calls', async () => { + const fetchSpy = vi.spyOn(globalThis, 'fetch').mockResolvedValue(new Response(JSON.stringify({ first_boot_completed: true }), { status: 200 })); + await service.checkStatus(); + const callsAfterFirst = fetchSpy.mock.calls.filter(c => String(c[0]).includes('/system/status')).length; + await service.checkStatus(); + const callsAfterSecond = fetchSpy.mock.calls.filter(c => String(c[0]).includes('/system/status')).length; + expect(callsAfterSecond).toBe(callsAfterFirst); + }); + + it('should return false on non-OK response', async () => { + vi.spyOn(globalThis, 'fetch').mockResolvedValue(new Response('error', { status: 500 })); + expect(await service.checkStatus()).toBe(false); + }); + + it('should return false on network error', async () => { + vi.spyOn(globalThis, 'fetch').mockRejectedValue(new Error('Network error')); + expect(await service.checkStatus()).toBe(false); + }); + }); + + describe('firstBoot', () => { + it('should return response and update cache on success', async () => { + const body = { success: true, user_id: 'u1', message: 'ok' }; + const fetchSpy = vi.spyOn(globalThis, 'fetch').mockResolvedValue(new Response(JSON.stringify(body), { status: 200 })); + const result = await service.firstBoot('admin', 'a@b.com', 'Pass1234!'); + expect(result).toEqual(body); + // Cache should now be true — next checkStatus should not hit the API again + fetchSpy.mockClear(); + expect(await service.checkStatus()).toBe(true); + expect(fetchSpy).not.toHaveBeenCalled(); + }); + + it('should throw FirstBootError on non-OK response with JSON body', async () => { + vi.spyOn(globalThis, 'fetch').mockResolvedValue(new Response(JSON.stringify({ detail: 'Already completed' }), { status: 409 })); + await expect(service.firstBoot('admin', 'a@b.com', 'Pass1234!')).rejects.toThrow(FirstBootError); + }); + + it('should throw FirstBootError with fallback message on non-JSON error body', async () => { + vi.spyOn(globalThis, 'fetch').mockResolvedValue(new Response('not json', { status: 500, headers: { 'Content-Type': 'text/plain' } })); + try { + await service.firstBoot('admin', 'a@b.com', 'Pass1234!'); + expect.unreachable('should have thrown'); + } catch (e) { + expect(e).toBeInstanceOf(FirstBootError); + expect((e as FirstBootError).message).toContain('Unknown error'); + } + }); + }); + + describe('clearCache', () => { + it('should force re-fetch after clearing cache', async () => { + const fetchSpy = vi.spyOn(globalThis, 'fetch').mockResolvedValue(new Response(JSON.stringify({ first_boot_completed: true }), { status: 200 })); + await service.checkStatus(); + const callsBeforeClear = fetchSpy.mock.calls.filter(c => String(c[0]).includes('/system/status')).length; + service.clearCache(); + await service.checkStatus(); + const callsAfterClear = fetchSpy.mock.calls.filter(c => String(c[0]).includes('/system/status')).length; + expect(callsAfterClear).toBe(callsBeforeClear + 1); + }); + }); +}); diff --git a/frontend/ai.client/src/app/services/system.service.ts b/frontend/ai.client/src/app/services/system.service.ts new file mode 100644 index 00000000..10247c91 --- /dev/null +++ b/frontend/ai.client/src/app/services/system.service.ts @@ -0,0 +1,99 @@ +import { Injectable, inject, signal } from '@angular/core'; +import { ConfigService } from './config.service'; + +export interface SystemStatus { + first_boot_completed: boolean; +} + +export interface FirstBootRequest { + username: string; + email: string; + password: string; +} + +export interface FirstBootResponse { + success: boolean; + user_id: string; + message: string; +} + +/** + * Service for system-level operations: first-boot status and admin setup. + * Caches the system status to avoid repeated API calls. + */ +@Injectable({ + providedIn: 'root' +}) +export class SystemService { + private readonly config = inject(ConfigService); + private cachedStatus = signal(null); + + /** + * Check if first-boot has been completed. + * Caches the result so subsequent calls don't hit the API. + * @returns true if first-boot is completed, false otherwise + */ + async checkStatus(): Promise { + const cached = this.cachedStatus(); + if (cached !== null) { + return cached; + } + + try { + const url = `${this.config.appApiUrl()}/system/status`; + const response = await fetch(url); + + if (!response.ok) { + // Treat errors as not completed (safe default) + this.cachedStatus.set(false); + return false; + } + + const data: SystemStatus = await response.json(); + this.cachedStatus.set(data.first_boot_completed); + return data.first_boot_completed; + } catch { + // Network error — treat as not completed + this.cachedStatus.set(false); + return false; + } + } + + /** + * Submit the first-boot admin registration. + * On success, invalidates the cached status. + */ + async firstBoot(username: string, email: string, password: string): Promise { + const url = `${this.config.appApiUrl()}/system/first-boot`; + const response = await fetch(url, { + method: 'POST', + headers: { 'Content-Type': 'application/json' }, + body: JSON.stringify({ username, email, password } as FirstBootRequest), + }); + + if (!response.ok) { + const errorBody = await response.json().catch(() => ({ detail: 'Unknown error' })); + const detail = errorBody.detail || `Request failed with status ${response.status}`; + throw new FirstBootError(detail, response.status); + } + + const data: FirstBootResponse = await response.json(); + // Invalidate cache so next check reflects completion + this.cachedStatus.set(true); + return data; + } + + /** + * Clear the cached status (useful for testing or forced re-check). + */ + clearCache(): void { + this.cachedStatus.set(null); + } +} + +export class FirstBootError extends Error { + constructor(message: string, public readonly statusCode: number) { + super(message); + this.name = 'FirstBootError'; + } +} diff --git a/frontend/ai.client/src/app/session/services/chat/chat-http.service.spec.ts b/frontend/ai.client/src/app/session/services/chat/chat-http.service.spec.ts index 3ef0546c..6f3ee3db 100644 --- a/frontend/ai.client/src/app/session/services/chat/chat-http.service.spec.ts +++ b/frontend/ai.client/src/app/session/services/chat/chat-http.service.spec.ts @@ -1,12 +1,11 @@ import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest'; import { TestBed } from '@angular/core/testing'; -import { HttpClientTestingModule, HttpTestingController } from '@angular/common/http/testing'; +import { provideHttpClient } from '@angular/common/http'; +import { HttpTestingController, provideHttpClientTesting } from '@angular/common/http/testing'; import { signal } from '@angular/core'; -import { of, throwError } from 'rxjs'; import { ChatHttpService } from './chat-http.service'; import { ConfigService } from '../../../services/config.service'; import { AuthService } from '../../../auth/auth.service'; -import { AuthApiService } from '../../../auth/auth-api.service'; import { SessionService } from '../session/session.service'; import { StreamParserService } from './stream-parser.service'; import { ChatStateService } from './chat-state.service'; @@ -17,18 +16,17 @@ describe('ChatHttpService', () => { let service: ChatHttpService; let httpMock: HttpTestingController; let authService: any; - let authApiService: any; let chatStateService: any; beforeEach(() => { TestBed.resetTestingModule(); TestBed.configureTestingModule({ - imports: [HttpClientTestingModule], providers: [ + provideHttpClient(), + provideHttpClientTesting(), ChatHttpService, - { provide: ConfigService, useValue: { appApiUrl: signal('http://localhost:8000') } }, + { provide: ConfigService, useValue: { appApiUrl: signal('http://localhost:8000'), inferenceApiUrl: signal('http://localhost:8001') } }, { provide: AuthService, useValue: { getAccessToken: vi.fn().mockReturnValue('tok'), isTokenExpired: vi.fn().mockReturnValue(false), refreshAccessToken: vi.fn(), ensureAuthenticated: vi.fn().mockResolvedValue(undefined), isAuthenticated: vi.fn().mockReturnValue(true), getProviderId: vi.fn().mockReturnValue('p1') } }, - { provide: AuthApiService, useValue: { getRuntimeEndpoint: vi.fn() } }, { provide: SessionService, useValue: { currentSession: signal({ sessionId: 's1' }), updateSessionTitleInCache: vi.fn() } }, { provide: StreamParserService, useValue: {} }, { provide: ChatStateService, useValue: { isStreaming: signal(false), streamingSessionId: signal(null), abortCurrentRequest: vi.fn(), setChatLoading: vi.fn(), resetState: vi.fn(), getAbortController: vi.fn().mockReturnValue(new AbortController()) } }, @@ -39,7 +37,6 @@ describe('ChatHttpService', () => { service = TestBed.inject(ChatHttpService); httpMock = TestBed.inject(HttpTestingController); authService = TestBed.inject(AuthService); - authApiService = TestBed.inject(AuthApiService); chatStateService = TestBed.inject(ChatStateService); }); @@ -94,39 +91,4 @@ describe('ChatHttpService', () => { authService.refreshAccessToken.mockRejectedValue(new Error('Refresh failed')); await expect(service.getBearerTokenForStreamingResponse()).rejects.toThrow(); }); - - it('should get runtime endpoint URL successfully', async () => { - authApiService.getRuntimeEndpoint.mockReturnValue(of({ runtime_endpoint_url: 'http://runtime.test/invocations', provider_id: 'p1' })); - const url = await (service as any).getRuntimeEndpointUrl(); - expect(url).toBe('http://runtime.test/invocations'); - }); - - it('should handle 404 error from runtime endpoint', async () => { - authApiService.getRuntimeEndpoint.mockReturnValue(throwError(() => ({ status: 404 }))); - await expect((service as any).getRuntimeEndpointUrl()).rejects.toThrow(); - }); - - it('should handle 401 error from runtime endpoint', async () => { - authApiService.getRuntimeEndpoint.mockReturnValue(throwError(() => ({ status: 401 }))); - await expect((service as any).getRuntimeEndpointUrl()).rejects.toThrow(); - }); - - it('should handle generic error from runtime endpoint', async () => { - authApiService.getRuntimeEndpoint.mockReturnValue(throwError(() => new Error('Network error'))); - await expect((service as any).getRuntimeEndpointUrl()).rejects.toThrow(); - }); - - it('should handle missing URL in runtime endpoint response', async () => { - authApiService.getRuntimeEndpoint.mockReturnValue(of({ provider_id: 'p1' })); - await expect((service as any).getRuntimeEndpointUrl()).rejects.toThrow('Invalid runtime endpoint response'); - }); - - it('should log warning on provider ID mismatch but still return URL', async () => { - const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {}); - authApiService.getRuntimeEndpoint.mockReturnValue(of({ runtime_endpoint_url: 'http://runtime.test/invocations', provider_id: 'p2' })); - const url = await (service as any).getRuntimeEndpointUrl(); - expect(url).toBe('http://runtime.test/invocations'); - expect(warnSpy).toHaveBeenCalled(); - warnSpy.mockRestore(); - }); }); diff --git a/frontend/ai.client/src/app/session/services/chat/chat-http.service.ts b/frontend/ai.client/src/app/session/services/chat/chat-http.service.ts index 16a8a519..5743f91f 100644 --- a/frontend/ai.client/src/app/session/services/chat/chat-http.service.ts +++ b/frontend/ai.client/src/app/session/services/chat/chat-http.service.ts @@ -4,7 +4,6 @@ import { StreamParserService } from './stream-parser.service'; import { ChatStateService } from './chat-state.service'; import { MessageMapService } from '../session/message-map.service'; import { AuthService } from '../../../auth/auth.service'; -import { AuthApiService } from '../../../auth/auth-api.service'; import { ConfigService } from '../../../services/config.service'; import { firstValueFrom } from 'rxjs'; import { HttpClient } from '@angular/common/http'; @@ -42,7 +41,6 @@ export class ChatHttpService { private chatStateService = inject(ChatStateService); private messageMapService = inject(MessageMapService); private authService = inject(AuthService); - private authApiService = inject(AuthApiService); private config = inject(ConfigService); private http = inject(HttpClient); private sessionService = inject(SessionService); @@ -53,11 +51,16 @@ export class ChatHttpService { const token = await this.getBearerTokenForStreamingResponse(); - // Fetch runtime endpoint URL for the user's provider - // The endpoint URL already includes /invocations path - const runtimeEndpointUrl = await this.getRuntimeEndpointUrl(); + // Single runtime endpoint from configuration + const runtimeEndpointUrl = this.config.inferenceApiUrl(); + if (!runtimeEndpointUrl) { + throw new FatalError('Inference API URL not configured. Please check your configuration.'); + } + + // Normalize: strip trailing /invocations if already present to avoid doubling + const baseUrl = runtimeEndpointUrl.replace(/\/invocations\/?$/, ''); - return fetchEventSource(`${runtimeEndpointUrl}?qualifier=DEFAULT`, { + return fetchEventSource(`${baseUrl}/invocations?qualifier=DEFAULT`, { method: 'POST', headers: { 'Content-Type': 'application/json', @@ -236,68 +239,4 @@ export class ChatHttpService { return token; } - /** - * Get the runtime endpoint URL for the user's authentication provider. - * - * This method fetches the provider-specific AgentCore Runtime endpoint URL - * from the App API. Each provider has its own dedicated runtime with - * provider-specific JWT validation. - * - * Flow: - * 1. Call App API /auth/runtime-endpoint (authenticated request) - * 2. Backend extracts issuer from JWT and matches to provider - * 3. Backend returns runtime endpoint URL for that provider - * 4. Use this endpoint for all inference API calls - * - * @returns Promise resolving to the runtime endpoint URL - * @throws FatalError if provider not found or runtime not ready - * - * @example - * ```typescript - * const endpointUrl = await this.getRuntimeEndpointUrl(); - * // Returns: "https://bedrock-agentcore.us-east-1.amazonaws.com/runtimes/arn%3Aaws%3A.../invocations" - * ``` - */ - private async getRuntimeEndpointUrl(): Promise { - try { - // Fetch runtime endpoint from App API - const response = await firstValueFrom( - this.authApiService.getRuntimeEndpoint() - ); - - if (!response || !response.runtime_endpoint_url) { - throw new FatalError('Invalid runtime endpoint response from server'); - } - - // Update provider ID in auth service for tracking - if (response.provider_id) { - // Provider ID is already tracked by auth service during login - // This is just for verification/logging - const currentProviderId = this.authService.getProviderId(); - if (currentProviderId !== response.provider_id) { - console.warn( - `Provider ID mismatch: expected ${currentProviderId}, got ${response.provider_id}`, - ); - } - } - - return response.runtime_endpoint_url; - } catch (error: any) { - // Handle specific HTTP errors - if (error?.status === 404) { - throw new FatalError( - 'Runtime not found for your authentication provider. Please contact support.', - ); - } else if (error?.status === 401) { - throw new FatalError('Authentication required. Please login again.'); - } else if (error instanceof FatalError) { - // Re-throw FatalError as-is - throw error; - } else { - // Generic error - const errorMessage = error?.message || 'Failed to resolve runtime endpoint'; - throw new FatalError(`Unable to connect to inference service: ${errorMessage}`); - } - } - } } diff --git a/frontend/ai.client/src/environments/environment.production.ts b/frontend/ai.client/src/environments/environment.production.ts index 3e2a8be9..a5905deb 100644 --- a/frontend/ai.client/src/environments/environment.production.ts +++ b/frontend/ai.client/src/environments/environment.production.ts @@ -31,5 +31,9 @@ export const environment = { // Runtime values loaded from /config.json // These are placeholders for fallback only appApiUrl: '', - version: '' + version: '', + cognitoDomainUrl: '', + cognitoAppClientId: '', + cognitoRegion: 'us-east-1', + inferenceApiUrl: '', }; diff --git a/frontend/ai.client/src/environments/environment.ts b/frontend/ai.client/src/environments/environment.ts index 25b8b426..6446804a 100644 --- a/frontend/ai.client/src/environments/environment.ts +++ b/frontend/ai.client/src/environments/environment.ts @@ -23,5 +23,9 @@ export const environment = { production: false, appApiUrl: 'http://localhost:8000', - version: 'dev' + version: 'dev', + cognitoDomainUrl: '', + cognitoAppClientId: '', + cognitoRegion: 'us-east-1', + inferenceApiUrl: 'http://localhost:8001', }; diff --git a/infrastructure/cdk.context.json b/infrastructure/cdk.context.json index e084b7ed..e4b5b41f 100644 --- a/infrastructure/cdk.context.json +++ b/infrastructure/cdk.context.json @@ -8,7 +8,7 @@ "awsAccount": "", "awsRegion": "us-west-2", "vpcCidr": "10.0.0.0/16", - "corsOrigins": "http://localhost:4200,http://localhost:8000", + "corsOrigins": "", "domainName": "", "infrastructureHostedZoneDomain": "", "albSubdomain": "", @@ -33,8 +33,7 @@ "memory": 2048, "desiredCount": 1, "maxCapacity": 5, - "logLevel": "INFO", - "corsOrigins": "" + "logLevel": "INFO" }, "gateway": { "enabled": true, diff --git a/infrastructure/lib/app-api-stack.ts b/infrastructure/lib/app-api-stack.ts index 494b733b..20524a40 100644 --- a/infrastructure/lib/app-api-stack.ts +++ b/infrastructure/lib/app-api-stack.ts @@ -13,7 +13,7 @@ import * as sns from "aws-cdk-lib/aws-sns"; import * as events from "aws-cdk-lib/aws-events"; import * as targets from "aws-cdk-lib/aws-events-targets"; import { Construct } from "constructs"; -import { AppConfig, getResourceName, applyStandardTags, getRemovalPolicy } from "./config"; +import { AppConfig, getResourceName, applyStandardTags, getRemovalPolicy, buildCorsOrigins } from "./config"; export interface AppApiStackProps extends cdk.StackProps { config: AppConfig; @@ -318,14 +318,33 @@ export class AppApiStack extends cdk.Stack { this, `/${config.projectPrefix}/auth/auth-providers-table-arn` ); - const authProvidersStreamArn = ssm.StringParameter.valueForStringParameter( + const authProviderSecretsArn = ssm.StringParameter.valueForStringParameter( this, - `/${config.projectPrefix}/auth/auth-providers-stream-arn` + `/${config.projectPrefix}/auth/auth-provider-secrets-arn` ); - const authProviderSecretsArn = ssm.StringParameter.valueForStringParameter( + // ============================================================ + // Import Cognito Resources from Infrastructure Stack + // ============================================================ + const cognitoUserPoolArn = ssm.StringParameter.valueForStringParameter( this, - `/${config.projectPrefix}/auth/auth-provider-secrets-arn` + `/${config.projectPrefix}/auth/cognito/user-pool-arn` + ); + const cognitoUserPoolId = ssm.StringParameter.valueForStringParameter( + this, + `/${config.projectPrefix}/auth/cognito/user-pool-id` + ); + const cognitoAppClientId = ssm.StringParameter.valueForStringParameter( + this, + `/${config.projectPrefix}/auth/cognito/app-client-id` + ); + const cognitoIssuerUrl = ssm.StringParameter.valueForStringParameter( + this, + `/${config.projectPrefix}/auth/cognito/issuer-url` + ); + const cognitoDomainUrl = ssm.StringParameter.valueForStringParameter( + this, + `/${config.projectPrefix}/auth/cognito/domain-url` ); // ============================================================ @@ -385,6 +404,7 @@ export class AppApiStack extends cdk.Stack { AWS_REGION: config.awsRegion, PROJECT_PREFIX: config.projectPrefix, FRONTEND_URL: config.domainName ? `https://${config.domainName}` : 'http://localhost:4200', + CORS_ORIGINS: buildCorsOrigins(config, config.appApi.additionalCorsOrigins).join(','), DYNAMODB_QUOTA_TABLE: userQuotasTableName, DYNAMODB_EVENTS_TABLE: quotaEventsTableName, DYNAMODB_OIDC_STATE_TABLE_NAME: oidcStateTableName, @@ -428,6 +448,12 @@ export class AppApiStack extends cdk.Stack { DYNAMODB_AUTH_PROVIDERS_TABLE_NAME: authProvidersTableName, AUTH_PROVIDER_SECRETS_ARN: authProviderSecretsArn, DYNAMODB_USER_SETTINGS_TABLE_NAME: userSettingsTableName, + // Cognito configuration (imported from Infrastructure Stack) + COGNITO_USER_POOL_ID: cognitoUserPoolId, + COGNITO_APP_CLIENT_ID: cognitoAppClientId, + COGNITO_ISSUER_URL: cognitoIssuerUrl, + COGNITO_DOMAIN_URL: cognitoDomainUrl, + COGNITO_REGION: config.awsRegion, SHARED_CONVERSATIONS_TABLE_NAME: ssm.StringParameter.valueForStringParameter( this, `/${config.projectPrefix}/shares/shared-conversations-table-name` @@ -938,6 +964,31 @@ export class AppApiStack extends cdk.Stack { }) ); + // Grant Cognito permissions for identity provider management and first-boot + taskDefinition.taskRole.addToPrincipalPolicy( + new iam.PolicyStatement({ + sid: 'CognitoIdentityProviderManagement', + effect: iam.Effect.ALLOW, + actions: [ + 'cognito-idp:CreateIdentityProvider', + 'cognito-idp:UpdateIdentityProvider', + 'cognito-idp:DeleteIdentityProvider', + 'cognito-idp:DescribeIdentityProvider', + 'cognito-idp:ListIdentityProviders', + 'cognito-idp:UpdateUserPoolClient', + 'cognito-idp:DescribeUserPoolClient', + 'cognito-idp:AdminCreateUser', + 'cognito-idp:AdminSetUserPassword', + 'cognito-idp:AdminGetUser', + 'cognito-idp:AdminDeleteUser', + 'cognito-idp:AdminAddUserToGroup', + 'cognito-idp:CreateGroup', + 'cognito-idp:UpdateUserPool', + ], + resources: [cognitoUserPoolArn], + }) + ); + // Grant SSM read permissions for runtime image tag taskDefinition.taskRole.addToPrincipalPolicy( new iam.PolicyStatement({ @@ -1110,324 +1161,6 @@ export class AppApiStack extends cdk.Stack { ); } - // ============================================================ - // Runtime Provisioner Lambda - // ============================================================ - - // Reconstruct AuthProviders table reference for DynamoDB Stream event source - // Note: fromTableAttributes accepts either tableName OR tableArn, not both - const authProvidersTable = dynamodb.Table.fromTableAttributes(this, 'ImportedAuthProvidersTable', { - tableArn: authProvidersTableArn, - tableStreamArn: authProvidersStreamArn, - }); - - // Create Lambda function for runtime provisioning - const runtimeProvisionerFunction = new lambda.Function(this, "RuntimeProvisionerFunction", { - functionName: getResourceName(config, "runtime-provisioner"), - runtime: lambda.Runtime.PYTHON_3_14, - handler: "lambda_function.lambda_handler", - code: lambda.Code.fromAsset("../backend/lambda-functions/runtime-provisioner"), - timeout: cdk.Duration.minutes(5), - memorySize: 512, - architecture: lambda.Architecture.ARM_64, - environment: { - PROJECT_PREFIX: config.projectPrefix, - AUTH_PROVIDERS_TABLE: authProvidersTableName, - }, - logRetention: logs.RetentionDays.ONE_WEEK, - }); - - // Grant DynamoDB Stream read permissions - authProvidersTable.grantStreamRead(runtimeProvisionerFunction); - - // Grant DynamoDB UpdateItem permissions for Auth Providers table - authProvidersTable.grantReadWriteData(runtimeProvisionerFunction); - - // Grant Bedrock AgentCore permissions - runtimeProvisionerFunction.addToRolePolicy( - new iam.PolicyStatement({ - sid: "BedrockAgentCoreRuntimeManagement", - effect: iam.Effect.ALLOW, - actions: [ - "bedrock-agentcore:CreateAgentRuntime", - "bedrock-agentcore:CreateAgentRuntimeEndpoint", - "bedrock-agentcore:CreateWorkloadIdentity", - "bedrock-agentcore:DeleteWorkloadIdentity", - "bedrock-agentcore:UpdateAgentRuntime", - "bedrock-agentcore:DeleteAgentRuntime", - "bedrock-agentcore:DeleteAgentRuntimeEndpoint", - "bedrock-agentcore:GetAgentRuntime", - "bedrock-agentcore:ListAgentRuntimeEndpoints", - "bedrock-agentcore:AllowVendedLogDeliveryForResource", - ], - resources: ["*"], // Runtime ARNs are not known at deployment time - }) - ); - - // Grant permission to create service-linked roles for Bedrock AgentCore - // Required on first CreateAgentRuntime call in an account - runtimeProvisionerFunction.addToRolePolicy( - new iam.PolicyStatement({ - sid: "CreateNetworkServiceLinkedRole", - effect: iam.Effect.ALLOW, - actions: ["iam:CreateServiceLinkedRole"], - resources: ["arn:aws:iam::*:role/aws-service-role/network.bedrock-agentcore.amazonaws.com/AWSServiceRoleForBedrockAgentCoreNetwork"], - conditions: { - StringLike: { - "iam:AWSServiceName": "network.bedrock-agentcore.amazonaws.com", - }, - }, - }) - ); - - runtimeProvisionerFunction.addToRolePolicy( - new iam.PolicyStatement({ - sid: "CreateIdentityServiceLinkedRole", - effect: iam.Effect.ALLOW, - actions: ["iam:CreateServiceLinkedRole"], - resources: ["arn:aws:iam::*:role/aws-service-role/runtime-identity.bedrock-agentcore.amazonaws.com/AWSServiceRoleForBedrockAgentCoreRuntimeIdentity"], - conditions: { - StringEquals: { - "iam:AWSServiceName": "runtime-identity.bedrock-agentcore.amazonaws.com", - }, - }, - }) - ); - - // Grant SSM Parameter Store read/write permissions - runtimeProvisionerFunction.addToRolePolicy( - new iam.PolicyStatement({ - sid: "SSMParameterAccess", - effect: iam.Effect.ALLOW, - actions: [ - "ssm:GetParameter", - "ssm:GetParameters", - "ssm:PutParameter", - "ssm:DeleteParameter", - ], - resources: [ - `arn:aws:ssm:${config.awsRegion}:${config.awsAccount}:parameter/${config.projectPrefix}/*`, - ], - }) - ); - - // Grant ECR read permissions - runtimeProvisionerFunction.addToRolePolicy( - new iam.PolicyStatement({ - sid: "ECRReadAccess", - effect: iam.Effect.ALLOW, - actions: [ - "ecr:DescribeRepositories", - "ecr:DescribeImages", - "ecr:GetAuthorizationToken", - ], - resources: ["*"], // ECR authorization token requires wildcard - }) - ); - - // Grant CloudWatch Logs delivery permissions for runtime observability - // The Lambda sets up vended log deliveries (APPLICATION_LOGS + TRACES) after creating runtimes - runtimeProvisionerFunction.addToRolePolicy( - new iam.PolicyStatement({ - sid: "CloudWatchLogsDeliveryManagement", - effect: iam.Effect.ALLOW, - actions: [ - "logs:PutDeliverySource", - "logs:PutDeliveryDestination", - "logs:CreateDelivery", - "logs:DeleteDeliverySource", - "logs:DeleteDeliveryDestination", - "logs:DeleteDelivery", - "logs:GetDelivery", - "logs:GetDeliverySource", - "logs:GetDeliveryDestination", - "logs:DescribeDeliveries", - "logs:DescribeDeliverySources", - "logs:DescribeDeliveryDestinations", - "logs:CreateLogGroup", - "logs:DescribeLogGroups", - ], - resources: ["*"], - }) - ); - - // Grant X-Ray resource policy permissions for TRACES delivery destinations - // Required so the Lambda can create X-Ray delivery destinations and auto-create - // the X-Ray resource policy that allows delivery.logs.amazonaws.com to write traces - runtimeProvisionerFunction.addToRolePolicy( - new iam.PolicyStatement({ - sid: "XRayResourcePolicyManagement", - effect: iam.Effect.ALLOW, - actions: [ - "xray:PutResourcePolicy", - "xray:ListResourcePolicies", - "xray:GetTraceSegmentDestination", - ], - resources: ["*"], - }) - ); - - // Grant IAM PassRole permission for runtime execution role - const runtimeExecutionRoleArn = ssm.StringParameter.valueForStringParameter( - this, - `/${config.projectPrefix}/inference-api/runtime-execution-role-arn` - ); - - runtimeProvisionerFunction.addToRolePolicy( - new iam.PolicyStatement({ - sid: "IAMPassRoleForRuntime", - effect: iam.Effect.ALLOW, - actions: ["iam:PassRole"], - resources: [runtimeExecutionRoleArn], - conditions: { - StringEquals: { - "iam:PassedToService": "bedrock-agentcore.amazonaws.com", - }, - }, - }) - ); - - // Add DynamoDB Stream event source - runtimeProvisionerFunction.addEventSource( - new lambdaEventSources.DynamoEventSource(authProvidersTable, { - startingPosition: lambda.StartingPosition.LATEST, - batchSize: 1, - retryAttempts: 3, - bisectBatchOnError: true, - }) - ); - - // Store Lambda function ARN in SSM - new ssm.StringParameter(this, "RuntimeProvisionerFunctionArnParameter", { - parameterName: `/${config.projectPrefix}/lambda/runtime-provisioner-arn`, - stringValue: runtimeProvisionerFunction.functionArn, - description: "Runtime Provisioner Lambda function ARN", - tier: ssm.ParameterTier.STANDARD, - }); - - // ============================================================ - // Runtime Updater Lambda - // ============================================================ - - // Create SNS topic for runtime update alerts - const runtimeUpdateAlertsTopic = new sns.Topic(this, "RuntimeUpdateAlertsTopic", { - topicName: getResourceName(config, "runtime-update-alerts"), - displayName: "AgentCore Runtime Update Alerts", - }); - - // Create Lambda function for runtime updates - const runtimeUpdaterFunction = new lambda.Function(this, "RuntimeUpdaterFunction", { - functionName: getResourceName(config, "runtime-updater"), - runtime: lambda.Runtime.PYTHON_3_14, - handler: "lambda_function.lambda_handler", - code: lambda.Code.fromAsset("../backend/lambda-functions/runtime-updater"), - timeout: cdk.Duration.minutes(15), - memorySize: 512, - architecture: lambda.Architecture.ARM_64, - environment: { - PROJECT_PREFIX: config.projectPrefix, - AUTH_PROVIDERS_TABLE: authProvidersTableName, - SNS_TOPIC_ARN: runtimeUpdateAlertsTopic.topicArn, - }, - logRetention: logs.RetentionDays.ONE_WEEK, - }); - - // Grant Bedrock AgentCore permissions - runtimeUpdaterFunction.addToRolePolicy( - new iam.PolicyStatement({ - sid: "BedrockAgentCoreRuntimeUpdates", - effect: iam.Effect.ALLOW, - actions: [ - "bedrock-agentcore:GetAgentRuntime", - "bedrock-agentcore:UpdateAgentRuntime", - ], - resources: ["*"], // Runtime ARNs are not known at deployment time - }) - ); - - // Grant IAM PassRole permission for runtime execution role - runtimeUpdaterFunction.addToRolePolicy( - new iam.PolicyStatement({ - sid: "IAMPassRoleForRuntime", - effect: iam.Effect.ALLOW, - actions: ["iam:PassRole"], - resources: [runtimeExecutionRoleArn], - conditions: { - StringEquals: { - "iam:PassedToService": "bedrock-agentcore.amazonaws.com", - }, - }, - }) - ); - - // Grant DynamoDB Scan and UpdateItem permissions - authProvidersTable.grantReadWriteData(runtimeUpdaterFunction); - - // Grant SSM Parameter Store read permissions - runtimeUpdaterFunction.addToRolePolicy( - new iam.PolicyStatement({ - sid: "SSMParameterReadAccess", - effect: iam.Effect.ALLOW, - actions: [ - "ssm:GetParameter", - "ssm:GetParameters", - ], - resources: [ - `arn:aws:ssm:${config.awsRegion}:${config.awsAccount}:parameter/${config.projectPrefix}/*`, - ], - }) - ); - - // Grant ECR read permissions - runtimeUpdaterFunction.addToRolePolicy( - new iam.PolicyStatement({ - sid: "ECRReadAccessForUpdater", - effect: iam.Effect.ALLOW, - actions: [ - "ecr:DescribeRepositories", - "ecr:DescribeImages", - "ecr:GetAuthorizationToken", - ], - resources: ["*"], // ECR authorization token requires wildcard - }) - ); - - // Grant SNS Publish permissions - runtimeUpdateAlertsTopic.grantPublish(runtimeUpdaterFunction); - - // Create EventBridge rule to detect SSM parameter changes - const imageTagChangeRule = new events.Rule(this, "ImageTagChangeRule", { - ruleName: getResourceName(config, "image-tag-change"), - description: "Triggers Runtime Updater when inference API image tag changes", - eventPattern: { - source: ["aws.ssm"], - detailType: ["Parameter Store Change"], - detail: { - name: [`/${config.projectPrefix}/inference-api/image-tag`], - operation: ["Update"], - }, - }, - }); - - // Add Lambda as target for EventBridge rule - imageTagChangeRule.addTarget(new targets.LambdaFunction(runtimeUpdaterFunction)); - - // Store Lambda function ARN in SSM - new ssm.StringParameter(this, "RuntimeUpdaterFunctionArnParameter", { - parameterName: `/${config.projectPrefix}/lambda/runtime-updater-arn`, - stringValue: runtimeUpdaterFunction.functionArn, - description: "Runtime Updater Lambda function ARN", - tier: ssm.ParameterTier.STANDARD, - }); - - // Store SNS topic ARN in SSM - new ssm.StringParameter(this, "RuntimeUpdateAlertsTopicArnParameter", { - parameterName: `/${config.projectPrefix}/sns/runtime-update-alerts-arn`, - stringValue: runtimeUpdateAlertsTopic.topicArn, - description: "SNS topic ARN for runtime update alerts", - tier: ssm.ParameterTier.STANDARD, - }); - // Grant permissions for AgentCore Memory (imported from InferenceApiStack) const memoryArn = ssm.StringParameter.valueForStringParameter( this, @@ -1657,22 +1390,5 @@ export class AppApiStack extends cdk.Stack { exportName: `${config.projectPrefix}-OAuthClientSecretsSecretArn`, }); - new cdk.CfnOutput(this, "RuntimeProvisionerFunctionArn", { - value: runtimeProvisionerFunction.functionArn, - description: "Runtime Provisioner Lambda function ARN", - exportName: `${config.projectPrefix}-RuntimeProvisionerFunctionArn`, - }); - - new cdk.CfnOutput(this, "RuntimeUpdaterFunctionArn", { - value: runtimeUpdaterFunction.functionArn, - description: "Runtime Updater Lambda function ARN", - exportName: `${config.projectPrefix}-RuntimeUpdaterFunctionArn`, - }); - - new cdk.CfnOutput(this, "RuntimeUpdateAlertsTopicArn", { - value: runtimeUpdateAlertsTopic.topicArn, - description: "SNS topic ARN for runtime update alerts", - exportName: `${config.projectPrefix}-RuntimeUpdateAlertsTopicArn`, - }); } } diff --git a/infrastructure/lib/config.ts b/infrastructure/lib/config.ts index c6249477..f2fa94dd 100644 --- a/infrastructure/lib/config.ts +++ b/infrastructure/lib/config.ts @@ -1,5 +1,12 @@ import * as cdk from 'aws-cdk-lib'; +export interface CognitoConfig { + domainPrefix?: string; // Custom Cognito domain prefix (defaults to projectPrefix) + callbackUrls?: string[]; // Additional callback URLs beyond auto-derived + logoutUrls?: string[]; // Additional logout URLs beyond auto-derived + passwordMinLength?: number; // Override default 8 +} + export interface AppConfig { projectPrefix: string; awsAccount: string; @@ -12,6 +19,7 @@ export interface AppConfig { infrastructureHostedZoneDomain?: string; albSubdomain?: string; // Subdomain for ALB (e.g., 'api' for api.yourdomain.com) certificateArn?: string; // ACM certificate ARN for HTTPS on ALB + cognito: CognitoConfig; frontend: FrontendConfig; appApi: AppApiConfig; inferenceApi: InferenceApiConfig; @@ -29,11 +37,12 @@ export interface FrontendConfig { enabled: boolean; bucketName?: string; cloudFrontPriceClass: string; + additionalCorsOrigins?: string; // Extra CORS origins to append (comma-separated) } export interface AssistantsConfig { enabled: boolean; - corsOrigins: string; + additionalCorsOrigins?: string; // Extra CORS origins to append (comma-separated) } export interface AppApiConfig { @@ -43,6 +52,7 @@ export interface AppApiConfig { desiredCount: number; maxCapacity: number; imageTag: string; + additionalCorsOrigins?: string; // Extra CORS origins to append (comma-separated) } export interface InferenceApiConfig { @@ -54,7 +64,7 @@ export interface InferenceApiConfig { imageTag: string; // Environment variables for runtime container logLevel: string; - corsOrigins: string; + additionalCorsOrigins?: string; // Extra CORS origins to append (comma-separated) } export interface GatewayConfig { @@ -72,12 +82,12 @@ export interface FileUploadConfig { maxFilesPerMessage: number; // Maximum files per message (default: 5) userQuotaBytes: number; // Per-user storage quota (default: 1GB) retentionDays: number; // File retention (default: 365 days) - corsOrigins?: string; // Comma-separated CORS origins (defaults based on environment) + additionalCorsOrigins?: string; // Extra CORS origins to append (comma-separated) } export interface RagIngestionConfig { enabled: boolean; // Enable/disable RAG stack - corsOrigins: string; // Comma-separated CORS origins + additionalCorsOrigins?: string; // Extra CORS origins to append (comma-separated) lambdaMemorySize: number; // Lambda memory in MB (default: 3008) lambdaTimeout: number; // Lambda timeout in seconds (default: 900) embeddingModel: string; // Bedrock model ID (default: "amazon.titan-embed-text-v2") @@ -88,6 +98,7 @@ export interface RagIngestionConfig { export interface FineTuningConfig { enabled: boolean; // Enable/disable SageMaker Fine-Tuning stack defaultQuotaHours: number; // Default monthly GPU-hour quota for all users (0 = whitelist-only) + additionalCorsOrigins?: string; // Extra CORS origins to append (comma-separated) } /** @@ -135,12 +146,21 @@ export function loadConfig(scope: cdk.App): AppConfig { validateAwsAccount(awsAccount); validateAwsRegion(awsRegion); - // Top-level shared CORS origins — used as default for sections that don't override. - // If not explicitly set, auto-derive from CDK_DOMAIN_NAME so callers only need one variable. + // Top-level shared CORS origins — always includes https://{domainName} when set. + // CDK_CORS_ORIGINS provides ADDITIONAL origins on top of the domain. const domainName = process.env.CDK_DOMAIN_NAME || scope.node.tryGetContext('domainName'); - const corsOrigins = process.env.CDK_CORS_ORIGINS + const extraCorsOrigins = process.env.CDK_CORS_ORIGINS || scope.node.tryGetContext('corsOrigins') - || (domainName ? `https://${domainName}` : ''); + || ''; + // Build corsOrigins: domain-derived origin first, then any extras + const corsOriginParts: string[] = []; + if (domainName) { + corsOriginParts.push(`https://${domainName}`); + } + if (extraCorsOrigins) { + corsOriginParts.push(extraCorsOrigins); + } + const corsOrigins = corsOriginParts.join(','); // Load app version from environment variable or CDK context const appVersion = process.env.CDK_APP_VERSION || scope.node.tryGetContext('appVersion') || 'unknown'; @@ -158,11 +178,24 @@ export function loadConfig(scope: cdk.App): AppConfig { infrastructureHostedZoneDomain: process.env.CDK_HOSTED_ZONE_DOMAIN || scope.node.tryGetContext('infrastructureHostedZoneDomain'), albSubdomain: process.env.CDK_ALB_SUBDOMAIN || scope.node.tryGetContext('albSubdomain'), certificateArn: process.env.CDK_CERTIFICATE_ARN || scope.node.tryGetContext('certificateArn'), + cognito: { + domainPrefix: process.env.CDK_COGNITO_DOMAIN_PREFIX + || scope.node.tryGetContext('cognito')?.domainPrefix + || projectPrefix, + callbackUrls: process.env.CDK_COGNITO_CALLBACK_URLS?.split(',') + || scope.node.tryGetContext('cognito')?.callbackUrls, + logoutUrls: process.env.CDK_COGNITO_LOGOUT_URLS?.split(',') + || scope.node.tryGetContext('cognito')?.logoutUrls, + passwordMinLength: parseIntEnv(process.env.CDK_COGNITO_PASSWORD_MIN_LENGTH) + || scope.node.tryGetContext('cognito')?.passwordMinLength + || 8, + }, frontend: { certificateArn: process.env.CDK_FRONTEND_CERTIFICATE_ARN || scope.node.tryGetContext('frontend').certificateArn, enabled: parseBooleanEnv(process.env.CDK_FRONTEND_ENABLED) ?? scope.node.tryGetContext('frontend')?.enabled, bucketName: process.env.CDK_FRONTEND_BUCKET_NAME || scope.node.tryGetContext('frontend')?.bucketName, cloudFrontPriceClass: process.env.CDK_FRONTEND_CLOUDFRONT_PRICE_CLASS || scope.node.tryGetContext('frontend')?.cloudFrontPriceClass, + additionalCorsOrigins: process.env.CDK_FRONTEND_CORS_ORIGINS || scope.node.tryGetContext('frontend')?.additionalCorsOrigins, }, appApi: { enabled: parseBooleanEnv(process.env.CDK_APP_API_ENABLED) ?? scope.node.tryGetContext('appApi')?.enabled, @@ -171,6 +204,7 @@ export function loadConfig(scope: cdk.App): AppConfig { desiredCount: parseIntEnv(process.env.CDK_APP_API_DESIRED_COUNT) ?? scope.node.tryGetContext('appApi')?.desiredCount, imageTag: scope.node.tryGetContext('imageTag') || '', maxCapacity: parseIntEnv(process.env.CDK_APP_API_MAX_CAPACITY) || scope.node.tryGetContext('appApi')?.maxCapacity, + additionalCorsOrigins: process.env.CDK_APP_API_CORS_ORIGINS || scope.node.tryGetContext('appApi')?.additionalCorsOrigins, }, inferenceApi: { enabled: parseBooleanEnv(process.env.CDK_INFERENCE_API_ENABLED) ?? scope.node.tryGetContext('inferenceApi')?.enabled, @@ -181,7 +215,7 @@ export function loadConfig(scope: cdk.App): AppConfig { imageTag: scope.node.tryGetContext('imageTag') || '', // Environment variables from GitHub Secrets/Variables with context fallback logLevel: process.env.ENV_INFERENCE_API_LOG_LEVEL || scope.node.tryGetContext('inferenceApi')?.logLevel, - corsOrigins: process.env.ENV_INFERENCE_API_CORS_ORIGINS || scope.node.tryGetContext('inferenceApi')?.corsOrigins, + additionalCorsOrigins: process.env.CDK_INFERENCE_API_CORS_ORIGINS || scope.node.tryGetContext('inferenceApi')?.additionalCorsOrigins, }, gateway: { enabled: parseBooleanEnv(process.env.CDK_GATEWAY_ENABLED) ?? scope.node.tryGetContext('gateway')?.enabled, @@ -197,15 +231,15 @@ export function loadConfig(scope: cdk.App): AppConfig { maxFilesPerMessage: parseIntEnv(process.env.CDK_FILE_UPLOAD_MAX_FILES_PER_MESSAGE) || scope.node.tryGetContext('fileUpload')?.maxFilesPerMessage, userQuotaBytes: parseIntEnv(process.env.CDK_FILE_UPLOAD_USER_QUOTA) || scope.node.tryGetContext('fileUpload')?.userQuotaBytes, retentionDays: parseIntEnv(process.env.CDK_FILE_UPLOAD_RETENTION_DAYS) || scope.node.tryGetContext('fileUpload')?.retentionDays, - corsOrigins: process.env.CDK_FILE_UPLOAD_CORS_ORIGINS || scope.node.tryGetContext('fileUpload')?.corsOrigins || corsOrigins, + additionalCorsOrigins: process.env.CDK_FILE_UPLOAD_CORS_ORIGINS || scope.node.tryGetContext('fileUpload')?.additionalCorsOrigins, }, assistants: { enabled: parseBooleanEnv(process.env.CDK_ASSISTANTS_ENABLED) ?? scope.node.tryGetContext('assistants')?.enabled, - corsOrigins: process.env.CDK_ASSISTANTS_CORS_ORIGINS || scope.node.tryGetContext('assistants')?.corsOrigins || corsOrigins, + additionalCorsOrigins: process.env.CDK_ASSISTANTS_CORS_ORIGINS || scope.node.tryGetContext('assistants')?.additionalCorsOrigins, }, ragIngestion: { enabled: parseBooleanEnv(process.env.CDK_RAG_ENABLED) ?? scope.node.tryGetContext('ragIngestion')?.enabled, - corsOrigins: process.env.CDK_RAG_CORS_ORIGINS || scope.node.tryGetContext('ragIngestion')?.corsOrigins || corsOrigins, + additionalCorsOrigins: process.env.CDK_RAG_CORS_ORIGINS || scope.node.tryGetContext('ragIngestion')?.additionalCorsOrigins, lambdaMemorySize: parseIntEnv(process.env.CDK_RAG_LAMBDA_MEMORY) || scope.node.tryGetContext('ragIngestion')?.lambdaMemorySize, lambdaTimeout: parseIntEnv(process.env.CDK_RAG_LAMBDA_TIMEOUT) || scope.node.tryGetContext('ragIngestion')?.lambdaTimeout, embeddingModel: process.env.CDK_RAG_EMBEDDING_MODEL || scope.node.tryGetContext('ragIngestion')?.embeddingModel, @@ -215,6 +249,7 @@ export function loadConfig(scope: cdk.App): AppConfig { fineTuning: { enabled: parseBooleanEnv(process.env.CDK_FINE_TUNING_ENABLED) ?? scope.node.tryGetContext('fineTuning')?.enabled ?? false, defaultQuotaHours: parseIntEnv(process.env.CDK_FINE_TUNING_DEFAULT_QUOTA_HOURS) ?? scope.node.tryGetContext('fineTuning')?.defaultQuotaHours ?? 0, + additionalCorsOrigins: process.env.CDK_FINE_TUNING_CORS_ORIGINS || scope.node.tryGetContext('fineTuning')?.additionalCorsOrigins, }, tags: { ...(scope.node.tryGetContext('tags') || {}), @@ -389,11 +424,11 @@ function validateConfig(config: AppConfig): void { } // Validate CORS origins if provided - if (config.ragIngestion.corsOrigins) { - const origins = config.ragIngestion.corsOrigins.split(',').map(o => o.trim()); + if (config.corsOrigins) { + const origins = config.corsOrigins.split(',').map(o => o.trim()); origins.forEach(origin => { if (origin && !origin.startsWith('http://') && !origin.startsWith('https://') && origin !== '*') { - console.warn(`Warning: RAG CORS origin '${origin}' should start with http:// or https:// or be '*'`); + console.warn(`Warning: CORS origin '${origin}' should start with http:// or https:// or be '*'`); } }); } @@ -410,14 +445,11 @@ function validateConfig(config: AppConfig): void { } // Validate File Upload CORS origins - if (config.fileUpload.enabled) { - const effectiveCors = config.fileUpload.corsOrigins || config.corsOrigins || config.domainName; - if (!effectiveCors || effectiveCors.trim() === '') { - throw new Error( - 'File Upload stack requires CORS origins to be configured. ' + - 'Set CDK_DOMAIN_NAME, CDK_CORS_ORIGINS, or corsOrigins in the fileUpload section.' - ); - } + if (config.fileUpload.enabled && !config.corsOrigins) { + console.warn( + 'Warning: File Upload is enabled but no CORS origins configured. ' + + 'Set CDK_DOMAIN_NAME or CDK_CORS_ORIGINS to enable browser uploads.' + ); } // Validate required fields for all enabled stacks @@ -540,3 +572,32 @@ export function applyStandardTags(stack: cdk.Stack, config: AppConfig): void { cdk.Tags.of(stack).add(key, value); }); } + +/** + * Build the canonical CORS origins list for a stack. + * + * Always includes: + * 1. https://{CDK_DOMAIN_NAME} (from config.corsOrigins) + * + * Optionally appends extra origins from: + * - CDK_CORS_ORIGINS (already merged into config.corsOrigins) + * - additionalOrigins parameter (section-specific CDK_*_CORS_ORIGINS) + * + * localhost is NOT auto-included. Add it via CDK_CORS_ORIGINS for local dev. + * + * Returns a de-duplicated array suitable for S3 CORS rules or + * a comma-joined string for container env vars. + * + * @param config The top-level AppConfig + * @param additionalOrigins Optional comma-separated extra origins to append + */ +export function buildCorsOrigins(config: AppConfig, additionalOrigins?: string): string[] { + const origins = new Set(); + if (config.corsOrigins) { + config.corsOrigins.split(',').map(o => o.trim()).filter(Boolean).forEach(o => origins.add(o)); + } + if (additionalOrigins) { + additionalOrigins.split(',').map(o => o.trim()).filter(Boolean).forEach(o => origins.add(o)); + } + return Array.from(origins); +} diff --git a/infrastructure/lib/frontend-stack.ts b/infrastructure/lib/frontend-stack.ts index 579a43cd..017ba11d 100644 --- a/infrastructure/lib/frontend-stack.ts +++ b/infrastructure/lib/frontend-stack.ts @@ -10,7 +10,7 @@ import * as acm from 'aws-cdk-lib/aws-certificatemanager'; import * as lambda from 'aws-cdk-lib/aws-lambda'; import * as iam from 'aws-cdk-lib/aws-iam'; import { Construct } from 'constructs'; -import { AppConfig, getResourceName, applyStandardTags, getRemovalPolicy, getAutoDeleteObjects } from './config'; +import { AppConfig, getResourceName, applyStandardTags, getRemovalPolicy, getAutoDeleteObjects, buildCorsOrigins } from './config'; export interface FrontendStackProps extends cdk.StackProps { config: AppConfig; @@ -72,9 +72,33 @@ export class FrontendStack extends cdk.Stack { ); } + // ============================================================================ + // SSM Parameter Imports - Cognito Configuration + // ============================================================================ + // These parameters are exported by InfrastructureStack (Cognito User Pool) + // and InferenceApiStack (Runtime endpoint URL). + // ============================================================================ + + const cognitoDomainUrl = ssm.StringParameter.valueForStringParameter( + this, + `/${config.projectPrefix}/auth/cognito/domain-url` + ); + + const cognitoAppClientId = ssm.StringParameter.valueForStringParameter( + this, + `/${config.projectPrefix}/auth/cognito/app-client-id` + ); + + const inferenceApiUrl = ssm.StringParameter.valueForStringParameter( + this, + `/${config.projectPrefix}/inference-api/runtime-endpoint-url` + ); + // Log imported values for debugging (values will be tokens at synth time) console.log('📥 Imported backend URLs from SSM:'); console.log(` App API URL: ${appApiUrl}`); + console.log(` Cognito Domain URL: ${cognitoDomainUrl}`); + console.log(` Inference API URL: ${inferenceApiUrl}`); // ============================================================================ // Runtime Configuration Generation @@ -91,6 +115,10 @@ export class FrontendStack extends cdk.Stack { appApiUrl: appApiUrl, environment: config.production ? 'production' : 'development', version: config.appVersion, + cognitoDomainUrl: cognitoDomainUrl, + cognitoAppClientId: cognitoAppClientId, + cognitoRegion: config.awsRegion, + inferenceApiUrl: inferenceApiUrl, }; console.log('🔧 Generated runtime configuration:'); @@ -304,18 +332,18 @@ export class FrontendStack extends cdk.Stack { tier: ssm.ParameterTier.STANDARD, }); - // Construct CORS origins list - const corsOrigins = config.domainName - ? `https://${config.domainName}` - : `https://${this.distributionDomainName}`; + // Construct CORS origins list via shared helper + const corsOrigins = buildCorsOrigins(config, config.frontend.additionalCorsOrigins).join(','); - // Export CORS origins for runtime provisioner - new ssm.StringParameter(this, 'CorsOriginsParameter', { - parameterName: `/${config.projectPrefix}/frontend/cors-origins`, - stringValue: corsOrigins, - description: 'Comma-separated list of allowed CORS origins for OAuth flows', - tier: ssm.ParameterTier.STANDARD, - }); + // Export CORS origins for runtime provisioner (SSM rejects empty string values) + if (corsOrigins) { + new ssm.StringParameter(this, 'CorsOriginsParameter', { + parameterName: `/${config.projectPrefix}/frontend/cors-origins`, + stringValue: corsOrigins, + description: 'Comma-separated list of allowed CORS origins for OAuth flows', + tier: ssm.ParameterTier.STANDARD, + }); + } new ssm.StringParameter(this, 'BucketNameParameter', { parameterName: `/${config.projectPrefix}/frontend/bucket-name`, @@ -378,7 +406,7 @@ def handler(event, context): 'AllowedOrigins': [frontend_url, 'http://localhost:4200'], 'AllowedMethods': ['GET', 'PUT', 'HEAD'], 'AllowedHeaders': ['Content-Type', 'Content-Length', 'x-amz-*'], - 'ExposedHeaders': ['ETag', 'Content-Length', 'Content-Type'], + 'ExposeHeaders': ['ETag', 'Content-Length', 'Content-Type'], 'MaxAgeSeconds': 3600 }) diff --git a/infrastructure/lib/inference-api-stack.ts b/infrastructure/lib/inference-api-stack.ts index 29f6b25c..38054159 100644 --- a/infrastructure/lib/inference-api-stack.ts +++ b/infrastructure/lib/inference-api-stack.ts @@ -7,7 +7,7 @@ import * as cloudwatch from 'aws-cdk-lib/aws-cloudwatch'; import * as xray from 'aws-cdk-lib/aws-xray'; import * as bedrock from 'aws-cdk-lib/aws-bedrockagentcore'; import { Construct } from 'constructs'; -import { AppConfig, getResourceName, getTruncatedResourceName, applyStandardTags } from './config'; +import { AppConfig, getResourceName, getTruncatedResourceName, applyStandardTags, buildCorsOrigins } from './config'; export interface InferenceApiStackProps extends cdk.StackProps { config: AppConfig; @@ -17,18 +17,19 @@ export interface InferenceApiStackProps extends cdk.StackProps { * Inference API Stack - AWS Bedrock AgentCore Shared Resources * * This stack creates shared resources used by all AgentCore Runtimes: + * - Single CDK-managed AgentCore Runtime with Cognito JWT Authorizer * - AgentCore Memory for conversation context and memory * - Code Interpreter Custom for Python code execution * - Browser Custom for web browsing capabilities * - IAM roles with appropriate permissions * - * Note: Individual runtimes are created dynamically by Lambda when auth providers are added. * Note: ECR repository is created by the build pipeline, not by CDK. */ export class InferenceApiStack extends cdk.Stack { public readonly memory: bedrock.CfnMemory; public readonly codeInterpreter: bedrock.CfnCodeInterpreterCustom; public readonly browser: bedrock.CfnBrowserCustom; + public readonly runtime: bedrock.CfnRuntime; constructor(scope: Construct, id: string, props: InferenceApiStackProps) { super(scope, id, props); @@ -150,6 +151,19 @@ export class InferenceApiStack extends cdk.Stack { ], })); + // AWS Marketplace permissions required for Bedrock model access + // Some foundation models (e.g., Anthropic Claude) require marketplace + // subscription validation before invocation is allowed. + runtimeExecutionRole.addToPolicy(new iam.PolicyStatement({ + sid: 'MarketplaceModelAccess', + effect: iam.Effect.ALLOW, + actions: [ + 'aws-marketplace:ViewSubscriptions', + 'aws-marketplace:Subscribe', + ], + resources: ['*'], + })); + // External MCP Lambda Function URL permissions (for external MCP tools with aws-iam auth) // This allows the runtime to invoke Lambda Function URLs that require IAM authentication // Scoped to mcp-* functions following the naming convention from mcp-servers repo @@ -782,6 +796,168 @@ export class InferenceApiStack extends cdk.Stack { resources: [this.browser.attrBrowserArn], })); + // ============================================================ + // Import Cognito SSM Parameters for JWT Authorizer + // ============================================================ + + const cognitoUserPoolId = ssm.StringParameter.valueForStringParameter( + this, `/${config.projectPrefix}/auth/cognito/user-pool-id` + ); + const cognitoAppClientId = ssm.StringParameter.valueForStringParameter( + this, `/${config.projectPrefix}/auth/cognito/app-client-id` + ); + + // Construct Cognito OIDC discovery URL + const cognitoDiscoveryUrl = `https://cognito-idp.${config.awsRegion}.amazonaws.com/${cognitoUserPoolId}/.well-known/openid-configuration`; + + // ============================================================ + // Import SSM Parameters for Runtime Environment Variables + // ============================================================ + + // DynamoDB table names (the ARNs are already imported above for IAM) + const usersTableName = ssm.StringParameter.valueForStringParameter( + this, `/${config.projectPrefix}/users/users-table-name` + ); + const appRolesTableName = ssm.StringParameter.valueForStringParameter( + this, `/${config.projectPrefix}/rbac/app-roles-table-name` + ); + const oidcStateTableName = ssm.StringParameter.valueForStringParameter( + this, `/${config.projectPrefix}/auth/oidc-state-table-name` + ); + const apiKeysTableName = ssm.StringParameter.valueForStringParameter( + this, `/${config.projectPrefix}/auth/api-keys-table-name` + ); + const oauthProvidersTableName = ssm.StringParameter.valueForStringParameter( + this, `/${config.projectPrefix}/oauth/providers-table-name` + ); + const oauthUserTokensTableName = ssm.StringParameter.valueForStringParameter( + this, `/${config.projectPrefix}/oauth/user-tokens-table-name` + ); + const assistantsTableName = ssm.StringParameter.valueForStringParameter( + this, `/${config.projectPrefix}/rag/assistants-table-name` + ); + const userQuotasTableName = ssm.StringParameter.valueForStringParameter( + this, `/${config.projectPrefix}/quota/user-quotas-table-name` + ); + const quotaEventsTableName = ssm.StringParameter.valueForStringParameter( + this, `/${config.projectPrefix}/quota/quota-events-table-name` + ); + const sessionsMetadataTableName = ssm.StringParameter.valueForStringParameter( + this, `/${config.projectPrefix}/cost-tracking/sessions-metadata-table-name` + ); + const userCostSummaryTableName = ssm.StringParameter.valueForStringParameter( + this, `/${config.projectPrefix}/cost-tracking/user-cost-summary-table-name` + ); + const systemCostRollupTableName = ssm.StringParameter.valueForStringParameter( + this, `/${config.projectPrefix}/cost-tracking/system-cost-rollup-table-name` + ); + const managedModelsTableName = ssm.StringParameter.valueForStringParameter( + this, `/${config.projectPrefix}/admin/managed-models-table-name` + ); + const userSettingsTableName = ssm.StringParameter.valueForStringParameter( + this, `/${config.projectPrefix}/settings/user-settings-table-name` + ); + const authProvidersTableName = ssm.StringParameter.valueForStringParameter( + this, `/${config.projectPrefix}/auth/auth-providers-table-name` + ); + const userFilesTableName = ssm.StringParameter.valueForStringParameter( + this, `/${config.projectPrefix}/user-file-uploads/table-name` + ); + + // S3 / RAG + const vectorBucketName = ssm.StringParameter.valueForStringParameter( + this, `/${config.projectPrefix}/rag/vector-bucket-name` + ); + const vectorIndexName = ssm.StringParameter.valueForStringParameter( + this, `/${config.projectPrefix}/rag/vector-index-name` + ); + + // Frontend CORS origins — single source: buildCorsOrigins (from CDK_DOMAIN_NAME) + const corsOrigins = buildCorsOrigins(config, config.inferenceApi.additionalCorsOrigins).join(','); + + // ============================================================ + // Single CDK-Managed AgentCore Runtime with Cognito JWT Authorizer + // ============================================================ + + this.runtime = new bedrock.CfnRuntime(this, 'AgentCoreRuntime', { + agentRuntimeName: getResourceName(config, 'agentcore_runtime').replace(/-/g, '_'), + agentRuntimeArtifact: { + containerConfiguration: { + containerUri: _containerImageUri, + }, + }, + authorizerConfiguration: { + customJwtAuthorizer: { + discoveryUrl: cognitoDiscoveryUrl, + allowedClients: [cognitoAppClientId], + }, + }, + roleArn: runtimeExecutionRole.roleArn, + networkConfiguration: { + networkMode: 'PUBLIC', + }, + requestHeaderConfiguration: { + requestHeaderAllowlist: ['Authorization'], + }, + environmentVariables: { + // Basic configuration + LOG_LEVEL: 'INFO', + PROJECT_PREFIX: config.projectPrefix, + AWS_DEFAULT_REGION: config.awsRegion, + + // DynamoDB tables + DYNAMODB_USERS_TABLE_NAME: usersTableName, + DYNAMODB_APP_ROLES_TABLE_NAME: appRolesTableName, + DYNAMODB_OIDC_STATE_TABLE_NAME: oidcStateTableName, + DYNAMODB_API_KEYS_TABLE_NAME: apiKeysTableName, + DYNAMODB_OAUTH_PROVIDERS_TABLE_NAME: oauthProvidersTableName, + DYNAMODB_OAUTH_USER_TOKENS_TABLE_NAME: oauthUserTokensTableName, + DYNAMODB_ASSISTANTS_TABLE_NAME: assistantsTableName, + + // Quota & cost tracking tables + DYNAMODB_QUOTA_TABLE: userQuotasTableName, + DYNAMODB_QUOTA_EVENTS_TABLE: quotaEventsTableName, + DYNAMODB_SESSIONS_METADATA_TABLE_NAME: sessionsMetadataTableName, + DYNAMODB_COST_SUMMARY_TABLE_NAME: userCostSummaryTableName, + DYNAMODB_SYSTEM_ROLLUP_TABLE_NAME: systemCostRollupTableName, + DYNAMODB_MANAGED_MODELS_TABLE_NAME: managedModelsTableName, + DYNAMODB_USER_SETTINGS_TABLE_NAME: userSettingsTableName, + DYNAMODB_USER_FILES_TABLE_NAME: userFilesTableName, + + // Auth providers + DYNAMODB_AUTH_PROVIDERS_TABLE_NAME: authProvidersTableName, + AUTH_PROVIDER_SECRETS_ARN: authProviderSecretsArn, + + // OAuth configuration + OAUTH_TOKEN_ENCRYPTION_KEY_ARN: oauthTokenEncryptionKeyArn, + OAUTH_CLIENT_SECRETS_ARN: oauthClientSecretsArn, + + // AgentCore resources + AGENTCORE_MEMORY_ID: this.memory.attrMemoryId, + MEMORY_ARN: this.memory.attrMemoryArn, + AGENTCORE_CODE_INTERPRETER_ID: this.codeInterpreter.attrCodeInterpreterId, + BROWSER_ID: this.browser.attrBrowserId, + + // S3 storage + S3_ASSISTANTS_VECTOR_STORE_BUCKET_NAME: vectorBucketName, + S3_ASSISTANTS_VECTOR_STORE_INDEX_NAME: vectorIndexName, + + // Authentication + ENABLE_AUTHENTICATION: 'true', + ENABLE_QUOTA_ENFORCEMENT: 'true', + + // Directories + UPLOAD_DIR: '/tmp/uploads', + OUTPUT_DIR: '/tmp/output', + GENERATED_IMAGES_DIR: '/tmp/generated_images', + + // URLs + FRONTEND_URL: config.domainName ? `https://${config.domainName}` : 'http://localhost:4200', + CORS_ORIGINS: corsOrigins, + }, + }); + this.runtime.node.addDependency(runtimeExecutionRole); + // ============================================================ // Observability: CloudWatch Log Group for Runtime // ============================================================ @@ -801,8 +977,6 @@ export class InferenceApiStack extends cdk.Stack { // ============================================================ // Uses CloudWatch Logs vended logs API (CfnDeliverySource/Destination/Delivery) // to configure APPLICATION_LOGS and TRACES for CDK-managed resources. - // Runtime log deliveries are configured in the runtime-provisioner Lambda - // since runtimes are created dynamically per auth provider. // --- Memory: APPLICATION_LOGS --- const memoryLogsLogGroup = new logs.LogGroup(this, 'MemoryLogsLogGroup', { @@ -1028,6 +1202,33 @@ export class InferenceApiStack extends cdk.Stack { description: 'Runtime execution role ARN for Lambda-created AgentCore Runtimes', tier: ssm.ParameterTier.STANDARD, }); + + new ssm.StringParameter(this, 'RuntimeArnParameter', { + parameterName: `/${config.projectPrefix}/inference-api/runtime-arn`, + stringValue: this.runtime.attrAgentRuntimeArn, + description: 'AgentCore Runtime ARN', + tier: ssm.ParameterTier.STANDARD, + }); + + new ssm.StringParameter(this, 'RuntimeIdParameter', { + parameterName: `/${config.projectPrefix}/inference-api/runtime-id`, + stringValue: this.runtime.attrAgentRuntimeId, + description: 'AgentCore Runtime ID', + tier: ssm.ParameterTier.STANDARD, + }); + + // Construct the full runtime endpoint URL for frontend consumption + const runtimeEndpointUrl = cdk.Fn.sub( + 'https://bedrock-agentcore.${AWS::Region}.amazonaws.com/runtimes/${RuntimeArn}', + { RuntimeArn: this.runtime.attrAgentRuntimeArn } + ); + + new ssm.StringParameter(this, 'InferenceApiRuntimeEndpointUrlParameter', { + parameterName: `/${config.projectPrefix}/inference-api/runtime-endpoint-url`, + stringValue: runtimeEndpointUrl, + description: 'Inference API AgentCore Runtime Endpoint URL', + tier: ssm.ParameterTier.STANDARD, + }); new ssm.StringParameter(this, 'InferenceApiMemoryArnParameter', { parameterName: `/${config.projectPrefix}/inference-api/memory-arn`, @@ -1098,6 +1299,18 @@ export class InferenceApiStack extends cdk.Stack { exportName: `${config.projectPrefix}-InferenceApiMemoryArn`, }); + new cdk.CfnOutput(this, 'AgentCoreRuntimeArn', { + value: this.runtime.attrAgentRuntimeArn, + description: 'AgentCore Runtime ARN', + exportName: `${config.projectPrefix}-AgentCoreRuntimeArn`, + }); + + new cdk.CfnOutput(this, 'AgentCoreRuntimeId', { + value: this.runtime.attrAgentRuntimeId, + description: 'AgentCore Runtime ID', + exportName: `${config.projectPrefix}-AgentCoreRuntimeId`, + }); + new cdk.CfnOutput(this, 'InferenceApiMemoryId', { value: this.memory.attrMemoryId, description: 'Inference API AgentCore Memory ID', diff --git a/infrastructure/lib/infrastructure-stack.ts b/infrastructure/lib/infrastructure-stack.ts index 6442755c..777b857d 100644 --- a/infrastructure/lib/infrastructure-stack.ts +++ b/infrastructure/lib/infrastructure-stack.ts @@ -1,5 +1,6 @@ import * as cdk from 'aws-cdk-lib'; import * as acm from 'aws-cdk-lib/aws-certificatemanager'; +import * as cognito from 'aws-cdk-lib/aws-cognito'; import * as dynamodb from 'aws-cdk-lib/aws-dynamodb'; import * as ec2 from 'aws-cdk-lib/aws-ec2'; import * as elbv2 from 'aws-cdk-lib/aws-elasticloadbalancingv2'; @@ -11,7 +12,7 @@ import * as s3 from 'aws-cdk-lib/aws-s3'; import * as secretsmanager from 'aws-cdk-lib/aws-secretsmanager'; import * as ssm from 'aws-cdk-lib/aws-ssm'; import { Construct } from 'constructs'; -import { AppConfig, getResourceName, applyStandardTags, getRemovalPolicy, getAutoDeleteObjects } from './config'; +import { AppConfig, getResourceName, applyStandardTags, getRemovalPolicy, getAutoDeleteObjects, buildCorsOrigins } from './config'; export interface InfrastructureStackProps extends cdk.StackProps { config: AppConfig; @@ -1072,6 +1073,118 @@ export class InfrastructureStack extends cdk.Stack { tier: ssm.ParameterTier.STANDARD, }); + // ============================================================ + // Cognito User Pool (Identity Broker) + // ============================================================ + // Central identity broker for all authentication. Federates to + // external IdPs (Entra ID, Okta, Google) and issues its own JWTs. + // Self-signup is enabled initially for first-boot; the App API + // disables it after the first admin user is created. + + const userPool = new cognito.UserPool(this, 'CognitoUserPool', { + userPoolName: getResourceName(config, 'user-pool'), + selfSignUpEnabled: true, + signInAliases: { username: true, email: true }, + autoVerify: { email: true }, + standardAttributes: { + email: { required: true, mutable: true }, + givenName: { mutable: true }, + familyName: { mutable: true }, + }, + customAttributes: { + 'provider_sub': new cognito.StringAttribute({ mutable: true }), + 'roles': new cognito.StringAttribute({ mutable: true }), + }, + passwordPolicy: { + minLength: config.cognito.passwordMinLength || 8, + requireUppercase: true, + requireLowercase: true, + requireDigits: true, + requireSymbols: true, + }, + accountRecovery: cognito.AccountRecovery.EMAIL_ONLY, + removalPolicy: getRemovalPolicy(config), + }); + + // App Client — SPA, no client secret, authorization code grant with PKCE + const callbackUrls = config.domainName + ? [`https://${config.domainName}/auth/callback`] + : ['http://localhost:4200/auth/callback']; + const logoutUrls = config.domainName + ? [`https://${config.domainName}`] + : ['http://localhost:4200']; + + // Append any additional callback/logout URLs from config + if (config.cognito.callbackUrls) { + callbackUrls.push(...config.cognito.callbackUrls); + } + if (config.cognito.logoutUrls) { + logoutUrls.push(...config.cognito.logoutUrls); + } + + const appClient = userPool.addClient('CognitoAppClient', { + userPoolClientName: getResourceName(config, 'app-client'), + generateSecret: false, + authFlows: { userSrp: true, custom: true }, + oAuth: { + flows: { authorizationCodeGrant: true }, + scopes: [ + cognito.OAuthScope.OPENID, + cognito.OAuthScope.PROFILE, + cognito.OAuthScope.EMAIL, + ], + callbackUrls, + logoutUrls, + }, + preventUserExistenceErrors: true, + supportedIdentityProviders: [ + cognito.UserPoolClientIdentityProvider.COGNITO, + ], + }); + + // Cognito Domain — prefix-based using project prefix or override + const cognitoDomain = userPool.addDomain('CognitoDomain', { + cognitoDomain: { + domainPrefix: config.cognito.domainPrefix || config.projectPrefix, + }, + }); + + // Cognito SSM Exports + new ssm.StringParameter(this, 'CognitoUserPoolIdParameter', { + parameterName: `/${config.projectPrefix}/auth/cognito/user-pool-id`, + stringValue: userPool.userPoolId, + description: 'Cognito User Pool ID', + tier: ssm.ParameterTier.STANDARD, + }); + + new ssm.StringParameter(this, 'CognitoUserPoolArnParameter', { + parameterName: `/${config.projectPrefix}/auth/cognito/user-pool-arn`, + stringValue: userPool.userPoolArn, + description: 'Cognito User Pool ARN', + tier: ssm.ParameterTier.STANDARD, + }); + + new ssm.StringParameter(this, 'CognitoAppClientIdParameter', { + parameterName: `/${config.projectPrefix}/auth/cognito/app-client-id`, + stringValue: appClient.userPoolClientId, + description: 'Cognito App Client ID', + tier: ssm.ParameterTier.STANDARD, + }); + + new ssm.StringParameter(this, 'CognitoDomainUrlParameter', { + parameterName: `/${config.projectPrefix}/auth/cognito/domain-url`, + stringValue: cognitoDomain.baseUrl(), + description: 'Cognito hosted UI domain URL', + tier: ssm.ParameterTier.STANDARD, + }); + + new ssm.StringParameter(this, 'CognitoIssuerUrlParameter', { + parameterName: `/${config.projectPrefix}/auth/cognito/issuer-url`, + stringValue: `https://cognito-idp.${config.awsRegion}.amazonaws.com/${userPool.userPoolId}`, + description: 'Cognito OIDC issuer URL', + tier: ssm.ParameterTier.STANDARD, + }); + // ============================================================ // File Upload Storage (S3 + DynamoDB) // ============================================================ @@ -1080,17 +1193,7 @@ export class InfrastructureStack extends cdk.Stack { // dependency: InferenceApiStack (tier 2) deploys before AppApiStack (tier 3). // Build CORS origins for file upload bucket - const fileUploadCorsOrigins: string[] = (() => { - const origins = new Set(); - origins.add('http://localhost:4200'); - if (config.domainName) { - origins.add(`https://${config.domainName}`); - } - if (config.fileUpload?.corsOrigins) { - config.fileUpload.corsOrigins.split(',').map(o => o.trim()).filter(Boolean).forEach(o => origins.add(o)); - } - return Array.from(origins); - })(); + const fileUploadCorsOrigins = buildCorsOrigins(config, config.fileUpload?.additionalCorsOrigins); // S3 Bucket for user file uploads const userFilesBucket = new s3.Bucket(this, "UserFilesBucket", { @@ -1101,7 +1204,7 @@ export class InfrastructureStack extends cdk.Stack { versioned: false, removalPolicy: getRemovalPolicy(config), autoDeleteObjects: getAutoDeleteObjects(config), - cors: [ + cors: fileUploadCorsOrigins.length > 0 ? [ { allowedOrigins: fileUploadCorsOrigins, allowedMethods: [s3.HttpMethods.GET, s3.HttpMethods.PUT, s3.HttpMethods.HEAD], @@ -1109,7 +1212,7 @@ export class InfrastructureStack extends cdk.Stack { exposedHeaders: ["ETag", "Content-Length", "Content-Type"], maxAge: 3600, }, - ], + ] : undefined, lifecycleRules: [ { id: "transition-to-ia", diff --git a/infrastructure/lib/rag-ingestion-stack.ts b/infrastructure/lib/rag-ingestion-stack.ts index 95df0376..36078462 100644 --- a/infrastructure/lib/rag-ingestion-stack.ts +++ b/infrastructure/lib/rag-ingestion-stack.ts @@ -10,7 +10,7 @@ import * as ssm from 'aws-cdk-lib/aws-ssm'; import * as ecr from 'aws-cdk-lib/aws-ecr'; import { Construct } from 'constructs'; import { CfnResource } from 'aws-cdk-lib'; -import { AppConfig, getResourceName, applyStandardTags, getRemovalPolicy, getAutoDeleteObjects } from './config'; +import { AppConfig, getResourceName, applyStandardTags, getRemovalPolicy, getAutoDeleteObjects, buildCorsOrigins } from './config'; export interface RagIngestionStackProps extends cdk.StackProps { config: AppConfig; @@ -86,21 +86,8 @@ export class RagIngestionStack extends cdk.Stack { // S3 Documents Bucket // ============================================================ - // Build CORS origins: auto-include domain + localhost + any explicit config - const corsOrigins = new Set(); - corsOrigins.add('http://localhost:4200'); - - // Use domainName if provided (custom domain) - if (config.domainName) { - corsOrigins.add(`https://${config.domainName}`); - } - - // Add any explicit CORS origins from config - if (config.ragIngestion.corsOrigins) { - config.ragIngestion.corsOrigins.split(',').map(o => o.trim()).filter(Boolean).forEach(o => corsOrigins.add(o)); - } - - const ragCorsOrigins = Array.from(corsOrigins); + // Build CORS origins for RAG documents bucket + const ragCorsOrigins = buildCorsOrigins(config, config.ragIngestion.additionalCorsOrigins); this.documentsBucket = new s3.Bucket(this, 'RagDocumentsBucket', { bucketName: getResourceName(config, 'rag-documents', config.awsAccount), diff --git a/infrastructure/lib/sagemaker-fine-tuning-stack.ts b/infrastructure/lib/sagemaker-fine-tuning-stack.ts index 61d548ca..33a9974c 100644 --- a/infrastructure/lib/sagemaker-fine-tuning-stack.ts +++ b/infrastructure/lib/sagemaker-fine-tuning-stack.ts @@ -5,7 +5,7 @@ import * as s3 from 'aws-cdk-lib/aws-s3'; import * as iam from 'aws-cdk-lib/aws-iam'; import * as ssm from 'aws-cdk-lib/aws-ssm'; import { Construct } from 'constructs'; -import { AppConfig, getResourceName, applyStandardTags, getRemovalPolicy, getAutoDeleteObjects } from './config'; +import { AppConfig, getResourceName, applyStandardTags, getRemovalPolicy, getAutoDeleteObjects, buildCorsOrigins } from './config'; export interface SageMakerFineTuningStackProps extends cdk.StackProps { config: AppConfig; @@ -126,16 +126,8 @@ export class SageMakerFineTuningStack extends cdk.Stack { // S3 Bucket for Fine-Tuning Data // ============================================================ - // Build CORS origins for presigned URL uploads - const corsOrigins = new Set(); - corsOrigins.add('http://localhost:4200'); - if (config.domainName) { - corsOrigins.add(`https://${config.domainName}`); - } - if (config.corsOrigins) { - config.corsOrigins.split(',').map(o => o.trim()).filter(Boolean).forEach(o => corsOrigins.add(o)); - } - const fineTuningCorsOrigins = Array.from(corsOrigins); + // Build CORS origins for fine-tuning data bucket + const fineTuningCorsOrigins = buildCorsOrigins(config, config.fineTuning.additionalCorsOrigins); this.fineTuningDataBucket = new s3.Bucket(this, 'FineTuningDataBucket', { bucketName: getResourceName(config, 'fine-tuning-data', config.awsAccount), @@ -145,7 +137,7 @@ export class SageMakerFineTuningStack extends cdk.Stack { versioned: false, removalPolicy: getRemovalPolicy(config), autoDeleteObjects: getAutoDeleteObjects(config), - cors: [ + cors: fineTuningCorsOrigins.length > 0 ? [ { allowedOrigins: fineTuningCorsOrigins, allowedMethods: [s3.HttpMethods.GET, s3.HttpMethods.PUT, s3.HttpMethods.HEAD], @@ -153,7 +145,7 @@ export class SageMakerFineTuningStack extends cdk.Stack { exposedHeaders: ['ETag', 'Content-Length', 'Content-Type'], maxAge: 3600, }, - ], + ] : undefined, lifecycleRules: [ { id: 'expire-objects', diff --git a/infrastructure/package-lock.json b/infrastructure/package-lock.json index b25a27f7..cef0a78b 100644 --- a/infrastructure/package-lock.json +++ b/infrastructure/package-lock.json @@ -1,14 +1,14 @@ { "name": "infrastructure", - "version": "1.0.0-beta.20", + "version": "1.0.0-beta.22", "lockfileVersion": 3, "requires": true, "packages": { "": { "name": "infrastructure", - "version": "1.0.0-beta.20", + "version": "1.0.0-beta.22", "dependencies": { - "aws-cdk-lib": "2.245.0", + "aws-cdk-lib": "2.248.0", "constructs": "10.6.0" }, "bin": { @@ -16,18 +16,18 @@ }, "devDependencies": { "@types/jest": "30.0.0", - "@types/node": "25.5.0", - "aws-cdk": "2.1115.0", + "@types/node": "25.5.2", + "aws-cdk": "2.1117.0", "jest": "30.3.0", - "ts-jest": "29.4.6", + "ts-jest": "29.4.9", "ts-node": "10.9.2", "typescript": "5.9.3" } }, "node_modules/@aws-cdk/asset-awscli-v1": { - "version": "2.2.263", - "resolved": "https://registry.npmjs.org/@aws-cdk/asset-awscli-v1/-/asset-awscli-v1-2.2.263.tgz", - "integrity": "sha512-X9JvcJhYcb7PHs8R7m4zMablO5C9PGb/hYfLnxds9h/rKJu6l7MiXE/SabCibuehxPnuO/vk+sVVJiUWrccarQ==", + "version": "2.2.273", + "resolved": "https://registry.npmjs.org/@aws-cdk/asset-awscli-v1/-/asset-awscli-v1-2.2.273.tgz", + "integrity": "sha512-X57HYUtHt9BQrlrzUNcMyRsDUCoakYNnY6qh5lNwRCHPtQoTfXmuISkfLk0AjLkcbS5lw1LLTQFiQhTDXfiTvg==", "license": "Apache-2.0" }, "node_modules/@aws-cdk/asset-node-proxy-agent-v6": { @@ -1248,9 +1248,9 @@ } }, "node_modules/@types/node": { - "version": "25.5.0", - "resolved": "https://registry.npmjs.org/@types/node/-/node-25.5.0.tgz", - "integrity": "sha512-jp2P3tQMSxWugkCUKLRPVUpGaL5MVFwF8RDuSRztfwgN1wmqJeMSbKlnEtQqU8UrhTmzEmZdu2I6v2dpp7XIxw==", + "version": "25.5.2", + "resolved": "https://registry.npmjs.org/@types/node/-/node-25.5.2.tgz", + "integrity": "sha512-tO4ZIRKNC+MDWV4qKVZe3Ql/woTnmHDr5JD8UI5hn2pwBrHEwOEMZK7WlNb5RKB6EoJ02gwmQS9OrjuFnZYdpg==", "dev": true, "license": "MIT", "dependencies": { @@ -1660,9 +1660,9 @@ } }, "node_modules/aws-cdk": { - "version": "2.1115.0", - "resolved": "https://registry.npmjs.org/aws-cdk/-/aws-cdk-2.1115.0.tgz", - "integrity": "sha512-PpNNflDt1L2TxpMh2h7cPHnFkDVeY1hwIxuGuvswS08mA0syOT4OmZx8hZYdcLru6NceCsn0x/7uTHpb6Hzo5A==", + "version": "2.1117.0", + "resolved": "https://registry.npmjs.org/aws-cdk/-/aws-cdk-2.1117.0.tgz", + "integrity": "sha512-2NbSDDw8LTkGv0uhEDffttmNvgyTAWV5EkLkyPUGAGECzBdwCmbgmRxSoUhbzxZ0XEd1eaqbdVTFRWgtsbj31g==", "dev": true, "license": "Apache-2.0", "bin": { @@ -1673,9 +1673,9 @@ } }, "node_modules/aws-cdk-lib": { - "version": "2.245.0", - "resolved": "https://registry.npmjs.org/aws-cdk-lib/-/aws-cdk-lib-2.245.0.tgz", - "integrity": "sha512-Yfeb+wKC6s+Ttm/N93C6vY6ksyCh68WaG/j3N6dalJWTW/V4o6hUolHm+v2c2IofJEUS45c5AF/EEj24e9hfMA==", + "version": "2.248.0", + "resolved": "https://registry.npmjs.org/aws-cdk-lib/-/aws-cdk-lib-2.248.0.tgz", + "integrity": "sha512-PGQycx/OdyX+t0o6QUFI1KJAOLoyIVj2WwrN0syrwCi8lYxW2KzldZsW0X+/UN/ALNQwcjSr927ImTpuDOh+bg==", "bundleDependencies": [ "@balena/dockerignore", "@aws-cdk/cloud-assembly-api", @@ -1692,7 +1692,7 @@ ], "license": "Apache-2.0", "dependencies": { - "@aws-cdk/asset-awscli-v1": "2.2.263", + "@aws-cdk/asset-awscli-v1": "2.2.273", "@aws-cdk/asset-node-proxy-agent-v6": "^2.1.1", "@aws-cdk/cloud-assembly-api": "^2.2.0", "@aws-cdk/cloud-assembly-schema": "^53.0.0", @@ -1812,7 +1812,7 @@ } }, "node_modules/aws-cdk-lib/node_modules/brace-expansion": { - "version": "5.0.3", + "version": "5.0.5", "inBundle": true, "license": "MIT", "dependencies": { @@ -1954,11 +1954,11 @@ } }, "node_modules/aws-cdk-lib/node_modules/minimatch": { - "version": "10.2.4", + "version": "10.2.5", "inBundle": true, "license": "BlueOak-1.0.0", "dependencies": { - "brace-expansion": "^5.0.2" + "brace-expansion": "^5.0.5" }, "engines": { "node": "18 || 20 || >=22" @@ -2853,9 +2853,9 @@ "license": "ISC" }, "node_modules/handlebars": { - "version": "4.7.8", - "resolved": "https://registry.npmjs.org/handlebars/-/handlebars-4.7.8.tgz", - "integrity": "sha512-vafaFqs8MZkRrSX7sFVUdo3ap/eNiLnb4IakshzvP56X5Nr1iGKAIqdX6tMlm6HcNRIkr6AxO5jFEoJzzpT8aQ==", + "version": "4.7.9", + "resolved": "https://registry.npmjs.org/handlebars/-/handlebars-4.7.9.tgz", + "integrity": "sha512-4E71E0rpOaQuJR2A3xDZ+GM1HyWYv1clR58tC8emQNeQe3RH7MAzSbat+V0wG78LQBo6m6bzSG/L4pBuCsgnUQ==", "dev": true, "license": "MIT", "dependencies": { @@ -4615,19 +4615,19 @@ "license": "BSD-3-Clause" }, "node_modules/ts-jest": { - "version": "29.4.6", - "resolved": "https://registry.npmjs.org/ts-jest/-/ts-jest-29.4.6.tgz", - "integrity": "sha512-fSpWtOO/1AjSNQguk43hb/JCo16oJDnMJf3CdEGNkqsEX3t0KX96xvyX1D7PfLCpVoKu4MfVrqUkFyblYoY4lA==", + "version": "29.4.9", + "resolved": "https://registry.npmjs.org/ts-jest/-/ts-jest-29.4.9.tgz", + "integrity": "sha512-LTb9496gYPMCqjeDLdPrKuXtncudeV1yRZnF4Wo5l3SFi0RYEnYRNgMrFIdg+FHvfzjCyQk1cLncWVqiSX+EvQ==", "dev": true, "license": "MIT", "dependencies": { "bs-logger": "^0.2.6", "fast-json-stable-stringify": "^2.1.0", - "handlebars": "^4.7.8", + "handlebars": "^4.7.9", "json5": "^2.2.3", "lodash.memoize": "^4.1.2", "make-error": "^1.3.6", - "semver": "^7.7.3", + "semver": "^7.7.4", "type-fest": "^4.41.0", "yargs-parser": "^21.1.1" }, @@ -4644,7 +4644,7 @@ "babel-jest": "^29.0.0 || ^30.0.0", "jest": "^29.0.0 || ^30.0.0", "jest-util": "^29.0.0 || ^30.0.0", - "typescript": ">=4.3 <6" + "typescript": ">=4.3 <7" }, "peerDependenciesMeta": { "@babel/core": { @@ -4668,9 +4668,9 @@ } }, "node_modules/ts-jest/node_modules/semver": { - "version": "7.7.3", - "resolved": "https://registry.npmjs.org/semver/-/semver-7.7.3.tgz", - "integrity": "sha512-SdsKMrI9TdgjdweUSR9MweHA4EJ8YxHn8DFaDisvhVlUOe4BF1tLD7GAj0lIqWVl+dPb/rExr0Btby5loQm20Q==", + "version": "7.7.4", + "resolved": "https://registry.npmjs.org/semver/-/semver-7.7.4.tgz", + "integrity": "sha512-vFKC2IEtQnVhpT78h1Yp8wzwrf8CM+MzKMHGJZfBtzhZNycRFnXsHk6E5TxIkkMsgNS7mdX3AGB7x2QM2di4lA==", "dev": true, "license": "ISC", "bin": { diff --git a/infrastructure/package.json b/infrastructure/package.json index b0ca4601..f184b466 100644 --- a/infrastructure/package.json +++ b/infrastructure/package.json @@ -1,6 +1,6 @@ { "name": "infrastructure", - "version": "1.0.0-beta.20", + "version": "1.0.0-beta.22", "bin": { "infrastructure": "bin/infrastructure.js" }, @@ -12,15 +12,15 @@ }, "devDependencies": { "@types/jest": "30.0.0", - "@types/node": "25.5.0", - "aws-cdk": "2.1115.0", + "@types/node": "25.5.2", + "aws-cdk": "2.1117.0", "jest": "30.3.0", - "ts-jest": "29.4.6", + "ts-jest": "29.4.9", "ts-node": "10.9.2", "typescript": "5.9.3" }, "dependencies": { - "aws-cdk-lib": "2.245.0", + "aws-cdk-lib": "2.248.0", "constructs": "10.6.0" }, "overrides": { diff --git a/infrastructure/test/app-api-stack.test.ts b/infrastructure/test/app-api-stack.test.ts index 0c2670f1..883b756c 100644 --- a/infrastructure/test/app-api-stack.test.ts +++ b/infrastructure/test/app-api-stack.test.ts @@ -100,6 +100,18 @@ describe('AppApiStack', () => { ]), }); }); + + test('container environment includes CORS_ORIGINS derived from domainName', () => { + template.hasResourceProperties('AWS::ECS::TaskDefinition', { + ContainerDefinitions: Match.arrayWith([ + Match.objectLike({ + Environment: Match.arrayWith([ + Match.objectLike({ Name: 'CORS_ORIGINS' }), + ]), + }), + ]), + }); + }); }); // ============================================================ @@ -134,118 +146,6 @@ describe('AppApiStack', () => { }); }); - // ============================================================ - // S3 Buckets - // ============================================================ - - describe('S3 Buckets', () => { - test('creates AssistantsDocumentBucket with versioning', () => { - template.hasResourceProperties('AWS::S3::Bucket', { - BucketName: `${config.projectPrefix}-assistants-documents`, - VersioningConfiguration: { Status: 'Enabled' }, - }); - }); - - test('AssistantsDocumentBucket has CORS configuration', () => { - template.hasResourceProperties('AWS::S3::Bucket', { - BucketName: `${config.projectPrefix}-assistants-documents`, - CorsConfiguration: { - CorsRules: Match.arrayWith([ - Match.objectLike({ - AllowedMethods: ['GET', 'PUT', 'HEAD'], - AllowedHeaders: ['Content-Type', 'Content-Length', 'x-amz-*'], - }), - ]), - }, - }); - }); - - test('creates exactly 1 S3 bucket (UserFiles moved to InfrastructureStack)', () => { - template.resourceCountIs('AWS::S3::Bucket', 1); - }); - }); - - // ============================================================ - // S3 Vector Store Resources - // ============================================================ - - describe('S3 Vector Store', () => { - test('creates S3 Vector Bucket', () => { - template.hasResourceProperties('AWS::S3Vectors::VectorBucket', { - VectorBucketName: `${config.projectPrefix}-assistants-vector-store-v1`, - }); - }); - - test('creates S3 Vector Index with correct config', () => { - template.hasResourceProperties('AWS::S3Vectors::Index', { - VectorBucketName: `${config.projectPrefix}-assistants-vector-store-v1`, - IndexName: `${config.projectPrefix}-assistants-vector-index-v1`, - DataType: 'float32', - Dimension: 1024, - DistanceMetric: 'cosine', - }); - }); - }); - - // ============================================================ - // Lambda Functions - // ============================================================ - - describe('Lambda Functions', () => { - test('creates RuntimeProvisioner function', () => { - template.hasResourceProperties('AWS::Lambda::Function', { - FunctionName: `${config.projectPrefix}-runtime-provisioner`, - Runtime: 'python3.14', - Handler: 'lambda_function.lambda_handler', - MemorySize: 512, - Timeout: 300, - Architectures: ['arm64'], - }); - }); - - test('creates RuntimeUpdater function', () => { - template.hasResourceProperties('AWS::Lambda::Function', { - FunctionName: `${config.projectPrefix}-runtime-updater`, - Runtime: 'python3.14', - Handler: 'lambda_function.lambda_handler', - MemorySize: 512, - Timeout: 900, - Architectures: ['arm64'], - }); - }); - - test('creates at least 2 Lambda functions', () => { - const lambdas = template.findResources('AWS::Lambda::Function'); - expect(Object.keys(lambdas).length).toBeGreaterThanOrEqual(2); - }); - - test('RuntimeProvisioner has DynamoDB event source mapping', () => { - template.hasResourceProperties('AWS::Lambda::EventSourceMapping', { - BatchSize: 1, - BisectBatchOnFunctionError: true, - MaximumRetryAttempts: 3, - StartingPosition: 'LATEST', - }); - }); - }); - - // ============================================================ - // SNS Topic - // ============================================================ - - describe('SNS Topic', () => { - test('creates runtime update alerts topic', () => { - template.hasResourceProperties('AWS::SNS::Topic', { - TopicName: `${config.projectPrefix}-runtime-update-alerts`, - DisplayName: 'AgentCore Runtime Update Alerts', - }); - }); - - test('creates exactly 1 SNS topic', () => { - template.resourceCountIs('AWS::SNS::Topic', 1); - }); - }); - // ============================================================ // ALB Target Group // ============================================================ @@ -285,29 +185,8 @@ describe('AppApiStack', () => { // ============================================================ describe('SSM Parameters', () => { - test('exports 3 SSM parameters (file-upload params moved to InfrastructureStack)', () => { - template.resourceCountIs('AWS::SSM::Parameter', 3); - }); - - test('exports lambda/runtime-provisioner-arn', () => { - template.hasResourceProperties('AWS::SSM::Parameter', { - Name: `/${config.projectPrefix}/lambda/runtime-provisioner-arn`, - Type: 'String', - }); - }); - - test('exports lambda/runtime-updater-arn', () => { - template.hasResourceProperties('AWS::SSM::Parameter', { - Name: `/${config.projectPrefix}/lambda/runtime-updater-arn`, - Type: 'String', - }); - }); - - test('exports sns/runtime-update-alerts-arn', () => { - template.hasResourceProperties('AWS::SSM::Parameter', { - Name: `/${config.projectPrefix}/sns/runtime-update-alerts-arn`, - Type: 'String', - }); + test('exports 0 SSM parameters (runtime provisioner/updater removed)', () => { + template.resourceCountIs('AWS::SSM::Parameter', 0); }); }); @@ -384,21 +263,6 @@ describe('AppApiStack', () => { }); }); - // ============================================================ - // EventBridge Rule - // ============================================================ - - describe('EventBridge Rule', () => { - test('creates rule for SSM parameter change detection', () => { - template.hasResourceProperties('AWS::Events::Rule', { - EventPattern: Match.objectLike({ - source: ['aws.ssm'], - 'detail-type': ['Parameter Store Change'], - }), - }); - }); - }); - // ============================================================ // CloudFormation Outputs (Required for Deploy Script) // ============================================================ diff --git a/infrastructure/test/config.test.ts b/infrastructure/test/config.test.ts index 2316d82a..3e865e1c 100644 --- a/infrastructure/test/config.test.ts +++ b/infrastructure/test/config.test.ts @@ -26,6 +26,7 @@ describe('RAG Ingestion Configuration', () => { app.node.setContext('awsRegion', 'us-east-1'); app.node.setContext('awsAccount', '123456789012'); app.node.setContext('vpcCidr', '10.0.0.0/16'); + app.node.setContext('domainName', 'test.example.com'); // Set default context for other required fields app.node.setContext('frontend', { @@ -46,7 +47,6 @@ describe('RAG Ingestion Configuration', () => { desiredCount: 1, maxCapacity: 4, logLevel: 'INFO', - corsOrigins: 'http://localhost:3000', }); app.node.setContext('gateway', { enabled: true, @@ -57,7 +57,7 @@ describe('RAG Ingestion Configuration', () => { }); app.node.setContext('assistants', { enabled: true, - corsOrigins: 'http://localhost:3000', + additionalCorsOrigins: 'http://localhost:3000', }); app.node.setContext('fileUpload', { enabled: true, @@ -65,7 +65,7 @@ describe('RAG Ingestion Configuration', () => { maxFilesPerMessage: 5, userQuotaBytes: 1073741824, retentionDays: 365, - corsOrigins: 'http://localhost:4200', + additionalCorsOrigins: 'http://localhost:4200', }); // Set default ragIngestion context (mirrors cdk.context.json defaults) @@ -73,7 +73,7 @@ describe('RAG Ingestion Configuration', () => { // provide context defaults for fields they don't explicitly set via env vars. app.node.setContext('ragIngestion', { enabled: true, - corsOrigins: '', + additionalCorsOrigins: '', lambdaMemorySize: 10240, lambdaTimeout: 900, embeddingModel: 'amazon.titan-embed-text-v2', @@ -105,7 +105,7 @@ describe('RAG Ingestion Configuration', () => { const config = loadConfig(app); - expect(config.ragIngestion.corsOrigins).toBe('https://example.com,https://test.com'); + expect(config.ragIngestion.additionalCorsOrigins).toBe('https://example.com,https://test.com'); }); test('loads Lambda memory size from CDK_RAG_LAMBDA_MEMORY environment variable', () => { @@ -161,7 +161,7 @@ describe('RAG Ingestion Configuration', () => { expect(config.ragIngestion).toEqual({ enabled: true, - corsOrigins: 'https://prod.example.com', + additionalCorsOrigins: 'https://prod.example.com', lambdaMemorySize: 10240, lambdaTimeout: 900, embeddingModel: 'amazon.titan-embed-text-v2', @@ -179,7 +179,7 @@ describe('RAG Ingestion Configuration', () => { test('falls back to context value when environment variable not set', () => { app.node.setContext('ragIngestion', { enabled: false, - corsOrigins: 'https://context.example.com', + additionalCorsOrigins: 'https://context.example.com', lambdaMemorySize: 8192, lambdaTimeout: 600, embeddingModel: 'amazon.titan-embed-text-v1', @@ -191,7 +191,7 @@ describe('RAG Ingestion Configuration', () => { expect(config.ragIngestion).toEqual({ enabled: false, - corsOrigins: 'https://context.example.com', + additionalCorsOrigins: 'https://context.example.com', lambdaMemorySize: 8192, lambdaTimeout: 600, embeddingModel: 'amazon.titan-embed-text-v1', @@ -203,7 +203,7 @@ describe('RAG Ingestion Configuration', () => { test('environment variable takes precedence over context', () => { app.node.setContext('ragIngestion', { enabled: false, - corsOrigins: 'https://context.example.com', + additionalCorsOrigins: 'https://context.example.com', lambdaMemorySize: 8192, lambdaTimeout: 900, embeddingModel: 'amazon.titan-embed-text-v2', @@ -218,14 +218,14 @@ describe('RAG Ingestion Configuration', () => { const config = loadConfig(app); expect(config.ragIngestion.enabled).toBe(true); - expect(config.ragIngestion.corsOrigins).toBe('https://env.example.com'); + expect(config.ragIngestion.additionalCorsOrigins).toBe('https://env.example.com'); expect(config.ragIngestion.lambdaMemorySize).toBe(10240); }); test('uses context for some values and env for others', () => { app.node.setContext('ragIngestion', { enabled: false, - corsOrigins: 'https://context.example.com', + additionalCorsOrigins: 'https://context.example.com', lambdaMemorySize: 8192, lambdaTimeout: 600, embeddingModel: 'amazon.titan-embed-text-v2', @@ -239,7 +239,7 @@ describe('RAG Ingestion Configuration', () => { const config = loadConfig(app); expect(config.ragIngestion.enabled).toBe(true); // from env - expect(config.ragIngestion.corsOrigins).toBe('https://context.example.com'); // from context + expect(config.ragIngestion.additionalCorsOrigins).toBe('https://context.example.com'); // from context expect(config.ragIngestion.lambdaMemorySize).toBe(10240); // from env expect(config.ragIngestion.lambdaTimeout).toBe(600); // from context }); @@ -254,7 +254,7 @@ describe('RAG Ingestion Configuration', () => { const config = loadConfig(app); expect(config.ragIngestion.enabled).toBe(true); - expect(config.ragIngestion.corsOrigins).toBe(''); + expect(config.ragIngestion.additionalCorsOrigins).toBe(''); expect(config.ragIngestion.lambdaMemorySize).toBe(10240); expect(config.ragIngestion.lambdaTimeout).toBe(900); expect(config.ragIngestion.embeddingModel).toBe('amazon.titan-embed-text-v2'); @@ -271,7 +271,7 @@ describe('RAG Ingestion Configuration', () => { test('default CORS origins is empty string', () => { const config = loadConfig(app); - expect(config.ragIngestion.corsOrigins).toBe(''); + expect(config.ragIngestion.additionalCorsOrigins).toBe(''); }); test('default Lambda memory is 10240 MB', () => { @@ -335,15 +335,15 @@ describe('RAG Ingestion Configuration', () => { testApp.node.setContext('vpcCidr', '10.0.0.0/16'); testApp.node.setContext('frontend', { enabled: true, cloudFrontPriceClass: 'PriceClass_100' }); testApp.node.setContext('appApi', { enabled: true, cpu: 256, memory: 512, desiredCount: 1, maxCapacity: 4 }); - testApp.node.setContext('inferenceApi', { enabled: true, cpu: 256, memory: 512, desiredCount: 1, maxCapacity: 4, logLevel: 'INFO', corsOrigins: 'http://localhost:3000' }); + testApp.node.setContext('inferenceApi', { enabled: true, cpu: 256, memory: 512, desiredCount: 1, maxCapacity: 4, logLevel: 'INFO' }); testApp.node.setContext('gateway', { enabled: true, apiType: 'REST', throttleRateLimit: 1000, throttleBurstLimit: 2000, enableWaf: false }); - testApp.node.setContext('assistants', { enabled: true, corsOrigins: 'http://localhost:3000' }); + testApp.node.setContext('assistants', { enabled: true, additionalCorsOrigins: 'http://localhost:3000' }); testApp.node.setContext('fileUpload', { enabled: true, maxFileSizeBytes: 4194304, maxFilesPerMessage: 5, userQuotaBytes: 1073741824, retentionDays: 365 }); process.env.CDK_RAG_ENABLED = 'true'; // Enable RAG to trigger validation testApp.node.setContext('ragIngestion', { enabled: true, - corsOrigins: '', + additionalCorsOrigins: '', lambdaMemorySize: 10240, lambdaTimeout: -1, // Negative (invalid) embeddingModel: 'amazon.titan-embed-text-v2', @@ -365,15 +365,15 @@ describe('RAG Ingestion Configuration', () => { testApp.node.setContext('vpcCidr', '10.0.0.0/16'); testApp.node.setContext('frontend', { enabled: true, cloudFrontPriceClass: 'PriceClass_100' }); testApp.node.setContext('appApi', { enabled: true, cpu: 256, memory: 512, desiredCount: 1, maxCapacity: 4 }); - testApp.node.setContext('inferenceApi', { enabled: true, cpu: 256, memory: 512, desiredCount: 1, maxCapacity: 4, logLevel: 'INFO', corsOrigins: 'http://localhost:3000' }); + testApp.node.setContext('inferenceApi', { enabled: true, cpu: 256, memory: 512, desiredCount: 1, maxCapacity: 4, logLevel: 'INFO' }); testApp.node.setContext('gateway', { enabled: true, apiType: 'REST', throttleRateLimit: 1000, throttleBurstLimit: 2000, enableWaf: false }); - testApp.node.setContext('assistants', { enabled: true, corsOrigins: 'http://localhost:3000' }); + testApp.node.setContext('assistants', { enabled: true, additionalCorsOrigins: 'http://localhost:3000' }); testApp.node.setContext('fileUpload', { enabled: true, maxFileSizeBytes: 4194304, maxFilesPerMessage: 5, userQuotaBytes: 1073741824, retentionDays: 365 }); process.env.CDK_RAG_ENABLED = 'true'; // Enable RAG to trigger validation testApp.node.setContext('ragIngestion', { enabled: true, - corsOrigins: '', + additionalCorsOrigins: '', lambdaMemorySize: 10240, lambdaTimeout: 1000, // Too high embeddingModel: 'amazon.titan-embed-text-v2', @@ -395,15 +395,15 @@ describe('RAG Ingestion Configuration', () => { testApp.node.setContext('vpcCidr', '10.0.0.0/16'); testApp.node.setContext('frontend', { enabled: true, cloudFrontPriceClass: 'PriceClass_100' }); testApp.node.setContext('appApi', { enabled: true, cpu: 256, memory: 512, desiredCount: 1, maxCapacity: 4 }); - testApp.node.setContext('inferenceApi', { enabled: true, cpu: 256, memory: 512, desiredCount: 1, maxCapacity: 4, logLevel: 'INFO', corsOrigins: 'http://localhost:3000' }); + testApp.node.setContext('inferenceApi', { enabled: true, cpu: 256, memory: 512, desiredCount: 1, maxCapacity: 4, logLevel: 'INFO' }); testApp.node.setContext('gateway', { enabled: true, apiType: 'REST', throttleRateLimit: 1000, throttleBurstLimit: 2000, enableWaf: false }); - testApp.node.setContext('assistants', { enabled: true, corsOrigins: 'http://localhost:3000' }); + testApp.node.setContext('assistants', { enabled: true, additionalCorsOrigins: 'http://localhost:3000' }); testApp.node.setContext('fileUpload', { enabled: true, maxFileSizeBytes: 4194304, maxFilesPerMessage: 5, userQuotaBytes: 1073741824, retentionDays: 365 }); process.env.CDK_RAG_ENABLED = 'true'; // Enable RAG to trigger validation testApp.node.setContext('ragIngestion', { enabled: true, - corsOrigins: '', + additionalCorsOrigins: '', lambdaMemorySize: 10240, lambdaTimeout: 900, embeddingModel: 'amazon.titan-embed-text-v2', @@ -459,15 +459,15 @@ describe('RAG Ingestion Configuration', () => { testApp.node.setContext('vpcCidr', '10.0.0.0/16'); testApp.node.setContext('frontend', { enabled: true, cloudFrontPriceClass: 'PriceClass_100' }); testApp.node.setContext('appApi', { enabled: true, cpu: 256, memory: 512, desiredCount: 1, maxCapacity: 4 }); - testApp.node.setContext('inferenceApi', { enabled: true, cpu: 256, memory: 512, desiredCount: 1, maxCapacity: 4, logLevel: 'INFO', corsOrigins: 'http://localhost:3000' }); + testApp.node.setContext('inferenceApi', { enabled: true, cpu: 256, memory: 512, desiredCount: 1, maxCapacity: 4, logLevel: 'INFO' }); testApp.node.setContext('gateway', { enabled: true, apiType: 'REST', throttleRateLimit: 1000, throttleBurstLimit: 2000, enableWaf: false }); - testApp.node.setContext('assistants', { enabled: true, corsOrigins: 'http://localhost:3000' }); + testApp.node.setContext('assistants', { enabled: true, additionalCorsOrigins: 'http://localhost:3000' }); testApp.node.setContext('fileUpload', { enabled: true, maxFileSizeBytes: 4194304, maxFilesPerMessage: 5, userQuotaBytes: 1073741824, retentionDays: 365 }); process.env.CDK_RAG_ENABLED = 'true'; // Enable RAG to trigger validation testApp.node.setContext('ragIngestion', { enabled: true, - corsOrigins: '', + additionalCorsOrigins: '', lambdaMemorySize: 10240, lambdaTimeout: 900, embeddingModel: ' ', // Whitespace only @@ -626,7 +626,7 @@ describe('RAG Ingestion Configuration', () => { const config = loadConfig(app); - expect(config.ragIngestion.corsOrigins).toBe(' http://localhost:3000 , https://example.com '); + expect(config.ragIngestion.additionalCorsOrigins).toBe(' http://localhost:3000 , https://example.com '); }); }); @@ -639,7 +639,7 @@ describe('RAG Ingestion Configuration', () => { // Set context value app.node.setContext('ragIngestion', { enabled: true, - corsOrigins: '', + additionalCorsOrigins: '', lambdaMemorySize: 8192, lambdaTimeout: 900, embeddingModel: 'amazon.titan-embed-text-v2', @@ -658,7 +658,7 @@ describe('RAG Ingestion Configuration', () => { test('context overrides default when env not set', () => { app.node.setContext('ragIngestion', { enabled: true, - corsOrigins: '', + additionalCorsOrigins: '', lambdaMemorySize: 8192, lambdaTimeout: 900, embeddingModel: 'amazon.titan-embed-text-v2', @@ -680,7 +680,7 @@ describe('RAG Ingestion Configuration', () => { test('mixed precedence for different fields', () => { app.node.setContext('ragIngestion', { enabled: false, - corsOrigins: 'https://context.example.com', + additionalCorsOrigins: 'https://context.example.com', lambdaMemorySize: 8192, lambdaTimeout: 900, embeddingModel: 'amazon.titan-embed-text-v2', @@ -695,7 +695,7 @@ describe('RAG Ingestion Configuration', () => { const config = loadConfig(app); expect(config.ragIngestion.enabled).toBe(true); // env - expect(config.ragIngestion.corsOrigins).toBe('https://context.example.com'); // context + expect(config.ragIngestion.additionalCorsOrigins).toBe('https://context.example.com'); // context expect(config.ragIngestion.lambdaMemorySize).toBe(8192); // context expect(config.ragIngestion.lambdaTimeout).toBe(900); // default }); @@ -722,7 +722,7 @@ describe('RAG Ingestion Configuration', () => { test('handles partial context values', () => { app.node.setContext('ragIngestion', { enabled: false, - corsOrigins: '', + additionalCorsOrigins: '', lambdaMemorySize: 10240, lambdaTimeout: 900, embeddingModel: 'amazon.titan-embed-text-v2', diff --git a/infrastructure/test/cors.test.ts b/infrastructure/test/cors.test.ts new file mode 100644 index 00000000..98b3fc78 --- /dev/null +++ b/infrastructure/test/cors.test.ts @@ -0,0 +1,258 @@ +import * as cdk from 'aws-cdk-lib'; +import { loadConfig, buildCorsOrigins, AppConfig } from '../lib/config'; +import { createMockConfig } from './helpers/mock-config'; + +/** + * Comprehensive CORS Configuration Tests + * + * These tests verify the two-layer CORS model: + * 1. CDK_DOMAIN_NAME is ALWAYS auto-applied as https://{domainName} + * 2. CDK_CORS_ORIGINS (or section-specific extras) are APPENDED + * + * localhost is NOT auto-included — use CDK_CORS_ORIGINS to add it for local dev. + * + * The flow: + * GitHub vars.CDK_DOMAIN_NAME + * → workflow job env → load-env.sh → --context domainName + * → config.ts: corsOrigins = "https://{domainName}" + extras + * → buildCorsOrigins(config, additionalOrigins?) → string[] + * → each stack uses the array for S3 CORS / container env vars + */ + +describe('buildCorsOrigins', () => { + // ============================================================ + // Layer 1: CDK_DOMAIN_NAME is always auto-applied + // ============================================================ + + describe('Layer 1: domainName auto-applied', () => { + test('includes https://{domainName} when set via corsOrigins', () => { + const config = createMockConfig({ + corsOrigins: 'https://example.com', + domainName: 'example.com', + }); + const origins = buildCorsOrigins(config); + expect(origins).toContain('https://example.com'); + }); + + test('does NOT auto-include localhost', () => { + const config = createMockConfig({ corsOrigins: 'https://example.com' }); + const origins = buildCorsOrigins(config); + expect(origins).not.toContain('http://localhost:4200'); + }); + + test('returns empty array when corsOrigins is empty and no extras', () => { + const config = createMockConfig({ corsOrigins: '', domainName: undefined }); + const origins = buildCorsOrigins(config); + expect(origins).toEqual([]); + }); + + test('localhost is included only when explicitly in corsOrigins', () => { + const config = createMockConfig({ corsOrigins: 'https://example.com,http://localhost:4200' }); + const origins = buildCorsOrigins(config); + expect(origins).toContain('http://localhost:4200'); + expect(origins).toContain('https://example.com'); + }); + }); + + // ============================================================ + // Layer 2: Additional origins are appended + // ============================================================ + + describe('Layer 2: additional origins appended', () => { + test('appends additionalOrigins parameter', () => { + const config = createMockConfig({ corsOrigins: 'https://example.com' }); + const origins = buildCorsOrigins(config, 'https://extra.com'); + expect(origins).toContain('https://example.com'); + expect(origins).toContain('https://extra.com'); + }); + + test('appends multiple comma-separated additional origins', () => { + const config = createMockConfig({ corsOrigins: 'https://example.com' }); + const origins = buildCorsOrigins(config, 'https://a.com,https://b.com'); + expect(origins).toContain('https://a.com'); + expect(origins).toContain('https://b.com'); + }); + + test('handles undefined additionalOrigins gracefully', () => { + const config = createMockConfig({ corsOrigins: 'https://example.com' }); + const origins = buildCorsOrigins(config, undefined); + expect(origins).toEqual(['https://example.com']); + }); + + test('handles empty string additionalOrigins', () => { + const config = createMockConfig({ corsOrigins: 'https://example.com' }); + const origins = buildCorsOrigins(config, ''); + expect(origins).toEqual(['https://example.com']); + }); + + test('localhost can be added via additionalOrigins', () => { + const config = createMockConfig({ corsOrigins: 'https://example.com' }); + const origins = buildCorsOrigins(config, 'http://localhost:4200'); + expect(origins).toContain('http://localhost:4200'); + expect(origins).toContain('https://example.com'); + }); + }); + + // ============================================================ + // Deduplication + // ============================================================ + + describe('deduplication', () => { + test('deduplicates when corsOrigins and additionalOrigins overlap', () => { + const config = createMockConfig({ corsOrigins: 'https://example.com' }); + const origins = buildCorsOrigins(config, 'https://example.com'); + const count = origins.filter(o => o === 'https://example.com').length; + expect(count).toBe(1); + }); + + test('deduplicates localhost when in both corsOrigins and additionalOrigins', () => { + const config = createMockConfig({ corsOrigins: 'http://localhost:4200,https://example.com' }); + const origins = buildCorsOrigins(config, 'http://localhost:4200'); + const count = origins.filter(o => o === 'http://localhost:4200').length; + expect(count).toBe(1); + }); + }); + + // ============================================================ + // Whitespace handling + // ============================================================ + + describe('whitespace handling', () => { + test('trims whitespace from origins', () => { + const config = createMockConfig({ corsOrigins: ' https://example.com , https://other.com ' }); + const origins = buildCorsOrigins(config); + expect(origins).toContain('https://example.com'); + expect(origins).toContain('https://other.com'); + }); + + test('filters out empty strings from splitting', () => { + const config = createMockConfig({ corsOrigins: 'https://example.com,,,' }); + const origins = buildCorsOrigins(config); + expect(origins).not.toContain(''); + }); + }); +}); + +// ============================================================ +// loadConfig corsOrigins derivation tests +// ============================================================ + +describe('loadConfig CORS derivation', () => { + let app: cdk.App; + let originalEnv: NodeJS.ProcessEnv; + + beforeEach(() => { + originalEnv = { ...process.env }; + app = new cdk.App(); + app.node.setContext('projectPrefix', 'test-project'); + app.node.setContext('awsRegion', 'us-east-1'); + app.node.setContext('awsAccount', '123456789012'); + app.node.setContext('vpcCidr', '10.0.0.0/16'); + app.node.setContext('domainName', 'test.example.com'); + app.node.setContext('frontend', { enabled: true, cloudFrontPriceClass: 'PriceClass_100' }); + app.node.setContext('appApi', { enabled: true, cpu: 256, memory: 512, desiredCount: 1, maxCapacity: 4 }); + app.node.setContext('inferenceApi', { enabled: true, cpu: 256, memory: 512, desiredCount: 1, maxCapacity: 4, logLevel: 'INFO' }); + app.node.setContext('gateway', { enabled: true, apiType: 'REST', throttleRateLimit: 1000, throttleBurstLimit: 2000, enableWaf: false }); + app.node.setContext('assistants', { enabled: true }); + app.node.setContext('fileUpload', { enabled: true, maxFileSizeBytes: 4194304, maxFilesPerMessage: 5, userQuotaBytes: 1073741824, retentionDays: 365 }); + app.node.setContext('ragIngestion', { enabled: true, additionalCorsOrigins: '', lambdaMemorySize: 10240, lambdaTimeout: 900, embeddingModel: 'amazon.titan-embed-text-v2', vectorDimension: 1024, vectorDistanceMetric: 'cosine' }); + }); + + afterEach(() => { + process.env = originalEnv; + }); + + test('corsOrigins includes domain when CDK_DOMAIN_NAME is set via context', () => { + const config = loadConfig(app); + expect(config.corsOrigins).toContain('https://test.example.com'); + }); + + test('corsOrigins includes domain when CDK_DOMAIN_NAME is set via env var', () => { + process.env.CDK_DOMAIN_NAME = 'env.example.com'; + const config = loadConfig(app); + expect(config.corsOrigins).toContain('https://env.example.com'); + }); + + test('CDK_DOMAIN_NAME env var takes precedence over context domainName', () => { + process.env.CDK_DOMAIN_NAME = 'env.example.com'; + const config = loadConfig(app); + expect(config.corsOrigins).toContain('https://env.example.com'); + expect(config.corsOrigins).not.toContain('https://test.example.com'); + }); + + test('CDK_CORS_ORIGINS appends to domain-derived origin', () => { + process.env.CDK_CORS_ORIGINS = 'https://extra.com'; + const config = loadConfig(app); + expect(config.corsOrigins).toContain('https://test.example.com'); + expect(config.corsOrigins).toContain('https://extra.com'); + }); + + test('CDK_CORS_ORIGINS does NOT replace domain-derived origin', () => { + process.env.CDK_CORS_ORIGINS = 'https://only-this.com'; + const config = loadConfig(app); + expect(config.corsOrigins).toContain('https://test.example.com'); + expect(config.corsOrigins).toContain('https://only-this.com'); + }); + + test('corsOrigins is empty when no domain and no extras', () => { + app.node.setContext('domainName', ''); + app.node.setContext('fileUpload', { enabled: false, maxFileSizeBytes: 4194304, maxFilesPerMessage: 5, userQuotaBytes: 1073741824, retentionDays: 365 }); + const config = loadConfig(app); + expect(config.corsOrigins).toBe(''); + }); + + test('context corsOrigins appends to domain (not replaces)', () => { + app.node.setContext('corsOrigins', 'https://context-extra.com'); + const config = loadConfig(app); + expect(config.corsOrigins).toContain('https://test.example.com'); + expect(config.corsOrigins).toContain('https://context-extra.com'); + }); + + test('buildCorsOrigins with loaded config includes domain only (no auto-localhost)', () => { + const config = loadConfig(app); + const origins = buildCorsOrigins(config); + expect(origins).toContain('https://test.example.com'); + expect(origins).not.toContain('http://localhost:4200'); + }); + + test('buildCorsOrigins with section extras appends them', () => { + app.node.setContext('ragIngestion', { + enabled: true, + additionalCorsOrigins: 'https://rag-extra.com', + lambdaMemorySize: 10240, lambdaTimeout: 900, + embeddingModel: 'amazon.titan-embed-text-v2', vectorDimension: 1024, vectorDistanceMetric: 'cosine', + }); + const config = loadConfig(app); + const origins = buildCorsOrigins(config, config.ragIngestion.additionalCorsOrigins); + expect(origins).toContain('https://test.example.com'); + expect(origins).toContain('https://rag-extra.com'); + }); + + test('real-world: alpha.boisestate.ai + poop.com global + pee.com inference-only', () => { + process.env.CDK_DOMAIN_NAME = 'alpha.boisestate.ai'; + process.env.CDK_CORS_ORIGINS = 'https://poop.com'; + process.env.CDK_INFERENCE_API_CORS_ORIGINS = 'https://pee.com'; + const config = loadConfig(app); + + // Global origins (app-api, frontend, etc.) + const globalOrigins = buildCorsOrigins(config); + expect(globalOrigins).toContain('https://alpha.boisestate.ai'); + expect(globalOrigins).toContain('https://poop.com'); + expect(globalOrigins).not.toContain('https://pee.com'); + + // Inference-api origins (global + section extra) + const inferenceOrigins = buildCorsOrigins(config, config.inferenceApi.additionalCorsOrigins); + expect(inferenceOrigins).toContain('https://alpha.boisestate.ai'); + expect(inferenceOrigins).toContain('https://poop.com'); + expect(inferenceOrigins).toContain('https://pee.com'); + }); + + test('real-world: local dev with CDK_CORS_ORIGINS=http://localhost:4200', () => { + app.node.setContext('domainName', ''); + app.node.setContext('fileUpload', { enabled: false, maxFileSizeBytes: 4194304, maxFilesPerMessage: 5, userQuotaBytes: 1073741824, retentionDays: 365 }); + process.env.CDK_CORS_ORIGINS = 'http://localhost:4200'; + const config = loadConfig(app); + const origins = buildCorsOrigins(config); + expect(origins).toEqual(['http://localhost:4200']); + }); +}); diff --git a/infrastructure/test/helpers/mock-config.ts b/infrastructure/test/helpers/mock-config.ts index be50c71c..74eea733 100644 --- a/infrastructure/test/helpers/mock-config.ts +++ b/infrastructure/test/helpers/mock-config.ts @@ -47,7 +47,6 @@ export function createMockConfig(overrides: Partial = {}): AppConfig maxCapacity: 2, imageTag: 'latest', logLevel: 'INFO', - corsOrigins: 'http://localhost:4200', }, gateway: { enabled: true, @@ -58,7 +57,6 @@ export function createMockConfig(overrides: Partial = {}): AppConfig }, assistants: { enabled: true, - corsOrigins: 'http://localhost:4200', }, fileUpload: { enabled: true, @@ -69,7 +67,6 @@ export function createMockConfig(overrides: Partial = {}): AppConfig }, ragIngestion: { enabled: true, - corsOrigins: 'http://localhost:4200', lambdaMemorySize: 3008, lambdaTimeout: 900, embeddingModel: 'amazon.titan-embed-text-v2', @@ -80,6 +77,10 @@ export function createMockConfig(overrides: Partial = {}): AppConfig enabled: false, defaultQuotaHours: 0, }, + cognito: { + domainPrefix: MOCK_PREFIX, + passwordMinLength: 8, + }, tags: { ManagedBy: 'CDK', Environment: 'test' }, }; @@ -133,6 +134,8 @@ const SSM_READS_BY_STACK: Record = { 'auth/auth-provider-secrets-arn', 'user-file-uploads/table-arn', 'user-file-uploads/bucket-arn', + 'auth/cognito/user-pool-id', + 'auth/cognito/app-client-id', ], AppApiStack: [ 'network/vpc-id', @@ -173,8 +176,12 @@ const SSM_READS_BY_STACK: Record = { 'admin/managed-models-table-arn', 'auth/auth-providers-table-name', 'auth/auth-providers-table-arn', - 'auth/auth-providers-stream-arn', 'auth/auth-provider-secrets-arn', + 'auth/cognito/user-pool-arn', + 'auth/cognito/user-pool-id', + 'auth/cognito/app-client-id', + 'auth/cognito/issuer-url', + 'auth/cognito/domain-url', 'rag/documents-bucket-name', 'rag/assistants-table-name', 'rag/vector-bucket-name', @@ -182,7 +189,6 @@ const SSM_READS_BY_STACK: Record = { 'inference-api/memory-id', 'rag/documents-bucket-arn', 'rag/assistants-table-arn', - 'inference-api/runtime-execution-role-arn', 'inference-api/memory-arn', 'fine-tuning/jobs-table-name', 'fine-tuning/jobs-table-arn', @@ -258,6 +264,9 @@ function getMockValueForParam(suffix: string): string { if (suffix.includes('index-name')) return 'mock-vector-index'; if (suffix.includes('lambda') || suffix.includes('provisioner') || suffix.includes('updater')) return 'arn:aws:lambda:us-east-1:123456789012:function:mock-fn'; if (suffix.includes('url')) return 'https://mock-api.example.com'; + if (suffix.includes('user-pool-arn')) return 'arn:aws:cognito-idp:us-east-1:123456789012:userpool/us-east-1_MockPool'; + if (suffix.includes('user-pool-id')) return 'us-east-1_MockPool'; + if (suffix.includes('app-client-id')) return 'mock-app-client-id'; if (suffix.includes('cors')) return 'http://localhost:4200'; return 'mock-value'; } diff --git a/infrastructure/test/inference-api-stack.test.ts b/infrastructure/test/inference-api-stack.test.ts index afd20b34..2a9cee2a 100644 --- a/infrastructure/test/inference-api-stack.test.ts +++ b/infrastructure/test/inference-api-stack.test.ts @@ -102,36 +102,38 @@ describe('InferenceApiStack', () => { }); test('has Memory access permissions', () => { - template.hasResourceProperties('AWS::IAM::Policy', { - PolicyDocument: Match.objectLike({ - Statement: Match.arrayWith([ - Match.objectLike({ - Sid: 'MemoryAccess', - Effect: 'Allow', - Action: Match.arrayWith([ - 'bedrock-agentcore:CreateEvent', - 'bedrock-agentcore:RetrieveMemory', - ]), - }), - ]), - }), + const inlinePolicies = template.findResources('AWS::IAM::Policy'); + const managedPolicies = template.findResources('AWS::IAM::ManagedPolicy'); + const allPolicies = { ...inlinePolicies, ...managedPolicies }; + + const hasMemoryAccess = Object.values(allPolicies).some((resource: any) => { + const statements = resource.Properties?.PolicyDocument?.Statement ?? []; + return statements.some((s: any) => + s.Sid === 'MemoryAccess' && + s.Effect === 'Allow' && + Array.isArray(s.Action) && + s.Action.includes('bedrock-agentcore:CreateEvent') && + s.Action.includes('bedrock-agentcore:RetrieveMemory') + ); }); + expect(hasMemoryAccess).toBe(true); }); test('has Code Interpreter access permissions', () => { - template.hasResourceProperties('AWS::IAM::Policy', { - PolicyDocument: Match.objectLike({ - Statement: Match.arrayWith([ - Match.objectLike({ - Sid: 'CodeInterpreterAccess', - Effect: 'Allow', - Action: Match.arrayWith([ - 'bedrock-agentcore:InvokeCodeInterpreter', - ]), - }), - ]), - }), + const inlinePolicies = template.findResources('AWS::IAM::Policy'); + const managedPolicies = template.findResources('AWS::IAM::ManagedPolicy'); + const allPolicies = { ...inlinePolicies, ...managedPolicies }; + + const hasCodeInterpreterAccess = Object.values(allPolicies).some((resource: any) => { + const statements = resource.Properties?.PolicyDocument?.Statement ?? []; + return statements.some((s: any) => + s.Sid === 'CodeInterpreterAccess' && + s.Effect === 'Allow' && + Array.isArray(s.Action) && + s.Action.includes('bedrock-agentcore:InvokeCodeInterpreter') + ); }); + expect(hasCodeInterpreterAccess).toBe(true); }); test('has Browser access permissions', () => { @@ -150,6 +152,16 @@ describe('InferenceApiStack', () => { }); }); + describe('AgentCore Runtime', () => { + test('runtime environment includes CORS_ORIGINS', () => { + template.hasResourceProperties('AWS::BedrockAgentCore::Runtime', { + EnvironmentVariables: Match.objectLike({ + CORS_ORIGINS: Match.anyValue(), + }), + }); + }); + }); + describe('AgentCore Memory', () => { test('CfnMemory resource exists', () => { template.hasResourceProperties('AWS::BedrockAgentCore::Memory', { @@ -189,8 +201,8 @@ describe('InferenceApiStack', () => { }); describe('SSM Parameters', () => { - test('creates 8 SSM parameters', () => { - template.resourceCountIs('AWS::SSM::Parameter', 8); + test('creates 12 SSM parameters', () => { + template.resourceCountIs('AWS::SSM::Parameter', 12); }); test('exports runtime execution role ARN', () => { @@ -274,39 +286,6 @@ describe('InferenceApiStack', () => { }); }); - // ============================================================ - // SSM Parameters (Required for Deploy Script) - // ============================================================ - - describe('SSM Parameters for Runtime Updates', () => { - test('creates image-tag parameter for runtime-updater trigger', () => { - template.hasResourceProperties('AWS::SSM::Parameter', { - Name: `/${config.projectPrefix}/inference-api/image-tag`, - Type: 'String', - Description: Match.stringLikeRegexp('.*image tag.*'), - }); - }); - - test('runtime-updater Lambda has permission to read image-tag parameter', () => { - // The runtime-updater needs to read this parameter when triggered - template.hasResourceProperties('AWS::IAM::Policy', { - PolicyDocument: Match.objectLike({ - Statement: Match.arrayWith([ - Match.objectLike({ - Action: Match.arrayWith(['ssm:GetParameter']), - Effect: 'Allow', - Resource: Match.arrayWith([ - Match.objectLike({ - 'Fn::Sub': Match.stringLikeRegexp('.*inference-api/image-tag.*'), - }), - ]), - }), - ]), - }), - }); - }); - }); - // ============================================================ // X-Ray Resource Name Length Limits // ============================================================ diff --git a/infrastructure/test/infrastructure-stack.test.ts b/infrastructure/test/infrastructure-stack.test.ts index 099981ac..b1770606 100644 --- a/infrastructure/test/infrastructure-stack.test.ts +++ b/infrastructure/test/infrastructure-stack.test.ts @@ -110,8 +110,8 @@ describe('InfrastructureStack', () => { // ------------------------------------------------------------------ // 6. All DynamoDB tables are created (count) // ------------------------------------------------------------------ - test('creates all 14 DynamoDB tables', () => { - template.resourceCountIs('AWS::DynamoDB::Table', 14); + test('creates all 16 DynamoDB tables', () => { + template.resourceCountIs('AWS::DynamoDB::Table', 16); }); // ------------------------------------------------------------------ @@ -216,7 +216,7 @@ describe('InfrastructureStack', () => { test('UserFiles table has PK/SK, TTL, stream, and SessionIndex GSI', () => { template.hasResourceProperties('AWS::DynamoDB::Table', { - TableName: Match.stringLikeRegexp('user-files'), + TableName: Match.stringLikeRegexp('user-file-uploads'), KeySchema: Match.arrayWith([ { AttributeName: 'PK', KeyType: 'HASH' }, { AttributeName: 'SK', KeyType: 'RANGE' }, diff --git a/infrastructure/test/rag-ingestion-stack.test.ts b/infrastructure/test/rag-ingestion-stack.test.ts index b5fa6d56..38b3d92b 100644 --- a/infrastructure/test/rag-ingestion-stack.test.ts +++ b/infrastructure/test/rag-ingestion-stack.test.ts @@ -51,7 +51,6 @@ describe('RagIngestionStack', () => { maxCapacity: 4, imageTag: 'latest', logLevel: 'INFO', - corsOrigins: 'http://localhost:3000', }, gateway: { enabled: true, @@ -69,11 +68,11 @@ describe('RagIngestionStack', () => { }, assistants: { enabled: true, - corsOrigins: 'http://localhost:3000,https://example.com', + additionalCorsOrigins: 'http://localhost:3000,https://example.com', }, ragIngestion: { enabled: true, - corsOrigins: 'http://localhost:3000,https://example.com', + additionalCorsOrigins: 'http://localhost:3000,https://example.com', lambdaMemorySize: 3008, lambdaTimeout: 900, embeddingModel: 'amazon.titan-embed-text-v2', @@ -84,6 +83,10 @@ describe('RagIngestionStack', () => { enabled: false, defaultQuotaHours: 0, }, + cognito: { + domainPrefix: 'test-project', + passwordMinLength: 8, + }, tags: { ManagedBy: 'CDK', }, @@ -114,7 +117,7 @@ describe('RagIngestionStack', () => { describe('S3 Documents Bucket', () => { test('creates S3 bucket with correct name', () => { template.hasResourceProperties('AWS::S3::Bucket', { - BucketName: 'test-project-rag-documents', + BucketName: 'test-project-rag-documents-123456789012', }); }); @@ -175,13 +178,13 @@ describe('RagIngestionStack', () => { describe('S3 Vectors Bucket and Index', () => { test('creates S3 Vectors bucket with correct name', () => { template.hasResourceProperties('AWS::S3Vectors::VectorBucket', { - VectorBucketName: 'test-project-rag-vector-store-v1', + VectorBucketName: 'test-project-rag-vector-store-v1-123456789012', }); }); test('creates vector index with correct configuration', () => { template.hasResourceProperties('AWS::S3Vectors::Index', { - VectorBucketName: 'test-project-rag-vector-store-v1', + VectorBucketName: 'test-project-rag-vector-store-v1-123456789012', IndexName: 'test-project-rag-vector-index-v1', DataType: 'float32', Dimension: 1024, @@ -409,7 +412,7 @@ describe('RagIngestionStack', () => { Variables: { S3_ASSISTANTS_DOCUMENTS_BUCKET_NAME: Match.anyValue(), DYNAMODB_ASSISTANTS_TABLE_NAME: Match.anyValue(), - S3_ASSISTANTS_VECTOR_STORE_BUCKET_NAME: 'test-project-rag-vector-store-v1', + S3_ASSISTANTS_VECTOR_STORE_BUCKET_NAME: 'test-project-rag-vector-store-v1-123456789012', S3_ASSISTANTS_VECTOR_STORE_INDEX_NAME: 'test-project-rag-vector-index-v1', BEDROCK_REGION: 'us-east-1', }, @@ -497,8 +500,8 @@ describe('RagIngestionStack', () => { ], Effect: 'Allow', Resource: Match.arrayWith([ - Match.stringLikeRegexp('arn:aws:s3vectors:.*:.*:bucket/.*rag-vector-store-v1'), - Match.stringLikeRegexp('arn:aws:s3vectors:.*:.*:bucket/.*rag-vector-store-v1/index/.*rag-vector-index-v1'), + Match.stringLikeRegexp('arn:aws:s3vectors:.*:.*:bucket/.*rag-vector-store-v1.*'), + Match.stringLikeRegexp('arn:aws:s3vectors:.*:.*:bucket/.*rag-vector-store-v1.*/index/.*rag-vector-index-v1'), ]), }), ]), @@ -605,7 +608,7 @@ describe('RagIngestionStack', () => { template.hasResourceProperties('AWS::SSM::Parameter', { Name: '/test-project/rag/vector-bucket-name', Type: 'String', - Value: 'test-project-rag-vector-store-v1', + Value: 'test-project-rag-vector-store-v1-123456789012', Description: 'RAG vector store bucket name', }); }); @@ -754,7 +757,7 @@ describe('RagIngestionStack', () => { (r: any) => r.Type === 'AWS::DynamoDB::Table' ) as any; const lambda = Object.values(resources).find( - (r: any) => r.Type === 'AWS::Lambda::Function' + (r: any) => r.Type === 'AWS::Lambda::Function' && r.Properties?.FunctionName ) as any; expect(bucket.Properties.BucketName).toContain('rag-documents'); diff --git a/infrastructure/test/sagemaker-fine-tuning-stack.test.ts b/infrastructure/test/sagemaker-fine-tuning-stack.test.ts index 50abe97b..8028babb 100644 --- a/infrastructure/test/sagemaker-fine-tuning-stack.test.ts +++ b/infrastructure/test/sagemaker-fine-tuning-stack.test.ts @@ -184,23 +184,9 @@ describe('SageMakerFineTuningStack', () => { template.hasResourceProperties('AWS::S3::Bucket', { LifecycleConfiguration: { Rules: Match.arrayWith([ - Match.objectLike({ - Id: 'transition-to-ia', - Transitions: [ - { StorageClass: 'STANDARD_IA', TransitionInDays: 30 }, - ], - Status: 'Enabled', - }), - Match.objectLike({ - Id: 'transition-to-glacier', - Transitions: [ - { StorageClass: 'GLACIER_IR', TransitionInDays: 90 }, - ], - Status: 'Enabled', - }), Match.objectLike({ Id: 'expire-objects', - ExpirationInDays: 365, + ExpirationInDays: 30, Status: 'Enabled', }), Match.objectLike({ diff --git a/infrastructure/test/stack-dependencies.test.ts b/infrastructure/test/stack-dependencies.test.ts index ce34d2fb..a620f184 100644 --- a/infrastructure/test/stack-dependencies.test.ts +++ b/infrastructure/test/stack-dependencies.test.ts @@ -392,7 +392,6 @@ describe('Stack Dependency Order', () => { test('AppApiStack reads from InferenceApiStack', () => { const appReads = reads.get('AppApiStack')!; expect(appReads.has('inference-api/memory-id')).toBe(true); - expect(appReads.has('inference-api/runtime-execution-role-arn')).toBe(true); }); test('AppApiStack reads from RagIngestionStack', () => { diff --git a/package-lock.json b/package-lock.json deleted file mode 100644 index 917c9d9c..00000000 --- a/package-lock.json +++ /dev/null @@ -1,6 +0,0 @@ -{ - "name": "agentcore-public-stack", - "lockfileVersion": 3, - "requires": true, - "packages": {} -} diff --git a/scripts/common/load-env.sh b/scripts/common/load-env.sh index fc3e8d58..002ed0b5 100644 --- a/scripts/common/load-env.sh +++ b/scripts/common/load-env.sh @@ -152,9 +152,6 @@ build_cdk_context_params() { if [ -n "${ENV_INFERENCE_API_LOG_LEVEL:-}" ]; then context_params="${context_params} --context inferenceApi.logLevel=\"${ENV_INFERENCE_API_LOG_LEVEL}\"" fi - if [ -n "${ENV_INFERENCE_API_CORS_ORIGINS:-}" ]; then - context_params="${context_params} --context inferenceApi.corsOrigins=\"${ENV_INFERENCE_API_CORS_ORIGINS}\"" - fi # Gateway optional parameters if [ -n "${CDK_GATEWAY_ENABLED:-}" ]; then @@ -275,6 +272,9 @@ export CDK_RAG_LAMBDA_TIMEOUT="${CDK_RAG_LAMBDA_TIMEOUT:-$(get_json_value "ragIn # SageMaker Fine-Tuning configuration export CDK_FINE_TUNING_ENABLED="${CDK_FINE_TUNING_ENABLED:-$(get_json_value "fineTuning.enabled" "${CONTEXT_FILE}")}" +# Cognito configuration (optional — defaults to projectPrefix for domain prefix) +export CDK_COGNITO_DOMAIN_PREFIX="${CDK_COGNITO_DOMAIN_PREFIX:-$(get_json_value "cognito.domainPrefix" "${CONTEXT_FILE}")}" + # AWS Account - try multiple sources (env vars take precedence) CDK_CONTEXT_ACCOUNT=$(get_json_value "awsAccount" "${CONTEXT_FILE}") export CDK_AWS_ACCOUNT="${CDK_AWS_ACCOUNT:-${CDK_CONTEXT_ACCOUNT:-${CDK_DEFAULT_ACCOUNT:-${AWS_ACCOUNT_ID:-}}}}" diff --git a/deploy.sh b/scripts/deploy.sh similarity index 100% rename from deploy.sh rename to scripts/deploy.sh diff --git a/scripts/stack-bootstrap/seed.sh b/scripts/stack-bootstrap/seed.sh index a71c4b23..3ffb7e01 100755 --- a/scripts/stack-bootstrap/seed.sh +++ b/scripts/stack-bootstrap/seed.sh @@ -20,25 +20,9 @@ main() { local prefix="${CDK_PROJECT_PREFIX}" local region="${CDK_AWS_REGION}" - # Resolve DynamoDB table names and Secrets Manager ARN from SSM + # Resolve DynamoDB table names from SSM log_info "Resolving resource names from SSM Parameter Store..." - export DDB_AUTH_PROVIDERS_TABLE - DDB_AUTH_PROVIDERS_TABLE=$(aws ssm get-parameter \ - --name "/${prefix}/auth/auth-providers-table-name" \ - --region "${region}" \ - --query "Parameter.Value" \ - --output text) - log_info "Auth providers table: ${DDB_AUTH_PROVIDERS_TABLE}" - - export SECRETS_AUTH_ARN - SECRETS_AUTH_ARN=$(aws ssm get-parameter \ - --name "/${prefix}/auth/auth-provider-secrets-arn" \ - --region "${region}" \ - --query "Parameter.Value" \ - --output text) - log_info "Auth secrets ARN: ${SECRETS_AUTH_ARN:0:50}..." - export DDB_USER_QUOTAS_TABLE DDB_USER_QUOTAS_TABLE=$(aws ssm get-parameter \ --name "/${prefix}/quota/user-quotas-table-name" \ diff --git a/scripts/stack-frontend/build.sh b/scripts/stack-frontend/build.sh index 161b30af..c0feb5e4 100644 --- a/scripts/stack-frontend/build.sh +++ b/scripts/stack-frontend/build.sh @@ -78,6 +78,18 @@ if [ "${IS_DEPLOYMENT_BUILD}" = true ]; then log_info "Environment configuration:" log_info " APP_API_URL: ${APP_API_URL}" log_info " PRODUCTION: ${PRODUCTION}" + if [ -n "${COGNITO_DOMAIN_URL:-}" ]; then + log_info " COGNITO_DOMAIN_URL: ${COGNITO_DOMAIN_URL}" + fi + if [ -n "${COGNITO_APP_CLIENT_ID:-}" ]; then + log_info " COGNITO_APP_CLIENT_ID: ${COGNITO_APP_CLIENT_ID}" + fi + if [ -n "${COGNITO_REGION:-}" ]; then + log_info " COGNITO_REGION: ${COGNITO_REGION}" + fi + if [ -n "${INFERENCE_API_URL:-}" ]; then + log_info " INFERENCE_API_URL: ${INFERENCE_API_URL}" + fi # Backup original environment file if [ ! -f "${ENV_FILE}.backup" ]; then @@ -93,6 +105,20 @@ if [ "${IS_DEPLOYMENT_BUILD}" = true ]; then -e "s|appApiUrl: 'http://localhost:8000'|appApiUrl: '${APP_API_URL}'|g" \ "${ENV_FILE}.backup" > "${ENV_FILE}" + # Inject optional Cognito and inference API values if set + if [ -n "${COGNITO_DOMAIN_URL:-}" ]; then + sed -i "s|cognitoDomainUrl: ''|cognitoDomainUrl: '${COGNITO_DOMAIN_URL}'|g" "${ENV_FILE}" + fi + if [ -n "${COGNITO_APP_CLIENT_ID:-}" ]; then + sed -i "s|cognitoAppClientId: ''|cognitoAppClientId: '${COGNITO_APP_CLIENT_ID}'|g" "${ENV_FILE}" + fi + if [ -n "${COGNITO_REGION:-}" ]; then + sed -i "s|cognitoRegion: 'us-east-1'|cognitoRegion: '${COGNITO_REGION}'|g" "${ENV_FILE}" + fi + if [ -n "${INFERENCE_API_URL:-}" ]; then + sed -i "s|inferenceApiUrl: 'http://localhost:8001'|inferenceApiUrl: '${INFERENCE_API_URL}'|g" "${ENV_FILE}" + fi + log_info "Environment values injected successfully" else log_info "Local development build - using localhost defaults from environment.ts" diff --git a/scripts/stack-frontend/install.sh b/scripts/stack-frontend/install.sh old mode 100644 new mode 100755 index 3206b9da..4385ee8e --- a/scripts/stack-frontend/install.sh +++ b/scripts/stack-frontend/install.sh @@ -1,12 +1,15 @@ #!/bin/bash -# Frontend install script - Install Angular dependencies -# This script installs all frontend dependencies using npm ci +# Frontend install script - Install Angular and CDK dependencies +# This script installs all dependencies needed by the frontend workflow: +# 1. Angular frontend dependencies (npm ci) +# 2. CDK infrastructure dependencies (npm ci) set -euo pipefail # Get the repository root directory REPO_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)" FRONTEND_DIR="${REPO_ROOT}/frontend/ai.client" +INFRA_DIR="${REPO_ROOT}/infrastructure" # Colors for output RED='\033[0;31m' @@ -23,6 +26,14 @@ log_error() { echo -e "${RED}[ERROR]${NC} $1" } +log_success() { + echo -e "${GREEN}[SUCCESS]${NC} $1" +} + +# =========================================================== +# Install Frontend Dependencies +# =========================================================== + # Check if frontend directory exists if [ ! -d "${FRONTEND_DIR}" ]; then log_error "Frontend directory not found: ${FRONTEND_DIR}" @@ -68,9 +79,26 @@ else exit 1 fi -log_info "Frontend dependencies installed successfully!" +log_success "Frontend dependencies installed successfully!" # Display Angular CLI version if available if [ -f "node_modules/.bin/ng" ]; then log_info "Angular CLI version: $(./node_modules/.bin/ng version --version 2>/dev/null || echo 'unknown')" fi + +# =========================================================== +# Install CDK Dependencies +# =========================================================== + +log_info "Installing CDK dependencies..." +cd "${INFRA_DIR}" + +if [ -f "package-lock.json" ]; then + log_info "Running npm ci (clean install from package-lock.json)..." + npm ci +else + log_error "package-lock.json not found. Cannot run npm ci." + exit 1 +fi + +log_success "CDK dependencies installed successfully" diff --git a/specs/ADMIN_OAUTH_PROVIDER_SPEC.md b/specs/ADMIN_OAUTH_PROVIDER_SPEC.md deleted file mode 100644 index da30a1b7..00000000 --- a/specs/ADMIN_OAUTH_PROVIDER_SPEC.md +++ /dev/null @@ -1,281 +0,0 @@ -OAuth Provider Management Implementation Plan -Overview -Implement OAuth connection management per specs/ADMIN_OAUTH_PROVIDER_SPEC.md. Enables admins to configure OAuth providers (Google, Microsoft, Canvas, etc.) and users to connect accounts for MCP tool requests. - -Phase 1: Infrastructure (CDK) -File to modify: infrastructure/lib/app-api-stack.ts -1.1 Add KMS Key (~line 920, after existing tables) -typescriptconst oauthTokenEncryptionKey = new kms.Key(this, "OAuthTokenEncryptionKey", { - alias: getResourceName(config, "oauth-token-key"), - description: "KMS key for encrypting OAuth user tokens at rest", - enableKeyRotation: true, - removalPolicy: config.environment === "prod" ? cdk.RemovalPolicy.RETAIN : cdk.RemovalPolicy.DESTROY, -}); -1.2 OAuth Providers Table -typescriptconst oauthProvidersTable = new dynamodb.Table(this, "OAuthProvidersTable", { - tableName: getResourceName(config, "oauth-providers"), - partitionKey: { name: "PK", type: dynamodb.AttributeType.STRING }, - sortKey: { name: "SK", type: dynamodb.AttributeType.STRING }, - billingMode: dynamodb.BillingMode.PAY_PER_REQUEST, - pointInTimeRecovery: true, - removalPolicy: config.environment === "prod" ? cdk.RemovalPolicy.RETAIN : cdk.RemovalPolicy.DESTROY, - encryption: dynamodb.TableEncryption.AWS_MANAGED, -}); - -oauthProvidersTable.addGlobalSecondaryIndex({ - indexName: "EnabledProvidersIndex", - partitionKey: { name: "GSI1PK", type: dynamodb.AttributeType.STRING }, - sortKey: { name: "GSI1SK", type: dynamodb.AttributeType.STRING }, - projectionType: dynamodb.ProjectionType.ALL, -}); -1.3 OAuth User Tokens Table (with KMS encryption) -typescriptconst oauthUserTokensTable = new dynamodb.Table(this, "OAuthUserTokensTable", { - tableName: getResourceName(config, "oauth-user-tokens"), - partitionKey: { name: "PK", type: dynamodb.AttributeType.STRING }, - sortKey: { name: "SK", type: dynamodb.AttributeType.STRING }, - billingMode: dynamodb.BillingMode.PAY_PER_REQUEST, - pointInTimeRecovery: true, - removalPolicy: config.environment === "prod" ? cdk.RemovalPolicy.RETAIN : cdk.RemovalPolicy.DESTROY, - encryption: dynamodb.TableEncryption.CUSTOMER_MANAGED, - encryptionKey: oauthTokenEncryptionKey, -}); - -oauthUserTokensTable.addGlobalSecondaryIndex({ - indexName: "ProviderUsersIndex", - partitionKey: { name: "GSI1PK", type: dynamodb.AttributeType.STRING }, - sortKey: { name: "GSI1SK", type: dynamodb.AttributeType.STRING }, - projectionType: dynamodb.ProjectionType.ALL, -}); -1.4 Secrets Manager for Client Secrets -typescriptconst oauthClientSecretsSecret = new secretsmanager.Secret(this, "OAuthClientSecretsSecret", { - secretName: getResourceName(config, "oauth-client-secrets"), - description: "OAuth provider client secrets (JSON: {provider_id: secret})", - removalPolicy: cdk.RemovalPolicy.RETAIN, -}); -1.5 SSM Parameters -typescriptnew ssm.StringParameter(this, "OAuthProvidersTableNameParameter", { - parameterName: `/${config.projectPrefix}/oauth/providers-table-name`, - stringValue: oauthProvidersTable.tableName, - tier: ssm.ParameterTier.STANDARD, -}); -new ssm.StringParameter(this, "OAuthUserTokensTableNameParameter", { - parameterName: `/${config.projectPrefix}/oauth/user-tokens-table-name`, - stringValue: oauthUserTokensTable.tableName, - tier: ssm.ParameterTier.STANDARD, -}); -new ssm.StringParameter(this, "OAuthTokenEncryptionKeyArnParameter", { - parameterName: `/${config.projectPrefix}/oauth/token-encryption-key-arn`, - stringValue: oauthTokenEncryptionKey.keyArn, - tier: ssm.ParameterTier.STANDARD, -}); -1.6 IAM Grants & Environment Variables -Add to ECS task role grants: -typescriptoauthProvidersTable.grantReadWriteData(taskDefinition.taskRole); -oauthUserTokensTable.grantReadWriteData(taskDefinition.taskRole); -oauthTokenEncryptionKey.grantEncryptDecrypt(taskDefinition.taskRole); -oauthClientSecretsSecret.grantRead(taskDefinition.taskRole); -Add to container environment: -typescriptDYNAMODB_OAUTH_PROVIDERS_TABLE_NAME: oauthProvidersTable.tableName, -DYNAMODB_OAUTH_USER_TOKENS_TABLE_NAME: oauthUserTokensTable.tableName, -OAUTH_TOKEN_ENCRYPTION_KEY_ARN: oauthTokenEncryptionKey.keyArn, -OAUTH_CLIENT_SECRETS_ARN: oauthClientSecretsSecret.secretArn, - -Phase 2: Backend Python Module -2.1 Dependencies -File: backend/pyproject.toml - Add: -tomlauthlib = "^1.3.0" -cachetools = "^5.3.0" -2.2 New Files to Create -FilePurposebackend/src/apis/app_api/oauth/__init__.pyModule exportsbackend/src/apis/app_api/oauth/models.pyPydantic modelsbackend/src/apis/app_api/oauth/encryption.pyKMS encrypt/decryptbackend/src/apis/app_api/oauth/token_cache.pyTTLCache (5 min)backend/src/apis/app_api/oauth/provider_repository.pyProvider CRUDbackend/src/apis/app_api/oauth/token_repository.pyToken CRUDbackend/src/apis/app_api/oauth/service.pyOAuth flow logicbackend/src/apis/app_api/oauth/routes.pyUser endpointsbackend/src/apis/app_api/admin/oauth/__init__.pyAdmin modulebackend/src/apis/app_api/admin/oauth/routes.pyAdmin endpoints -2.3 Models (oauth/models.py) - -OAuthProviderType enum: google, microsoft, github, canvas, custom -OAuthConnectionStatus enum: connected, expired, revoked, needs_reauth -OAuthProvider dataclass with to_dynamo_item()/from_dynamo_item() -OAuthUserToken dataclass with encryption helpers -compute_scopes_hash() for change detection -Request/Response Pydantic models - -2.4 Encryption (oauth/encryption.py) -pythonclass TokenEncryptionService: - def encrypt(self, plaintext: str) -> str: ... - def decrypt(self, ciphertext: str) -> str: ... -2.5 Service (oauth/service.py) -Key methods: - -initiate_connect(provider_id, user_id) → authorization_url -handle_callback(code, state) → store encrypted tokens -get_decrypted_token(user_id, provider_id) → access_token -disconnect(user_id, provider_id) → delete tokens -check_needs_reauth(user_token, provider) → scope hash comparison - -Reuse existing StateStore from apis/shared/auth/state_store.py for OAuth state. -2.6 Admin Routes (admin/oauth/routes.py) - -POST /admin/oauth-providers/ - Create provider -GET /admin/oauth-providers/ - List all -GET /admin/oauth-providers/{id} - Get one -PATCH /admin/oauth-providers/{id} - Update -DELETE /admin/oauth-providers/{id} - Delete - -2.7 User Routes (oauth/routes.py) - -GET /oauth/providers - List available (filtered by user roles) -GET /oauth/connections - List user's connections -GET /oauth/connect/{provider_id} - Start OAuth flow -GET /oauth/callback - Handle callback, redirect to frontend -DELETE /oauth/connections/{provider_id} - Disconnect - -2.8 Wire Routes -File: backend/src/apis/app_api/admin/routes.py - Add at bottom: -pythonfrom .oauth.routes import router as oauth_admin_router -router.include_router(oauth_admin_router) -File: backend/src/apis/app_api/main.py - Add: -pythonfrom apis.app_api.oauth.routes import router as oauth_router -app.include_router(oauth_router) - -Phase 3: Admin UI (Angular) -3.1 New Files -FilePurposeadmin/oauth-providers/models/oauth-provider.model.tsTypeScript interfacesadmin/oauth-providers/services/oauth-providers.service.tsHTTP + resourceadmin/oauth-providers/pages/provider-list.page.tsList with search/filteradmin/oauth-providers/pages/provider-form.page.tsCreate/edit form -3.2 Models (oauth-provider.model.ts) -typescriptexport interface OAuthProvider { - providerId: string; - displayName: string; - providerType: 'google' | 'microsoft' | 'github' | 'canvas' | 'custom'; - authorizationEndpoint: string; - tokenEndpoint: string; - clientId: string; - scopes: string[]; - allowedRoles: string[]; - enabled: boolean; - iconName: string; - createdAt: string; - updatedAt: string; -} - -export interface OAuthProviderCreateRequest { ... } -export interface OAuthProviderUpdateRequest { ... } -3.3 Service Pattern (follow app-roles.service.ts) -typescript@Injectable({ providedIn: 'root' }) -export class OAuthProvidersService { - readonly providersResource = resource({ - loader: async () => { ... } - }); - // CRUD methods -} -3.4 List Page Pattern (follow role-list.page.ts) - -Card grid layout with provider icons -Search by name signal -Filter by enabled status -Edit/Delete actions with tooltips - -3.5 Form Page Pattern (follow role-form.page.ts) - -Provider type dropdown with endpoint presets -Client ID / Client Secret (password field) -Scopes input (comma-separated or tags) -Role restrictions multi-select -Enabled toggle - -3.6 Update Routes -File: frontend/ai.client/src/app/app.routes.ts - Add: -typescript{ - path: 'admin/oauth-providers', - loadComponent: () => import('./admin/oauth-providers/pages/provider-list.page').then(m => m.ProviderListPage), - canActivate: [adminGuard], -}, -{ - path: 'admin/oauth-providers/new', - loadComponent: () => import('./admin/oauth-providers/pages/provider-form.page').then(m => m.ProviderFormPage), - canActivate: [adminGuard], -}, -{ - path: 'admin/oauth-providers/edit/:providerId', - loadComponent: () => import('./admin/oauth-providers/pages/provider-form.page').then(m => m.ProviderFormPage), - canActivate: [adminGuard], -}, -3.7 Update Admin Dashboard -File: frontend/ai.client/src/app/admin/admin.page.ts - Add to features array: -typescript{ - title: 'OAuth Providers', - description: 'Configure third-party OAuth integrations for tool access', - icon: 'heroLink', - route: '/admin/oauth-providers', -} - -Phase 4: User Connections UI (Angular) -4.1 New Files -FilePurposesettings/connections/models/oauth-connection.model.tsInterfacessettings/connections/services/connections.service.tsHTTP + resourcesettings/connections/connections.page.tsMain page -4.2 Connections Page Features - -List available providers with icons -Connect/Disconnect buttons -Status badges (Connected, Needs Reauth, Not Connected) -Handle callback query params (?success=true, ?error=...) -Toast notifications - -4.3 Connect Flow -typescriptasync connect(providerId: string): Promise { - const response = await firstValueFrom( - this.http.get<{ authorization_url: string }>(`${this.baseUrl}/oauth/connect/${providerId}`) - ); - window.location.href = response.authorization_url; -} -4.4 Update Routes -File: frontend/ai.client/src/app/app.routes.ts - Add: -typescript{ - path: 'settings/connections', - loadComponent: () => import('./settings/connections/connections.page').then(m => m.ConnectionsPage), - canActivate: [authGuard], -}, -4.5 Update User Dropdown -File: frontend/ai.client/src/app/components/topnav/components/user-dropdown.component.ts -Add after "My Files" menu item: -html - - Connections - - -DynamoDB Schema Summary -OAuth Providers Table -Access PatternKeyIndexGet providerPK=PROVIDER#{id}, SK=CONFIGBaseList enabledGSI1PK=ENABLED#trueEnabledProvidersIndex -OAuth User Tokens Table -Access PatternKeyIndexGet user tokenPK=USER#{user_id}, SK=PROVIDER#{provider_id}BaseList user tokensPK=USER#{user_id}BaseList by providerGSI1PK=PROVIDER#{provider_id}ProviderUsersIndex - -Security Considerations - -Client secrets stored in Secrets Manager (never exposed to frontend) -User tokens encrypted with KMS at rest -State tokens are one-time use (reuse existing StateStore pattern) -PKCE required for all OAuth flows (S256) -Scope hash detects provider config changes, prompts re-auth -Role-based filtering on available providers - - -Verification Steps -Phase 1 -bashcd infrastructure && npx cdk diff AppApiStack -npx cdk deploy AppApiStack -# Verify in AWS Console: DynamoDB tables, KMS key, Secrets Manager -Phase 2 -bashcd backend -uv sync --extra agentcore --extra dev -uv run python -m pytest tests/test_oauth.py -v -# Start API and test endpoints with curl -Phase 3 -bashcd frontend/ai.client -npm install && npm run build -# Navigate to /admin/oauth-providers, create test provider -Phase 4 -bash# Navigate to /settings/connections -# Test Connect flow with configured provider -# Verify callback redirect and status display - -Implementation Order - -Phase 1: CDK - Deploy infrastructure first -Phase 2: Backend - Models → Repositories → Service → Routes -Phase 3: Admin UI - Models → Service → List → Form -Phase 4: User UI - Models → Service → Page → Dropdown menu item \ No newline at end of file diff --git a/specs/QUOTA_BUDGET_MODEL_DOWNGRADE.md b/specs/QUOTA_BUDGET_MODEL_DOWNGRADE.md deleted file mode 100644 index cac991ed..00000000 --- a/specs/QUOTA_BUDGET_MODEL_DOWNGRADE.md +++ /dev/null @@ -1,732 +0,0 @@ -# Quota Budget Model Downgrade Feature Specification - -## Overview - -This specification describes a new quota enforcement action that automatically downgrades users to a cost-effective "budget model" when they approach their quota limit, with a hard stop at 100%. - -**Feature Name:** Budget Model Downgrade -**Status:** Draft -**Created:** 2026-01-05 -**Author:** AgentCore Team - ---- - -## Problem Statement - -Currently, quota enforcement offers two options: -1. **Block**: Hard stop at 100% - users cannot continue working -2. **Warn**: No enforcement - users can exceed quota indefinitely - -Neither option provides a middle ground that: -- Allows users to continue working when approaching limits -- Reduces cost accumulation as users near their quota -- Provides a graceful degradation experience - ---- - -## Proposed Solution - -Add a third `action_on_limit` option: **`downgrade`** - -When enabled: -- At **90%** (configurable threshold): Automatically switch to a cheaper "budget model" -- At **100%**: Hard stop (same as `block` action) - -This allows users to continue working with reduced capabilities while preventing quota overruns. - ---- - -## User Stories - -### Admin Stories - -1. **As an admin**, I want to configure a quota tier that automatically switches users to a cheaper model when they reach 90% of their quota, so that users can continue working while controlling costs. - -2. **As an admin**, I want to specify which budget model to use for downgraded sessions, so that I can balance cost savings with acceptable user experience. - -3. **As an admin**, I want to set a custom threshold (e.g., 85%, 90%, 95%) for when the downgrade kicks in, so that I can tune the experience per tier. - -### User Stories - -1. **As a user**, I want to be notified when I've been downgraded to a budget model, so that I understand why responses may differ. - -2. **As a user**, I want to continue chatting even when approaching my quota limit, so that I can complete urgent tasks. - -3. **As a user**, I want to see my current quota status and whether I'm in "budget mode", so that I can manage my usage. - ---- - -## Technical Design - -### 1. Data Model Changes - -#### 1.1 QuotaTier Model (Backend) - -**File:** `backend/src/agents/main_agent/quota/models.py` - -```python -class QuotaTier(BaseModel): - # ... existing fields ... - - # Expand action_on_limit to include "downgrade" - action_on_limit: Literal["block", "warn", "downgrade"] = Field( - default="block", - alias="actionOnLimit" - ) - - # New fields for downgrade action - budget_model_id: Optional[str] = Field( - None, - alias="budgetModelId", - description="Model ID to use when downgrade action triggers. Required if action_on_limit is 'downgrade'." - ) - - downgrade_threshold: Decimal = Field( - default=Decimal("90.0"), - alias="downgradeThreshold", - ge=0, - lt=100, - description="Percentage at which to switch to budget model. Must be less than 100." - ) - - @model_validator(mode='after') - def validate_downgrade_config(self): - """Ensure budget_model_id is set when action is downgrade""" - if self.action_on_limit == "downgrade" and not self.budget_model_id: - raise ValueError("budget_model_id is required when action_on_limit is 'downgrade'") - return self -``` - -#### 1.2 QuotaCheckResult Model (Backend) - -**File:** `backend/src/agents/main_agent/quota/models.py` - -```python -class QuotaCheckResult(BaseModel): - # ... existing fields ... - - # New fields for downgrade status - is_downgraded: bool = Field( - default=False, - alias="isDowngraded", - description="True if user has been downgraded to budget model" - ) - - downgrade_model_id: Optional[str] = Field( - None, - alias="downgradeModelId", - description="Budget model ID to use if is_downgraded is True" - ) - - original_model_id: Optional[str] = Field( - None, - alias="originalModelId", - description="The model that would have been used without downgrade" - ) -``` - -#### 1.3 Frontend TypeScript Models - -**File:** `frontend/ai.client/src/app/admin/quota-tiers/models/quota.models.ts` - -```typescript -export type ActionOnLimit = 'block' | 'warn' | 'downgrade'; - -export interface QuotaTier { - tierId: string; - tierName: string; - description?: string; - - // Limits - monthlyCostLimit: number; - dailyCostLimit?: number; - periodType: PeriodType; - - // Soft limits - softLimitPercentage: number; - actionOnLimit: ActionOnLimit; - - // Downgrade configuration (new) - budgetModelId?: string; - downgradeThreshold?: number; - - // Metadata - enabled: boolean; - createdAt: string; - updatedAt: string; - createdBy: string; -} - -export interface QuotaTierCreate { - // ... existing fields ... - budgetModelId?: string; - downgradeThreshold?: number; -} - -export interface QuotaTierUpdate { - // ... existing fields ... - budgetModelId?: string; - downgradeThreshold?: number; -} -``` - -### 2. DynamoDB Schema Changes - -**Table:** `user-quotas` (quota tiers partition) - -Add new attributes to tier items: -| Attribute | Type | Description | -|-----------|------|-------------| -| `budgetModelId` | String | Model ID for budget mode (e.g., `us.amazon.nova-micro-v1:0`) | -| `downgradeThreshold` | Number | Percentage threshold (0-99) | - -No new GSIs required - existing queries remain unchanged. - -### 3. QuotaChecker Logic - -**File:** `backend/src/agents/main_agent/quota/checker.py` - -```python -async def check_quota(self, user: User, session_id: Optional[str] = None) -> QuotaCheckResult: - # ... existing resolution and usage lookup ... - - # Handle downgrade action - if tier.action_on_limit == "downgrade": - downgrade_threshold = float(tier.downgrade_threshold) - - # At or above 100% → hard block - if percentage_used >= 100: - await self.event_recorder.record_block(...) - return QuotaCheckResult( - allowed=False, - message=f"Quota exceeded: ${current_usage:.2f} / ${limit:.2f}", - tier=tier, - current_usage=current_usage, - quota_limit=limit, - percentage_used=percentage_used, - remaining=0.0, - warning_level="100%", - is_downgraded=False # Blocked, not downgraded - ) - - # At or above downgrade threshold → use budget model - if percentage_used >= downgrade_threshold: - await self.event_recorder.record_downgrade( - user=user, - tier=tier, - current_usage=current_usage, - limit=limit, - percentage_used=percentage_used, - budget_model=tier.budget_model_id, - session_id=session_id - ) - - return QuotaCheckResult( - allowed=True, - message=f"Using budget model (${current_usage:.2f} / ${limit:.2f})", - tier=tier, - current_usage=current_usage, - quota_limit=limit, - percentage_used=percentage_used, - remaining=remaining, - warning_level=f"{int(downgrade_threshold)}%", - is_downgraded=True, - downgrade_model_id=tier.budget_model_id - ) - - # ... existing block/warn logic ... -``` - -### 4. Chat Routes Integration - -**File:** `backend/src/apis/app_api/chat/routes.py` - -```python -@router.post("/stream") -async def chat_stream(request: ChatRequest, current_user: User = Depends(get_current_user)): - # ... existing tool filtering ... - - # Check quota - quota_warning_event = None - quota_exceeded_event = None - quota_downgrade_event = None - model_override = None - - if is_quota_enforcement_enabled(): - try: - quota_checker = get_quota_checker() - quota_result = await quota_checker.check_quota( - user=current_user, - session_id=request.session_id - ) - - if not quota_result.allowed: - # Quota exceeded - stream as SSE - quota_exceeded_event = build_quota_exceeded_event(quota_result) - elif quota_result.is_downgraded: - # Downgraded to budget model - model_override = quota_result.downgrade_model_id - quota_downgrade_event = build_quota_downgrade_event(quota_result) - logger.info( - f"User {user_id} downgraded to budget model: {model_override} " - f"({quota_result.percentage_used:.1f}% quota used)" - ) - else: - # Check for warning - quota_warning_event = build_quota_warning_event(quota_result) - except Exception as e: - logger.error(f"Error checking quota: {e}", exc_info=True) - - # ... handle quota_exceeded_event (existing) ... - - # Create agent with potential model override - agent = get_agent( - session_id=request.session_id, - user_id=user_id, - enabled_tools=authorized_tools, - model_id=model_override # None uses default, otherwise uses budget model - ) - - async def stream_with_cleanup(): - # Emit downgrade event first if applicable - if quota_downgrade_event: - yield quota_downgrade_event.to_sse_format() - - # Emit warning event if applicable (and not downgraded) - if quota_warning_event and not quota_downgrade_event: - yield quota_warning_event.to_sse_format() - - # ... rest of streaming logic ... -``` - -### 5. SSE Event Types - -**File:** `backend/src/apis/shared/quota.py` - -```python -class QuotaDowngradeEvent(BaseModel): - """SSE event for quota-based model downgrade notification""" - model_config = ConfigDict(populate_by_name=True) - - type: str = "quota_downgrade" - budget_model_id: str = Field(..., alias="budgetModelId") - original_model_id: Optional[str] = Field(None, alias="originalModelId") - current_usage: float = Field(..., alias="currentUsage") - quota_limit: float = Field(..., alias="quotaLimit") - percentage_used: float = Field(..., alias="percentageUsed") - threshold: float = Field(..., description="Downgrade threshold percentage") - message: str = Field(..., description="User-friendly notification message") - - def to_sse_format(self) -> str: - """Convert to SSE event format""" - import json - return f"event: quota_downgrade\ndata: {json.dumps(self.model_dump(by_alias=True, exclude_none=True))}\n\n" - - -def build_quota_downgrade_event(result: QuotaCheckResult) -> QuotaDowngradeEvent: - """Build a quota downgrade SSE event from QuotaCheckResult""" - percentage = int(result.percentage_used) - threshold = int(result.tier.downgrade_threshold) if result.tier else 90 - - # User-friendly model name mapping - model_names = { - "us.amazon.nova-micro-v1:0": "Nova Micro", - "us.amazon.nova-lite-v1:0": "Nova Lite", - "us.anthropic.claude-haiku-4-5-20251001-v1:0": "Claude Haiku", - } - - budget_name = model_names.get(result.downgrade_model_id, result.downgrade_model_id) - - message = ( - f"You've used {percentage}% of your quota. " - f"Switching to {budget_name} to help conserve your remaining balance." - ) - - return QuotaDowngradeEvent( - budgetModelId=result.downgrade_model_id, - originalModelId=result.original_model_id, - currentUsage=float(result.current_usage), - quotaLimit=float(result.quota_limit) if result.quota_limit else 0.0, - percentageUsed=float(result.percentage_used), - threshold=float(threshold), - message=message - ) -``` - -### 6. Event Recording - -**File:** `backend/src/agents/main_agent/quota/event_recorder.py` - -Add new event type and recording method: - -```python -async def record_downgrade( - self, - user: User, - tier: QuotaTier, - current_usage: float, - limit: float, - percentage_used: float, - budget_model: str, - session_id: Optional[str] = None, - assignment_id: Optional[str] = None -) -> None: - """Record a quota downgrade event""" - event = QuotaEvent( - event_id=str(uuid.uuid4()), - user_id=user.user_id, - tier_id=tier.tier_id, - event_type="downgrade", # New event type - current_usage=Decimal(str(current_usage)), - quota_limit=Decimal(str(limit)), - percentage_used=Decimal(str(percentage_used)), - timestamp=datetime.utcnow().isoformat(), - metadata={ - "budget_model": budget_model, - "threshold": float(tier.downgrade_threshold), - "session_id": session_id, - "assignment_id": assignment_id - } - ) - - await self.repository.create_quota_event(event) - logger.info(f"Recorded downgrade event for user {user.user_id}: switched to {budget_model}") -``` - -Update `QuotaEvent.event_type`: -```python -event_type: Literal["warning", "block", "reset", "override_applied", "downgrade"] -``` - -### 7. Frontend Admin UI - -#### 7.1 Tier Detail Form Component - -**File:** `frontend/ai.client/src/app/admin/quota-tiers/pages/tier-detail/tier-detail.component.ts` - -```typescript -interface TierFormGroup { - // ... existing controls ... - actionOnLimit: FormControl; - budgetModelId: FormControl; - downgradeThreshold: FormControl; -} - -// In component class -readonly tierForm: FormGroup = this.fb.group({ - // ... existing controls ... - actionOnLimit: this.fb.control('block', { nonNullable: true }), - budgetModelId: this.fb.control(null), - downgradeThreshold: this.fb.control(90, { - nonNullable: true, - validators: [Validators.min(1), Validators.max(99)] - }), -}); - -// Computed signal for showing downgrade options -readonly showDowngradeOptions = computed(() => - this.tierForm.controls.actionOnLimit.value === 'downgrade' -); - -// Available budget models (could be loaded from API) -readonly budgetModels = signal([ - { id: 'us.amazon.nova-micro-v1:0', name: 'Nova Micro (Cheapest)' }, - { id: 'us.amazon.nova-lite-v1:0', name: 'Nova Lite' }, - { id: 'us.anthropic.claude-haiku-4-5-20251001-v1:0', name: 'Claude Haiku' }, -]); -``` - -#### 7.2 Tier Detail Template - -**File:** `frontend/ai.client/src/app/admin/quota-tiers/pages/tier-detail/tier-detail.component.html` - -```html - -
-

Soft Limit & Action

- -
- - - - -
- -
- - - - - - - - -
-
- - - @if (showDowngradeOptions()) { -
- -
- - -

- Switch to budget model when usage reaches this percentage (1-99) -

-
- - -
- - -

- The model to use when user exceeds the downgrade threshold -

-
- - -
-

- How it works: Users will automatically switch to - the budget model at {{ tierForm.controls.downgradeThreshold.value }}% usage. - At 100%, requests will be blocked entirely. -

-
-
- } -
-
-``` - -### 8. Frontend User Notification - -#### 8.1 Stream Parser Updates - -**File:** `frontend/ai.client/src/app/session/services/chat/stream-parser.service.ts` - -```typescript -// Add signal for downgrade state -readonly quotaDowngrade = signal(null); - -// In parseEvent method -case 'quota_downgrade': - this.quotaDowngrade.set(data as QuotaDowngradeEvent); - break; -``` - -#### 8.2 Downgrade Banner Component - -**File:** `frontend/ai.client/src/app/components/quota-downgrade-banner/quota-downgrade-banner.component.ts` - -```typescript -@Component({ - selector: 'app-quota-downgrade-banner', - standalone: true, - imports: [NgIconComponent], - template: ` - @if (downgrade()) { -
- -
-

- {{ downgrade()?.message }} -

-

- {{ downgrade()?.percentageUsed | number:'1.0-0' }}% of quota used -

-
- -
- } - `, - changeDetection: ChangeDetectionStrategy.OnPush, -}) -export class QuotaDowngradeBannerComponent { - downgrade = input(null); - dismissed = output(); - - dismiss() { - this.dismissed.emit(); - } -} -``` - ---- - -## API Changes Summary - -### New/Modified Endpoints - -| Endpoint | Change | -|----------|--------| -| `POST /admin/quota/tiers` | Accept `budgetModelId`, `downgradeThreshold` | -| `PUT /admin/quota/tiers/{id}` | Accept `budgetModelId`, `downgradeThreshold` | -| `GET /admin/quota/tiers` | Return new fields | -| `GET /admin/quota/tiers/{id}` | Return new fields | - -### New SSE Event - -| Event | When Emitted | -|-------|--------------| -| `quota_downgrade` | User is downgraded to budget model (≥threshold, <100%) | - ---- - -## Migration Plan - -### Database Migration - -No schema migration required - DynamoDB is schemaless. New attributes will be added to items as tiers are created/updated. - -### Backward Compatibility - -- Existing tiers with `action_on_limit: "block"` or `"warn"` continue to work unchanged -- New fields (`budgetModelId`, `downgradeThreshold`) are optional for non-downgrade actions -- Frontend gracefully handles missing downgrade fields - -### Rollout Strategy - -1. **Phase 1**: Deploy backend changes (new fields, QuotaChecker logic) -2. **Phase 2**: Deploy frontend admin UI changes -3. **Phase 3**: Deploy frontend user notification components -4. **Phase 4**: Admin documentation and training - ---- - -## Testing Strategy - -### Unit Tests - -1. **QuotaTier validation**: Ensure `budgetModelId` required when `action_on_limit == "downgrade"` -2. **QuotaChecker**: Test all branches (below threshold, at threshold, at 100%) -3. **Event recording**: Verify downgrade events are recorded correctly - -### Integration Tests - -1. **End-to-end downgrade flow**: - - Create tier with downgrade action - - Assign to test user - - Simulate usage at threshold - - Verify budget model is used - - Verify SSE event emitted - -2. **Admin UI**: - - Create tier with downgrade config - - Edit existing tier to add downgrade - - Validation errors for missing budget model - -### Manual Testing Checklist - -- [ ] Admin can create tier with downgrade action -- [ ] Admin cannot save downgrade tier without budget model -- [ ] User sees downgrade banner when threshold reached -- [ ] Chat uses budget model after downgrade -- [ ] User is blocked at 100% (not just warned) -- [ ] Quota events table shows downgrade events -- [ ] Quota inspector shows downgrade status - ---- - -## Security Considerations - -1. **Model access control**: Ensure budget models are accessible to all users (no additional permissions needed) -2. **Rate limiting**: Downgrade events should be rate-limited to prevent spam -3. **Audit logging**: All downgrade events are recorded for compliance - ---- - -## Performance Considerations - -1. **Agent cache**: Downgraded sessions create new cache entries (different model_id) -2. **Event recording**: Async, non-blocking -3. **SSE overhead**: Single additional event, minimal impact - ---- - -## Open Questions - -1. **User opt-out?** Should users be able to prefer blocking over downgrade? -2. **Tool restrictions?** Should certain tools be disabled with budget models? -3. **Notification frequency?** Show banner once per session or persistently? -4. **Admin presets?** Provide "suggested" budget models per tier type? - ---- - -## Appendix: Model Cost Reference - -| Model ID | Relative Cost | Recommended For | -|----------|---------------|-----------------| -| `us.amazon.nova-micro-v1:0` | $$ (cheapest) | Simple Q&A, summaries | -| `us.amazon.nova-lite-v1:0` | $$$ | General tasks | -| `us.anthropic.claude-haiku-4-5-20251001-v1:0` | $$$$ | Coding, analysis | -| `us.anthropic.claude-sonnet-4-20250514-v1:0` | $$$$$ | Complex reasoning | - -Budget model selection should balance cost savings with acceptable user experience for the tier's intended use case.