Harden auth and security controls with session auth and docs

doc/data-model-reference.md

@@ -2,6 +2,38 @@
 
 Primary SQLAlchemy models are defined in `backend/app/models/`.
 
+## app_users
+
+Model: `AppUser` in `backend/app/models/auth.py`
+
+Purpose:
+- Stores authenticatable user identities for session-based API access.
+
+Core fields:
+- Identity and credentials: `id`, `username`, `password_hash`
+- Authorization and lifecycle: `role`, `is_active`
+- Audit timestamps: `created_at`, `updated_at`
+
+Enum `UserRole`:
+- `admin`
+- `user`
+
+## auth_sessions
+
+Model: `AuthSession` in `backend/app/models/auth.py`
+
+Purpose:
+- Stores issued bearer sessions linked to user identities.
+
+Core fields:
+- Identity and linkage: `id`, `user_id`, `token_hash`
+- Session lifecycle: `expires_at`, `revoked_at`
+- Request context: `user_agent`, `ip_address`
+- Audit timestamps: `created_at`, `updated_at`
+
+Foreign keys:
+- `user_id` references `app_users.id` with `ON DELETE CASCADE`.
+
 ## documents
 
 Model: `Document` in `backend/app/models/document.py`
@@ -12,7 +44,7 @@ Purpose:
 Core fields:
 - Identity and source: `id`, `original_filename`, `source_relative_path`, `stored_relative_path`
 - File attributes: `mime_type`, `extension`, `sha256`, `size_bytes`
-- Organization: `logical_path`, `suggested_path`, `tags`, `suggested_tags`
+- Ownership and organization: `owner_user_id`, `logical_path`, `suggested_path`, `tags`, `suggested_tags`
 - Processing outputs: `extracted_text`, `image_text_type`, `handwriting_style_id`, `preview_available`
 - Lifecycle and relations: `status`, `is_archive_member`, `archived_member_path`, `parent_document_id`, `replaces_document_id`
 - Metadata and timestamps: `metadata_json`, `created_at`, `processed_at`, `updated_at`
@@ -24,8 +56,12 @@ Enum `DocumentStatus`:
 - `error`
 - `trashed`
 
+Foreign keys:
+- `owner_user_id` references `app_users.id` with `ON DELETE SET NULL`.
+
 Relationships:
 - Self-referential `parent_document` relationship for archive extraction trees.
+- `owner_user` relationship to `AppUser`.
 
 ## processing_logs
 
@@ -47,7 +83,10 @@ Foreign keys:
 
 ## Model Lifecycle Notes
 
-- Upload inserts a `Document` row in `queued` state and enqueues background processing.
-- Worker updates extraction results and final status (`processed`, `unsupported`, or `error`).
+- API startup initializes schema and creates or refreshes bootstrap users from auth environment variables.
+- `POST /auth/login` validates `AppUser` credentials, creates `AuthSession` with hashed token, and returns bearer token once.
+- Upload inserts `Document` row in `queued` state, assigns `owner_user_id`, and enqueues background processing.
+- Worker updates extraction results and final status (`processed`, `unsupported`, or `error`), preserving ownership on archive descendants.
+- User-role queries are owner-scoped; admin-role queries can access all documents.
 - Trash and restore operations toggle `status` while preserving source files until permanent delete.
 - Permanent delete removes the document tree (including archive descendants) and associated stored files.