Security & Environment Standards

Authentication Model

The app uses passwordless magic-link authentication — no passwords, no flask-login, no WTForms. A time-limited token is emailed; clicking it creates an authenticated session.

# app.py globals
magic_links    = {}   # {token: {'email': str, 'expires': datetime}}
active_sessions = {}  # {email: session_id} — one session per user enforced

MAGIC_LINK_EXPIRY_MINUTES = 15

def send_magic_link_email(email, magic_token, base_url) -> bool:
    # Send link via SMTP; falls back to stdout in dev (no SMTP config).
    ...

The @login_required decorator (defined in app.py) checks session['authenticated'] and active_sessions.

Environment Variables

# .env  (never commit — listed in .gitignore)

# Flask
FLASK_SECRET_KEY=<64-hex-chars>     # Required in production
FLASK_ENV=production                # Enables secure cookies

# Database
COSMOS_DB_CONNECTION_STRING=mongodb://...  # Full Cosmos DB connection string

# Email (SMTP)
SMTP_HOST=smtp.gmail.com
SMTP_PORT=587
SMTP_USER=your@gmail.com
SMTP_PASSWORD=app-specific-password
SMTP_FROM=your@gmail.com

# OCR (optional)
GOOGLE_VISION_API_KEY=...

# App limits
MAX_CONTENT_LENGTH=16777216   # 16 MB
UPLOAD_FOLDER=uploads

Session Security (actual app.py config)

app.config['SESSION_COOKIE_SECURE']   = os.getenv('FLASK_ENV') == 'production'
app.config['SESSION_COOKIE_HTTPONLY'] = True
app.config['SESSION_COOKIE_SAMESITE'] = 'Lax'
app.config['PERMANENT_SESSION_LIFETIME'] = 86400 * 7   # 7 days

File Upload Security

ALLOWED_EXTENSIONS = {'png', 'jpg', 'jpeg', 'gif', 'pdf', 'docx', 'txt', 'csv', 'epub'}

def allowed_file(filename):
    return '.' in filename and filename.rsplit('.', 1)[1].lower() in ALLOWED_EXTENSIONS

# Always use werkzeug's secure_filename
filename = secure_filename(file.filename)

Regex Safety

User input used in MongoDB $regex must be escaped:

import re
pattern = re.escape(user_input)   # prevents ReDoS
collection.find({'field': {'$regex': f'^{pattern}$'}})

Secrets Management

• Never hardcode secrets in source files
• Use Azure Key Vault references for production environment variables
• FLASK_SECRET_KEY must be set explicitly in production; app raises ValueError otherwise
• users.json (authorised email list) is gitignored in production deployments

Production Checklist

• FLASK_ENV=production (enables secure cookies)
• FLASK_SECRET_KEY set to 64+ hex chars
• SMTP credentials configured (magic-link delivery)
• Cosmos DB connection string from Key Vault
• users.json authorised users list deployed
• HTTPS enforced at load balancer / Azure Container App ingress

Source Files

• app.py — auth routes, login_required decorator, send_magic_link_email()
• config/users.json — authorised user email list
• deploy-chuuk.sh — production Azure deployment script