feat(repo): establish open-source visual identity suite, assets, anim…

.github/assets/README.md

@@ -0,0 +1,33 @@
+# Passli Visual Identity & Repository Assets
+
+This directory contains the visual branding, architecture infographics, UI previews, and animated demonstration assets for the **Passli** open-source repository.
+
+---
+
+## 🎨 Asset Catalog
+
+| Asset | File | Type | Resolution | Purpose |
+| :--- | :--- | :---: | :---: | :--- |
+| **Hero Banner** | [`passli-repo-banner.png`](passli-repo-banner.png) | Static Image (PNG) | 1376 × 768 (16:9) | Primary README header banner, social card, and project cover |
+| **Ephemeral Flow Demo** | [`passli-ephemeral-workflow.gif`](passli-ephemeral-workflow.gif) | Animated GIF | 1100 × 580 (58 frames) | Interactive demonstration of pass creation, 8-char key hashing, QR protocol, live countdown, and 1-click revocation |
+| **Vault Dashboard Preview** | [`passli-dashboard-preview.png`](passli-dashboard-preview.png) | Static Image (PNG) | 1376 × 768 (16:9) | High-fidelity UI mockup of the authenticated personal vault dashboard, telemetry, and document cards |
+| **Cryptographic Pipeline** | [`passli-cryptographic-pipeline.png`](passli-cryptographic-pipeline.png) | Static Image (PNG) | 1376 × 768 (16:9) | Architecture diagram depicting AES-256-GCM AEAD ingestion and in-memory streaming decryption |
+
+---
+
+## 🛠️ Regeneration & Build Tools
+
+The animated workflow demonstration (`passli-ephemeral-workflow.gif`) can be deterministically generated and optimized using Pillow:
+
+```bash
+python scripts/generate_ephemeral_flow_gif.py
+```
+
+### Design Standards & Palette
+Assets adhere strictly to Passli's **anti-ai-slop** and **unslop-ui v2** engineering standards:
+- **Background**: `#0B0F17` (Deep Obsidian) / `#111827` (Dark Slate)
+- **Primary Accent**: `#10B981` (Emerald Green)
+- **Secondary Accent**: `#06B6D4` (Electric Cyan)
+- **Danger / Revoke**: `#EF4444` (Ruby Red)
+- **Text Hierarchy**: `#F8FAFC` (Heading White), `#94A3B8` (Muted Slate), `#64748B` (Dim Slate)
+- **Typography**: Clean humanist sans-serif and monospace technical displays

PROGRESS.md

@@ -0,0 +1,132 @@
+# Passli Development Progress & Roadmap
+
+> **Current Milestone**: Full Project (Phases 1-7 & Security Audit Suite) 100% Completed & Verified (93/93 Automated Tests Passing)  
+> **Repository**: [github.com/Ali-Nawaz-devt/passli](https://github.com/Ali-Nawaz-devt/passli)  
+> **Status**: Production Ready & Fully Verified
+
+---
+
+## 📊 Phase-by-Phase Roadmap
+
+| Phase | Description | Status | Test Coverage |
+| :--- | :--- | :---: | :---: |
+| **Phase 1** | Project Setup, Anti-Slop Design System, Split-Hero & Landing Page | :white_check_mark: Completed | 100% (11/11 Tests) |
+| **Phase 2** | User Authentication, Registration & Personal Vault Dashboard | :white_check_mark: Completed | 100% (11/11 Tests) |
+| **Phase 3** | Encrypted Document Vault Management & Categorization | :white_check_mark: Completed | 100% (17/17 Tests) |
+| **Security Audit** | OWASP Top 10, IDOR Prevention, Upload Defense & Checksum Integrity | :white_check_mark: Completed | 100% (10/10 Tests) |
+| **Phase 4** | Controlled Share Pass Generation & Ephemeral QR Protocol | :white_check_mark: Completed | 100% (16/16 Tests) |
+| **Phase 5** | Recipient Verification Portal & Two-Factor Access Flow | :white_check_mark: Completed | 100% (14/14 Tests) |
+| **Phase 6** | Audit Trail, Immediate Revocation & Rate Limiting | :white_check_mark: Completed | 100% (13/13 Tests) |
+| **Phase 7** | End-to-End User Lifecycle Suite, Production Verification & Audit Report | :white_check_mark: Completed | 100% (1/1 E2E Suite) |
+
+---
+
+## 🎯 Phase Details & Deliverables
+
+
+### ✅ Phase 1: Foundation, Anti-Slop Design System & Landing Page
+- [x] Django 5 project initialized with modular app architecture (`accounts`, `documents`, `sharing`, `audit`, `config`).
+- [x] Vanilla CSS Design System with custom properties (`static/css/styles.css`).
+- [x] Human-crafted anti-AI-slop UI standards enforced (referencing `LeoStehlik/no-slop-ui` and `unslop-ui v2`).
+- [x] Clean Split-Hero layout with authentic high-resolution security photography.
+- [x] Interactive client-side Share Pass Generator simulator.
+- [x] Real-world scenario showcase (Clinic visits, Job KYC verification, Vehicle registration).
+- [x] Institutional Security Comparison Matrix (Passli vs Cloud Folders vs Email).
+- [x] Responsive navigation bar with verified on-page anchor targets.
+- [x] CodeRabbit review and rewrite protocol integrated into `AGENTS.md`.
+- [x] 11 automated unit tests created and verified in `tests/unit/test_phase1.py`.
+
+---
+
+### ✅ Phase 2: User Authentication & Personal Vault Dashboard
+- [x] Custom `RegisterForm` with email uniqueness validation and input styling.
+- [x] Custom `LoginForm` with credential sanitization and session handling.
+- [x] `register_view` with automatic session login and welcome messaging.
+- [x] `CustomLoginView` and `CustomLogoutView` with redirect targets.
+- [x] Protected `@login_required` `dashboard_view` calculating live vault metrics.
+- [x] Semantic HTML5 templates: `templates/accounts/login.html`, `register.html`, and `dashboard.html`.
+- [x] Vault statistics grid, storage usage tracker, and empty-state placeholders.
+- [x] 11 automated unit tests created and verified in `tests/unit/test_phase2.py`.
+
+---
+
+### ✅ Phase 3: Document Vault Management & Categorization
+- [x] `Document` model with user-isolated storage paths (`vault_files/user_<id>/<uuid>.<ext>`).
+- [x] Automatic SHA-256 cryptographic checksum calculation and MIME verification on save.
+- [x] Domain taxonomy: Medical Records, Education & Degrees, Vehicle & Asset, Personal & Identity, Professional, Other.
+- [x] `DocumentUploadForm` and `DocumentEditForm` with 25 MB size constraint and extension whitelisting.
+- [x] Safe in-browser decrypted preview for PDF documents and high-resolution images.
+- [x] Secure download streaming with sanitized `Content-Disposition` attachment headers.
+- [x] Robust IDOR security guards on view, preview, download, edit, and delete operations.
+- [x] Automatic physical disk sanitization on document deletion.
+- [x] Real-time dashboard integration showing actual document counts, storage used (MB), and recent vault records.
+- [x] 17 automated unit tests created and verified in `tests/unit/test_phase3.py`.
+
+---
+
+### ✅ Security & Vulnerability Defense Suite
+- [x] **IDOR Attack Prevention**: Complete test verification that Bob cannot view, download, edit, or delete Alice's documents (HTTP 404 enforcement).
+- [x] **Unauthenticated Access Redirection**: All protected routes (`/dashboard/`, `/documents/`, `/documents/upload/`, `/documents/<id>/`, `/documents/<id>/download/`, `/documents/<id>/edit/`, `/documents/<id>/delete/`) redirect to login.
+- [x] **Malicious File Upload Defense**: Instant rejection of executable scripts (`.exe, .bat, .sh, .py, .php, .html, .js`).
+- [x] **File Size Constraint Defense**: Client & form level enforcement rejecting payloads > 25 MB.
+- [x] **Path Traversal Sanitization**: Multi-level path traversal payloads (`../../../../etc/shadow.pdf`) sanitized to isolated UUID filenames in user partition.
+- [x] **Cryptographic Integrity Checksum**: SHA-256 binary validation on every saved file.
+- [x] **Session Destruction Verification**: POST logout destroys session cookies and revokes protected route access.
+- [x] 10 automated security tests created and verified in `tests/unit/test_security.py`.
+
+---
+
+### ✅ Phase 4: Controlled Share Pass Generation & Ephemeral QR Protocol
+- [x] `SharePass` model with many-to-many document relationships, UUID primary keys, and usage constraints.
+- [x] Ephemeral Share Key generation (cryptographically secure 8-character token `XXXX-XXXX`) and PBKDF2 hashing.
+- [x] Zero-knowledge key storage: Plaintext keys never stored on disk; verified via salted PBKDF2 hash.
+- [x] Configurable time-to-live (15m, 30m, 1h, 2h, 24h, 1-time view).
+- [x] Granular permission toggles: In-browser View enforced, Download toggleable.
+- [x] Dynamic high-contrast QR code generation via `qrcode` with base64 data URI and direct PNG attachment streaming.
+- [x] Interactive UI templates: `templates/sharing/create.html`, `detail.html`, and `list.html`.
+- [x] Immediate 1-click revocation mechanism from owner pass details and pass list.
+- [x] Dashboard integration: Live active passes metrics and recent active passes bento panel.
+- [x] 16 automated unit tests created and verified in `tests/unit/test_phase4.py`.
+
+---
+
+### ✅ Phase 5: Recipient Verification Portal & Two-Factor Access Flow
+- [x] Public recipient route `/p/<uuid:pass_id>/` requiring Share Key submission.
+- [x] Rate-limited key verification (5 attempts max before automatic lockout).
+- [x] Isolated in-browser viewer for authorized documents without account leakage.
+- [x] Server-enforced download gating (`can_download`).
+- [x] Expired / Revoked pass error states with clean security diagnostics.
+- [x] Session destruction on explicit departure (`/leave/`).
+- [x] 14 automated unit tests created and verified in `tests/unit/test_phase5.py`.
+
+
+---
+
+### ✅ Phase 6: Audit Trail, Immediate Revocation & Rate Limiting
+- [x] Structured immutable audit logging (`ShareAccessLog`) tracking timestamp, IP, user-agent, key attempt, event type, and outcome.
+- [x] Automated audit logging triggers across recipient key verification, preview streaming, downloads, session exits, and lockouts.
+- [x] Owner Security Audit Dashboard (`/audit/`) with metric counters, multi-attribute filter toolbar, keyword search, and pagination.
+- [x] Strict IDOR isolation ensuring users only see audit trails for passes they own.
+- [x] 1-click immediate pass revocation from owner dashboard & pass details.
+- [x] Rate limiting brute-force defense with structured lockout auditing.
+- [x] 13 automated unit tests created and verified in `tests/unit/test_phase6.py`.
+
+---
+
+### ✅ Phase 7: End-to-End Testing, Production Hardening & Audit Report
+- [x] Comprehensive End-to-End User & Recipient Lifecycle suite in `tests/selenium/test_e2e_user_journey.py`.
+- [x] Full simulation covering owner registration, document upload, SHA-256 verification, pass generation with PBKDF2 ephemeral key, adversary brute-force lockout, recipient verification, PDF preview stream, raw download, voluntary session exit, and owner 1-click revocation.
+- [x] Full-featured DOCX-ready Markdown Verification & Security Audit Report in `PHASE7_TEST_REPORT.md`.
+- [x] Zero-knowledge architecture and responsive UI audit verified across desktop, tablet, and mobile viewpoints.
+- [x] 93 automated tests created and passing with 100% success rate across all repository suites.
+
+---
+
+## 🛠️ Automated Verification Log
+
+```text
+Test Suite: test_phase1.py, test_phase2.py, test_phase3.py, test_security.py, test_phase4.py, test_phase5.py, test_phase6.py, test_e2e_user_journey.py
+Status: 93 Passed, 0 Failed, 0 Skipped
+Ran: 93 tests
+Result: OK (100% Passed)
+```

README.md

@@ -1,12 +1,36 @@
-# Passli — Cryptographic Document Vault & Ephemeral Sharing Platform
+<p align="center">
+  <img src=".github/assets/passli-repo-banner.png" alt="Passli — Cryptographic Document Vault & Ephemeral Sharing Platform" width="100%">
+</p>
+
+<p align="center">
+  <a href="https://github.com/alinawazcode/passli/actions/workflows/ci.yml"><img src="https://github.com/alinawazcode/passli/actions/workflows/ci.yml/badge.svg?branch=main" alt="CI"></a>
+  <a href="https://www.python.org/"><img src="https://img.shields.io/badge/python-3.11%20%7C%203.12-blue.svg" alt="Python Version"></a>
+  <a href="https://www.djangoproject.com/"><img src="https://img.shields.io/badge/django-5.1%2B-green.svg" alt="Django"></a>
+  <a href="SECURITY.md"><img src="https://img.shields.io/badge/encryption-AES--256--GCM%20AEAD-blueviolet.svg" alt="Encryption: AES-256-GCM AEAD"></a>
+  <a href="LICENSE"><img src="https://img.shields.io/badge/License-MIT-yellow.svg" alt="License: MIT"></a>
+</p>
+
+<p align="center">
+  <strong>Passli</strong> is an enterprise-grade, privacy-first personal records vault and ephemeral cryptographic sharing platform. Store sensitive documents with <strong>AES-256-GCM authenticated encryption at rest</strong> and share them with verified recipients via time-gated <strong>Share Passes</strong>—without exposing master cloud credentials, unencrypted email attachments, or cascading folder permissions.
+</p>
+
+<p align="center">
+  <a href="#-ephemeral-protocol-in-action">Interactive Demo</a> •
+  <a href="#-the-problem-passli-solves">The Problem</a> •
+  <a href="#-core-platform-capabilities">Capabilities</a> •
+  <a href="#-cryptographic-architecture-flow">Architecture</a> •
+  <a href="#-quick-start--installation">Quick Start</a> •
+  <a href="#-automated-testing--coverage">Testing</a> •
+  <a href="docs/DEPLOY_PYTHONANYWHERE.md">Deployment Guide</a>
+</p>
 
-[![CI](https://github.com/alinawazcode/passli/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/alinawazcode/passli/actions/workflows/ci.yml)
-[![Python Version](https://img.shields.io/badge/python-3.11%20%7C%203.12-blue.svg)](https://www.python.org/)
-[![Django](https://img.shields.io/badge/django-5.1%2B-green.svg)](https://www.djangoproject.com/)
-[![Encryption: AES-256-GCM](https://img.shields.io/badge/encryption-AES--256--GCM%20AEAD-blueviolet.svg)](SECURITY.md)
-[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+---
+
+## 🎬 Ephemeral Protocol in Action
 
-**Passli** is an enterprise-grade, privacy-first personal records vault and ephemeral cryptographic sharing platform. It enables individuals and organizations to securely store sensitive documents with **AES-256-GCM authenticated encryption at rest** and share them with verified recipients via time-gated **Share Passes**—without exposing master cloud credentials, unencrypted email attachments, or cascading folder permissions.
+<p align="center">
+  <img src=".github/assets/passli-ephemeral-workflow.gif" alt="Passli Ephemeral Share Pass Protocol in Action" width="100%">
+</p>
 
 ---
 
@@ -24,6 +48,11 @@ When sharing sensitive records with doctors, employers, financial institutions,
 ## ✨ Core Platform Capabilities
 
 ### 🗄️ 1. Personal Document Vault
+
+<p align="center">
+  <img src=".github/assets/passli-dashboard-preview.png" alt="Passli Personal Vault Dashboard & Document Manager UI" width="100%">
+</p>
+
 - **Domain Taxonomy**: Organize records into structured categories (`Medical`, `Education`, `Vehicle`, `Personal & Identity`, `Professional`, `Other`).
 - **Storage Migration CLI**: Includes `python manage.py encrypt_vault_storage` for seamless batch migration of legacy storage records.
 
@@ -78,6 +107,10 @@ When sharing sensitive records with doctors, employers, financial institutions,
 
 ## 🔐 Cryptographic Architecture Flow
 
+<p align="center">
+  <img src=".github/assets/passli-cryptographic-pipeline.png" alt="Passli Cryptographic Pipeline Architecture: AES-256-GCM AEAD Ingestion & In-Memory Streaming" width="100%">
+</p>
+
 ```mermaid
 flowchart TD
     subgraph Ingestion["Document Upload & Storage"]
@@ -169,8 +202,14 @@ passli/
 │   ├── driver_factory.py               # Persistent Chrome WebDriver session manager
 │   ├── test_config.py                  # Selectors, timeouts, and credentials configuration
 │   ├── tests/                          # 16 full-lifecycle tests + 3 controlled negative demos
-│   └── reports/                        # Standalone dark-mode HTML reports & screenshots
-├── .github/workflows/ci.yml   # Multi-stage CI pipeline (Ruff, pip-audit, Docker, Postgres, Coverage)
+├── .github/
+│   ├── assets/                # Visual branding, animated demo GIFs & architecture infographics
+│   └── workflows/ci.yml       # Multi-stage CI pipeline (Ruff, pip-audit, Docker, Postgres, Coverage)
+├── docs/                      # Architectural specifications, brand system, and deployment runbooks
+│   ├── ARCHITECTURE.md        # Cryptographic design, wire format, and in-memory streaming
+│   ├── BRANDING.md            # Visual identity catalog, design tokens, and color system
+│   ├── DEPLOY_PYTHONANYWHERE.md # Production deployment guide for PythonAnywhere
+│   └── DEPLOYMENT.md          # Multi-host deployment options (Docker, Render, Fly.io)
 ├── Dockerfile                 # Multi-stage production container image with unprivileged appuser
 └── manage.py                  # Django CLI management entry point
 ```

docs/ARCHITECTURE.md

@@ -18,6 +18,10 @@ Passli is a privacy-first, zero-credential-exposure personal document vault and
 
 ## 2. Document Vault Cryptographic Lifecycle
 
+<p align="center">
+  <img src="../.github/assets/passli-cryptographic-pipeline.png" alt="Passli Cryptographic Lifecycle Architecture" width="100%">
+</p>
+
 ### 2.1 File Ingestion & Storage Wire Format
 When a user uploads a document:
 1. **Plaintext Hashing**: Original plaintext bytes are read in-memory; a SHA-256 digest is calculated and stored in `Document.file_hash`.
@@ -54,6 +58,10 @@ Passli supports zero-downtime key rotation:
 
 ## 3. Ephemeral Share Pass Protocol
 
+<p align="center">
+  <img src="../.github/assets/passli-ephemeral-workflow.gif" alt="Passli Ephemeral Share Pass Protocol in Action" width="100%">
+</p>
+
 ### 3.1 Plaintext Key Isolation
 - Plaintext 8-character keys (`XXXX-XXXX`) use a 31-character unambiguous alphabet (`ABCDEFGHJKMNPQRSTUVWXYZ23456789`, omitting lookalikes `0`, `O`, `1`, `I`, `L`).
 - Plaintext keys are **never stored** in the database.