orion/docs/proposals/test-api-deps-auth-dependencies.md

Test Plan: app/api/deps.py — Authentication Dependencies

Date: 2026-02-19 Status: Planned Priority: P0 — Security-critical, zero test coverage File under test: app/api/deps.py (1,668 lines, 31 functions)

Why This File Is Critical

deps.py is the single entry point for all authentication and authorization in the application. Every protected route depends on it. It enforces:

• Role isolation (admins can't access store routes, stores can't access admin routes)
• Cookie path restrictions (prevent cross-context token leakage)
• Token priority (Authorization header > cookie)
• Platform access control for platform admins
• Store permission checks (owner, team member, specific permissions)
• Merchant ownership verification
• Customer token validation with store-matching
• Module and menu-based access control

A bug here is a security vulnerability. Zero test coverage is unacceptable.

Current State

• Existing test coverage: None for deps.py directly
• Related tests: tests/integration/security/test_authentication.py (3 tests — basic endpoint protection only)
• Related tests: tests/unit/models/schema/test_auth.py (tests UserContext schema)

Test Structure

Tests will live at: tests/unit/api/test_deps.py

This follows the project convention of matching source layout (app/api/deps.py → tests/unit/api/test_deps.py).

Functions To Test (31 total)

Phase 1: Helper Functions (4 functions)

These are pure/near-pure functions — easiest to test, highest value as foundation.

Function	Lines	What it does	Test count
_get_token_from_request()	76–105	Extract token from header or cookie, header takes priority	4
_validate_user_token()	108–123	Validate JWT, return User model	3
_get_user_model()	126–155	Load User from DB by UserContext.id, copy token attrs	3
_validate_customer_token()	1026–1114	Decode customer JWT, verify type/expiry/store match	7

Tests for _get_token_from_request:

• Returns (token, "header") when Authorization header present
• Returns (token, "cookie") when only cookie present
• Header takes priority over cookie when both present
• Returns (None, None) when neither present

Tests for _validate_user_token:

• Returns User for valid token
• Raises InvalidTokenException for invalid/expired token
• Raises InvalidTokenException for token with non-existent user

Tests for _get_user_model:

• Returns User model with token attributes copied
• Raises InvalidTokenException when user not in DB
• Copies token_store_id, token_store_code, token_store_role from context

Tests for _validate_customer_token:

• Returns CustomerContext for valid customer token
• Rejects token with wrong type (not "customer")
• Rejects token with missing "sub" claim
• Rejects expired token
• Rejects token for non-existent customer
• Rejects token for inactive customer
• Rejects token with store_id mismatch (cross-store attack)

Phase 2: Admin Authentication (6 functions)

Function	Lines	What it does	Test count
get_current_admin_from_cookie_or_header()	163–209	Admin auth via cookie or header	4
get_current_admin_api()	212–242	Admin auth via header only (CSRF-safe)	3
get_current_super_admin()	250–283	Require super admin role	3
get_current_super_admin_api()	286–312	Super admin, header only	2
require_platform_access()	315–357	Factory: platform-specific admin access	4
get_admin_with_platform_context()	360–430	Admin with platform from JWT	4

Key tests:

• Valid admin token accepted (cookie and header)
• Non-admin role rejected with AdminRequiredException
• No token raises InvalidTokenException
• Super admin check: platform admin rejected
• Platform access: super admin bypasses, platform admin checked against accessible_platform_ids
• Platform context: platform_id extracted from token, stored in request.state

Phase 3: Store Authentication (2 functions)

Function	Lines	What it does	Test count
get_current_store_from_cookie_or_header()	665–720	Store auth via cookie or header	5
get_current_store_api()	723–780	Store API auth, validates store context	5

Key tests:

• Valid store token accepted
• Admin blocked from store routes (critical security boundary)
• Customer blocked from store routes
• No token raises InvalidTokenException
• Store API requires token_store_id claim
• Store API verifies user still member of store (revocation check)

Phase 4: Merchant Authentication (5 functions)

Function	Lines	What it does	Test count
get_current_merchant_from_cookie_or_header()	788–848	Merchant auth, verifies ownership	4
get_current_merchant_api()	851–896	Merchant API auth	3
get_current_merchant_optional()	899–940	Returns None if not authenticated	3
get_merchant_for_current_user()	943–979	Load Merchant object for API user	3
get_merchant_for_current_user_page()	982–1018	Load Merchant object for page user	2

Key tests:

• Valid merchant owner accepted
• User without active merchants rejected
• Optional variant returns None on failure (no exception)
• Merchant object stored in request.state

Phase 5: Customer Authentication (2 functions)

Function	Lines	What it does	Test count
get_current_customer_from_cookie_or_header()	1117–1156	Customer auth via cookie or header	3
get_current_customer_api()	1159–1185	Customer API auth	2

Key tests:

• Valid customer token accepted
• No token raises InvalidTokenException
• API variant requires Authorization header

Phase 6: Access Control (6 functions)

Function	Lines	What it does	Test count
require_module_access()	438–538	Factory: module enablement check	4
require_menu_access()	546–657	Factory: menu visibility check	4
require_store_permission()	1278–1324	Factory: specific permission check	4
require_store_owner()	1327–1369	Require store owner role	3
require_any_store_permission()	1372–1425	Factory: ANY of N permissions	3
require_all_store_permissions()	1428–1483	Factory: ALL of N permissions	3

Key tests:

• Module disabled → InsufficientPermissionsException
• Super admin bypasses module check
• Store owner has all permissions
• Team member checked against specific permissions
• Missing permission raises InsufficientStorePermissionsException

Phase 7: Optional Auth & Utilities (4 functions)

Function	Lines	What it does	Test count
get_current_admin_optional()	1535–1579	Returns None on failure	3
get_current_store_optional()	1582–1626	Returns None on failure	3
get_current_customer_optional()	1629–1667	Returns None on failure	3
get_user_permissions()	1486–1527	List all permissions for user in store	3
get_user_store()	1225–1270	Verify store ownership/membership	3

Key tests:

• Optional variants return None (not raise) when token invalid
• Optional variants return context when token valid
• get_user_permissions returns all permissions for owner, specific for team member

Total Test Count

Phase	Functions	Tests
1. Helpers	4	17
2. Admin auth	6	20
3. Store auth	2	10
4. Merchant auth	5	15
5. Customer auth	2	5
6. Access control	6	21
7. Optional & utils	5	15
Total	30	~103

Test Approach

Unit vs Integration

These will be unit tests with mocked dependencies:

• db → SQLAlchemy session with test data (using existing db fixture)
• auth_manager → Use the real AuthManager but with test users/tokens (existing auth_fixtures.py)
• request → Mock FastAPI Request with request.state, request.url.path
• FastAPI Depends() → Call functions directly, passing dependencies explicitly

This avoids the overhead of full HTTP request cycles and tests the logic in isolation.

Fixtures Needed

Most already exist in tests/fixtures/auth_fixtures.py:

• test_admin — admin user (is_super_admin=True)
• test_platform_admin — platform admin (is_super_admin=False)
• test_store_user — store-role user
• test_user — regular user

New fixtures to add in the test file:

• mock_request — Mock Request with configurable state and url.path
• test_customer — Customer model for customer auth tests
• test_merchant — Merchant model for merchant auth tests
• test_store — Store with platform association
• admin_token — JWT token for admin user
• store_token — JWT token with store context claims
• customer_token — Customer JWT token
• merchant_token — JWT token for merchant owner

Execution Order

1. Phase 1 first — helper functions have no dependencies on other deps.py functions
2. Phase 2–5 next — auth functions build on helpers
3. Phase 6–7 last — access control builds on auth functions

Phases 2–5 can be done in parallel. Phase 6 depends on 2–3 being done.

Verification

# Run just the deps tests
python -m pytest tests/unit/api/test_deps.py -v --timeout=60

# Run with coverage
python -m pytest tests/unit/api/test_deps.py -v --cov=app.api.deps --cov-report=term-missing

Corrected Coverage Summary

The earlier 360 analysis incorrectly reported module service coverage at 10%. The actual numbers (after finding tests in app/modules/*/tests/):

Module	Services	Unit Tests	Integration Tests	Coverage
billing	7	8	4	100%+
catalog	4	4	0	100%
checkout	1	1	0	100%
cms	4	4	0	100%
core	6	5	0	83%
customers	3	3	0	100%
dev_tools	2	2	0	100%
inventory	3	3	0	100%
loyalty	8	8	1	100%
marketplace	5	8	0	100%+
messaging	6	5	0	83%
monitoring	6	6	0	100%
orders	6	5	0	83%
payments	2	2	0	100%
tenancy	11	17	6	100%+
cart	1	1	0	100%
analytics	1	0	0	0%

Remaining gaps (non-service):

• Models: 12 modules have no model tests
• Schemas: 12 modules have no schema tests
• Routes: 14 modules have no route/integration tests
• Tasks: 0 modules have task tests (5 modules have tasks)
• Framework: app/api/deps.py, middleware/auth.py, app/exceptions/, app/handlers/stripe_webhook.py have no tests