igny8/final-tenancy-accounts-payments/Tenancy_Audit_Report.md

Tenancy Audit — Detailed Report (Dec 2025)

This is a detailed, actionable audit of the tenancy model, controls, and billing/payment gaps in the codebase as of Dec 2025. It includes precise findings with file references, concrete fixes (code + DB migration), recommended tests, rollout/rollback guidance, and prioritised next steps.

Summary of actions already applied

• Removed role/system bypasses from account/site/sector filtering and permissions (changes under backend/igny8_core/... and mirrored in tenant/backend/igny8_core/...). These changes make tenant isolation strict: queries, creates and updates now require an account context and will fail/return empty if none is present.
• Updated Final_Flow_Tenancy.md to present Stripe and PayPal as placeholders and Bank Transfer as the active payment path (document-only change).

Methodology

• Code locations scanned (primary):
  • backend/igny8_core/auth/middleware.py (account injection & plan validation)
  • backend/igny8_core/api/base.py (AccountModelViewSet, SiteSectorModelViewSet)
  • backend/igny8_core/api/permissions.py (HasTenantAccess, role-based perms)
  • backend/igny8_core/api/throttles.py (DebugScopedRateThrottle)
  • backend/igny8_core/auth/models.py (User, Account, Plan, Subscription)
  • backend/igny8_core/api/authentication.py (JWTAuthentication, APIKeyAuthentication)
  • backend/igny8_core/business/billing/services/credit_service.py & backend/igny8_core/ai/engine.py (credits handling)
  • backend/igny8_core/auth/views.py (Site/Sector ViewSets)
• I searched occurrences of is_admin_or_developer, is_system_account, stripe_subscription_id, APIKeyAuthentication, and rate-throttle bypasses and inspected relevant code paths.

Detailed findings (evidence + impact)

1. Subscription / Payment model mismatch (High)

   • Evidence:
     • backend/igny8_core/auth/models.py::Subscription defines stripe_subscription_id = models.CharField(..., unique=True) and links subscription to account. There is no payment_method or external_payment_id field.
   • Impact:
     • Can't represent non-Stripe payments (bank transfer, PayPal) without schema changes. Current docs (Bank Transfer active) are inaccurate relative to DB constraints.
   • Recommended fix:
     • DB migration to:
       • Add payment_method enum/choices to Subscription and Account (values: stripe, paypal, bank_transfer), default stripe for backwards compatibility.
       • Add external_payment_id (nullable) to record external payment reference (e.g., bank transfer reference number / PayPal transaction id).
       • Make stripe_subscription_id nullable and remove unique constraint if you must support multiple non-Stripe flows. Migration steps:
         1. Add new nullable fields and keep old fields unchanged.
         2. Backfill payment_method='stripe' where stripe_subscription_id exists.
         3. Make stripe_subscription_id nullable and drop unique index if needed.
       • Update serializers, admin forms, and registration/subscription endpoints to accept payment_method.
   • Files: backend/igny8_core/auth/models.py, backend/igny8_core/api/serializers.py (where Subscription serializer exists), frontend forms.

2. API-key auth bypasses plan/status validation (High)

   • Evidence:
     • backend/igny8_core/api/authentication.py::APIKeyAuthentication sets request.account and request.site but does not call _validate_account_and_plan from middleware. The middleware (auth/middleware.py) runs plan validation only for session/JWT flows.
   • Impact:
     • WordPress bridge/API-key clients can access tenant-scoped endpoints even if the account is suspended or plan inactive.
   • Recommended fix:
     • In APIKeyAuthentication.authenticate(), after resolving account, call a shared validation helper (e.g., factor _validate_account_and_plan into auth/utils.py and call it here). If validation fails, raise AuthenticationFailed or return None.
     • Files: backend/igny8_core/api/authentication.py, backend/igny8_core/auth/middleware.py (extract validation helper), backend/igny8_core/auth/utils.py.
     • Tests: add API-key request tests for suspended/past-due accounts returning 402/403.

3. Role/system overrides removed but system-account function remains (Design decision needed) (Medium)

   • Evidence:
     • auth/models.py::Account.is_system_account() returns slug in ['aws-admin', 'default-account', 'default']. Many code paths previously used admin/dev/system overrides (these were removed).
   • Impact:
     • Potential residual special-casing exists (e.g., is_system_account_user()), and system accounts may need controlled, explicit privileges rather than silent bypasses.
   • Recommended action:
     • Decide: keep system accounts with tightly-scoped features (e.g., access to global monitoring endpoints only) OR remove hard-coded system slugs and manage via a features or is_system_account boolean that must be explicitly set.
     • Files to update/document: backend/igny8_core/auth/models.py, master-docs/00-system/*.

4. Throttle bypass broadness (Medium)

   • Evidence:
     • backend/igny8_core/api/throttles.py::DebugScopedRateThrottle currently bypasses throttling for any authenticated user (previously intended for admin/dev/system). This was simplified but remains permissive.
   • Impact:
     • Authenticated tenants are effectively unthrottled; DoS or excessive usage by a tenant is possible without tenant-specific limits.
   • Recommended fix:
     • Change to: bypass only when DEBUG or specific env var set OR user is in system account or developer role (if you reintroduce that concept intentionally). Otherwise enforce per-tenant/per-scope throttling.
     • Add tenant-specific rate bucket logic (e.g., throttle keys by account.id).
     • Files: backend/igny8_core/api/throttles.py.
     • Tests: verify throttling triggers for authenticated tenant requests above threshold.

5. Account injection & validation behavior (Medium)

   • Evidence:
     • backend/igny8_core/auth/middleware.py::AccountContextMiddleware skips middleware for request.path.startswith('/api/v1/auth/') and /admin/ and returns immediately in some JWT failure cases (silently allowing request.account = None).
   • Impact:
     • Some endpoints may not get account validated; middleware may "fail silently" and allowing unauthenticated or un-validated access in edge cases.
   • Recommended fix:
     • Harden error handling: log token decode errors at WARNING/ERROR, and fail requests explicitly where appropriate. For API-key or JWT failure, ensure any downstream endpoints guard properly (permissions should reject).
     • Consider removing silent fallback in production; allow session auth to handle user but ensure request.account is present for tenant endpoints.
     • Files: backend/igny8_core/auth/middleware.py.

6. Credit deduction consistent but missing pre-check hooks (Low)

   • Evidence:
     • backend/igny8_core/ai/engine.py automatically deducts credits via CreditService.deduct_credits_for_operation() after AI responses.
   • Impact:
     • Good centralisation; ensure pre-check (sufficient credits) is always called before AI invocation to avoid wasted external API calls.
   • Recommended fix:
     • Verify AIEngine.execute() or AICore calls CreditService.check_credits_legacy() or similar BEFORE making AI calls. If not, move pre-check earlier and make AI call cancellable if funds insufficient.
     • Files: backend/igny8_core/ai/engine.py, backend/igny8_core/business/billing/services/credit_service.py.

7. Registration & initial credits (Medium)

   • Evidence:
     • Final_Flow_Tenancy.md describes initial credits seeded from Plan.get_effective_credits_per_month() on registration.
     • Implementation: auth/views.py::register (inspected earlier) sets Account.credits on creation (confirm serializer/implementation).
   • Impact:
     • Ensure atomicity: create User + Account + Subscription and seed credits in a transaction to avoid partial creates.
   • Recommended fix:
     • Wrap registration flow in a DB transaction; move credit seeding into an idempotent service method.
     • Files: backend/igny8_core/auth/views.py, billing service modules.

8. Billing webhook architecture (Medium)

   • Evidence:
     • Billing flows refer largely to Stripe webhooks. Bank transfer is manual in doc; no webhook or admin confirmation API exists.
   • Impact:
     • Manual processes can lead to inconsistent states (account remains suspended when payment received).
   • Recommended changes:
     • Add admin endpoint to confirm bank transfer (secure endpoint, permissioned) which:
       • Accepts account_id/subscription_id, external_payment_id, payer details, proof (file or URL), amount, and sets Subscription.status='active' and updates Account.credits.
     • Add payment_proofs model or attach to CreditTransaction.
     • Files: new backend/igny8_core/billing/views.py, updates to backend/igny8_core/auth/models.py (Subscription), backend/igny8_core/business/billing/services/.

9. Tests & CI regression gaps (High)

   • Evidence:
     • No test coverage found for strict tenant filtering removal. No tests for API-key gate or bank-transfer flows.
   • Recommended test matrix:
     • Unit tests:
       • AccountModelViewSet.get_queryset() filters by request.account; returns none when request.account missing.
       • perform_create() raises PermissionDenied when account context missing for account-scoped models.
       • APIKeyAuthentication denies access when account is suspended or plan inactive.
       • DebugScopedRateThrottle enforces throttle when expected.
     • Integration tests:
       • Registration -> account created with credits seeded.
       • Bank transfer admin confirmation endpoint flow (once implemented).
     • Add to CI pipeline; fail on regressions.

Concrete code and DB changes (step-by-step)

1. Add payment fields migration (priority: HIGH)

   • Migration pseudo-steps:
     • Add payment_method = models.CharField(max_length=30, choices=PAYMENT_CHOICES, default='stripe') to Subscription and Account (nullable initially if you prefer).
     • Add external_payment_id = models.CharField(max_length=255, null=True, blank=True).
     • Make stripe_subscription_id nullable and drop unique constraint if necessary.
   • Update serializers and forms to accept payment_method.
   • Update register flow and any subscription creation flows to accept payment_method.

2. API-key validation (priority: HIGH)

   • Implementation:
     • Extract _validate_account_and_plan() from auth/middleware.py into auth/utils.py as validate_account_and_plan(account_or_user) -> None | (error, status).
     • Call that helper from APIKeyAuthentication.authenticate() immediately after obtaining account and before returning (user, api_key). On failure, raise AuthenticationFailed with the same message & HTTP semantics as middleware uses (map 402/403 to DRF errors).
   • Tests:
     • Add tests covering API key access for active vs past_due / canceled.

3. Throttle policy update (priority: MEDIUM)

   • Implementation:
     • Remove blanket authenticated bypass. Instead:
       • Keep debug_bypass and env variable bypass.
       • Add if is_system_account_user() or is_developer() optionally for debug environments only.
       • Add per-account throttle key using account.id or request.user.account.id.
     • Files: backend/igny8_core/api/throttles.py.

4. Harden middleware & logging (priority: MEDIUM)

   • Implementation:
     • Ensure token decode errors and other exceptions are logged. Fail louder in production (configurable).
     • For JWT absent but APIKey present, ensure account validation runs or permission classes enforce it.
     • Files: backend/igny8_core/auth/middleware.py.

5. Bank-transfer admin confirmation endpoint (priority: MEDIUM)

   • Implementation:
     • Endpoint: POST /api/v1/billing/confirm-bank-transfer/ (permissioned to IsAdminOrOwner or similar admin role).
     • Accepts: subscription_id | account_id, external_payment_id, amount, payer_name, proof_url or file upload.
     • Actions:
       • Mark Subscription.status='active', set current_period_start/end.
       • Set Subscription.payment_method='bank_transfer', store external_payment_id.
       • Add CreditTransaction entry and top up Account.credits to Plan.get_effective_credits_per_month() (or configured top-up).
     • Files: new backend/igny8_core/billing/views.py, backend/igny8_core/business/billing/services/.
     • Tests: bank transfer happy path; confirm idempotency (double-confirmation should be safe).

6. Tests & CI (priority: HIGH)

   • Add unit tests and integration tests described earlier. Run tests locally and include in CI gating.

Documentation & UX changes

• Update Final_Flow_Tenancy.md (already done) and master-docs/00-system/02-MULTITENANCY-MODEL.md to remove references to admin bypasses and document new account-only model.
• Update admin UI to:
  • Show payment_method on account/subscription pages.
  • Provide "Confirm Bank Transfer" action (with proof upload).
  • Mark Stripe/PayPal UI options as "coming soon" where relevant.

Rollout plan (safe incremental)

1. Create DB migrations (add nullable fields) and deploy with code that tolerates nulls. (no downtime)
2. Backfill payment_method='stripe' for existing subscriptions where stripe_subscription_id exists.
3. Deploy API changes to accept payment_method but keep Stripe/PayPal inactive in business logic.
4. Add admin confirmation endpoint and small UI changes; deploy.
5. Gradually switch registration/checkout UI to allow bank transfer (server-side honored immediately).
6. Add tests and enable stricter logging / monitoring.

Rollback guidance

• Revert deployments in order: UI -> backend code -> DB (reverse migration only if safe). Keep feature flags for enabling bank-transfer flows to toggle behavior without DB rollbacks.

Estimated effort & priorities

• Immediate (1–3 days): Add payment_method, external_payment_id fields (migration + serializer updates), API-key validation change, unit tests for API-key gating.
• Short (3–7 days): Implement bank-transfer confirmation endpoint, admin UI changes, and throttling policy adjustments + tests.
• Medium (1–3 weeks): Full rollout across frontend, integration with Stripe/PayPal placeholders, heavier monitoring, and end-to-end tests.

Appendix — Exact code touchpoints (recommendations)

• backend/igny8_core/auth/middleware.py — extract validation helper; improve logging.
• backend/igny8_core/api/authentication.py — add validation call in APIKeyAuthentication.
• backend/igny8_core/api/base.py — already updated to require account; verify all viewsets inherit this correctly.
• backend/igny8_core/api/permissions.py — reviewed and cleaned; add tests.
• backend/igny8_core/api/throttles.py — tighten bypass rules; add tenant-keyed throttling.
• backend/igny8_core/auth/models.py — add payment_method + external_payment_id, make stripe_subscription_id nullable.
• backend/igny8_core/business/billing/services/credit_service.py — ensure pre-checks before AI calls.
• New: backend/igny8_core/billing/views.py & backend/igny8_core/billing/serializers.py — bank transfer admin confirmation endpoint.

Next steps I can take (pick one and I'll implement):

1. Implement DB migration and model/serializer changes for payment_method + external_payment_id + make stripe_subscription_id nullable (create migrations, update code).
2. Implement API-key plan/status validation (small PR).
3. Implement bank-transfer confirmation endpoint and basic admin UI API (POST endpoint only).
4. Produce test cases and a tests PR skeleton (unittests + integration outlines).

If you'd like, I can start with implementing the DB migration and model changes (#1) and update serializers and the admin list/detail views, then add corresponding tests.