nx9-url-shortener/docs/SECURITY.md

BZOD Security Guide

Version: v0.8.0

---

Security Overview

BZOD is designed as a self-hosted URL shortener and landing page platform with a strong emphasis on:

• Multi-user isolation
• Secure authentication
• Role-based access control
• Auditability
• Data ownership
• Disaster recovery
• Operational simplicity

This document describes the security architecture, threat model, authentication mechanisms, authorization controls, and operational security recommendations for BZOD v0.8.0.

---

Security Principles

BZOD follows several core principles:

1. Least Privilege
2. Tenant Isolation
3. Defense in Depth
4. Auditability
5. Secure Defaults
6. Explicit Ownership
7. Fail Secure

---

Threat Model

BZOD is designed to protect against:

• Unauthorized dashboard access
• Credential theft
• Session hijacking
• Cross-user data access
• Slug takeover attempts
• Privilege escalation
• CSRF attacks
• XSS injection attempts
• Unauthorized API access
• Malicious content modification
• Accidental administrative mistakes

BZOD is not intended to defend against:

• Physical server compromise
• Root-level operating system compromise
• Malware running as the BZOD service user
• Full database theft by a privileged host administrator

---

Authentication

Authentication is centralized in:

users.db

Tables:

users
sessions
api_tokens

All users authenticate through the same identity system.

---

Password Security

Passwords are never stored in plaintext.

Stored values:

password_hash

Passwords are hashed before storage.

Administrative password resets generate entirely new hashes.

Existing passwords cannot be recovered.

---

Session Security

All dashboard authentication uses:

bzod_session

cookie.

Sessions are stored in:

users.db.sessions

Each session contains:

session_id
user_id
created_at
expires_at

---

Session Validation

Each authenticated request verifies:

1. Session exists
2. Session has not expired
3. User exists
4. User status is active
5. User has required permissions

Failure at any step immediately invalidates access.

---

Session Revocation

Sessions are revoked when:

• User logs out
• User is disabled
• User is deleted
• Password is reset
• Administrator revokes sessions

---

Session Fixation Protection

BZOD generates new session identifiers after successful authentication.

Previously issued identifiers are not reused.

---

Authorization Model

BZOD implements Role-Based Access Control (RBAC).

Supported roles:

admin
standard
system

---

Administrator

Administrators can:

• Manage users
• Reset passwords
• Transfer ownership
• Manage quotas
• Access audit logs
• Review analytics
• Create backups
• Restore backups
• Moderate content

Administrators cannot bypass audit logging.

---

Standard User

Standard users can:

• Manage owned URLs
• Manage owned landing pages
• View owned analytics
• Generate API tokens
• Manage owned content

Standard users cannot:

• Access other users' content
• Access administrative endpoints
• Access system settings

---

System Accounts

System accounts are internal accounts.

They cannot authenticate into:

• Dashboard
• REST API

---

Multi-User Isolation

Multi-user isolation is one of the primary security features of BZOD.

Each tenant receives independent databases.

Example:

users/
├── 2/
│   ├── content.db
│   └── analytics.db
│
├── 3/
│   ├── content.db
│   └── analytics.db

User 2 never accesses:

users/3/content.db
users/3/analytics.db

User 3 never accesses:

users/2/content.db
users/2/analytics.db

---

Global Slug Security

All public slugs are stored in:

system.db.global_slugs

Each slug is globally unique.

Example:

/company

may belong to only one owner.

Duplicate registrations are rejected.

---

Slug Ownership

Every slug contains:

owner_user_id
target_id
target_type
status

Ownership must match before modification is permitted.

---

Slug Transfer Protection

Only administrators may transfer ownership.

Transfer operations:

1. Validate destination quotas
2. Validate destination user
3. Copy content
4. Update ownership
5. Record history
6. Write audit event

---

API Security

REST API authentication uses API tokens.

Tokens are stored as hashes.

Plaintext tokens are shown only once during creation.

---

API Token Security

Stored values:

token_hash

Never:

plaintext_token

If a token is lost:

1. Revoke it
2. Generate a new token

---

API Permissions

Admin tokens:

Full administrative access

Standard user tokens:

Owned resources only

System accounts:

API access denied

---

CSRF Protection

All dashboard forms require valid CSRF tokens.

Protected actions include:

• Login
• User creation
• Password reset
• Content modification
• Moderation actions
• Quota updates
• Backup operations

---

Invalid CSRF Requests

Invalid requests return:

403 Forbidden

and are rejected before processing.

---

XSS Protection

User-supplied content is validated before rendering.

Templates use:

Askama

which escapes output by default.

Recommended:

• Do not allow arbitrary JavaScript
• Validate HTML content
• Restrict trusted editors

---

Content Moderation

Administrators may:

• Flag content
• Disable content
• Delete content

Disabled content returns:

410 Gone

for:

/{slug}
/p/{slug}
/api/qr/{slug}.png
/api/qr/{slug}.svg

---

Redirect Security

The redirect handler validates destination URLs before constructing HTTP Location headers.

Protections include:

• URL scheme validation (only http and https destinations are permitted)
• Control character rejection
• CRLF injection prevention
• Safe Location header construction (no panics on malformed values)

Invalid redirect destinations return:

500 Internal Server Error

with structured server-side logging. Full destination values are not exposed to clients.

---

Audit Logging

Security-sensitive actions are logged.

Examples:

login
logout
failed_login
user_created
user_deleted
password_reset
slug_transfer
quota_update
backup_created
restore_executed

Stored in:

system.db

Audit logs should be reviewed regularly.

---

Backup Security

Backups may contain:

• User records
• Session records
• URLs
• Pages
• Analytics
• API token hashes

Backups should be treated as sensitive data.

---

Recommendations

Store backups:

• Offsite
• Encrypted
• Access-controlled

Never expose backup archives publicly.

---

Database Security

SQLite databases should be accessible only to the BZOD service account.

Recommended permissions:

chmod 700 data
chmod 600 *.db

---

HTTPS Requirements

Production deployments should always use HTTPS.

Recommended reverse proxies:

• Nginx
• Caddy
• Traefik

Never expose login pages over plaintext HTTP.

---

Security Headers

Recommended reverse proxy headers:

X-Frame-Options: DENY
X-Content-Type-Options: nosniff
Referrer-Policy: strict-origin-when-cross-origin
Content-Security-Policy: default-src 'self'

---

Password Policy Recommendations

Recommended minimum:

12 characters

Encourage:

• Password managers
• Unique passwords
• Randomly generated credentials

Avoid:

• Reused passwords
• Dictionary words
• Predictable patterns

---

Brute Force Protection

Recommended deployment protections:

• Reverse proxy rate limiting
• Fail2Ban
• Firewall rules

Example:

5 login attempts
within 5 minutes

before temporary blocking.

---

Administrative Security Checklist

Before production deployment:

• Enable HTTPS
• Configure backups
• Review file permissions
• Remove default credentials
• Verify audit logging
• Test restore procedures
• Review active sessions

---

Incident Response

If compromise is suspected:

1. Disable affected accounts.
2. Revoke active sessions.
3. Revoke API tokens.
4. Create forensic backup.
5. Review audit logs.
6. Restore from trusted backups if necessary.
7. Rotate credentials.

---

Security Testing

BZOD v0.8.0 includes tests covering:

• Authentication
• Authorization
• Session validation
• CSRF enforcement
• Slug ownership
• User isolation
• Upgrade migrations
• Backup integrity
• Disaster recovery
• Redirect destination validation
• HTTP Location header safety

These tests are executed during CI and release validation.

---

Responsible Disclosure

If a security vulnerability is discovered:

1. Do not publish exploit details immediately.
2. Report the issue privately.
3. Allow time for remediation.
4. Coordinate disclosure after a fix is available.

---

Known Limitations

Current limitations include:

• No MFA support
• No SSO integration
• No hardware security key support
• No built-in rate limiter
• No WebAuthn support

These may be addressed in future releases.

---

Summary

BZOD v0.8.0 provides:

• Centralized authentication
• Secure session management
• RBAC authorization
• Multi-user isolation
• Global slug ownership controls
• CSRF protection
• API token hashing
• Audit logging
• Backup security
• Operational security guidance

while maintaining a lightweight, SQLite-native, self-hosted architecture.

---

End of Document.