azionelab/docs/security-notes.md

Security Notes

This document records security assumptions and controls for AzioneLab's initial architecture.

Assumptions

• The public website is readable by anonymous visitors.
• Booking endpoints are public but must validate input strictly.
• Administration and check-in functions require authenticated staff users.
• HTTPS is expected in production.
• PostgreSQL is reachable only from trusted application containers.
• Email is sent through a configured SMTP provider or relay.

Personal Data

Reservations contain personal data such as name, email address, optional phone number, and optional notes.

Controls:

• collect only data required to manage the reservation;
• do not expose reservation personal data through public APIs;
• do not include personal data in QR codes;
• avoid logging request bodies from booking and confirmation endpoints;
• avoid logging raw tokens;
• restrict admin access to staff users who need it.

Token Handling

Reservation tokens are used for email confirmation and QR verification.

Rules:

• generate tokens with a cryptographically secure random generator;
• make tokens opaque and non-guessable;
• do not encode personal data in tokens;
• store token hashes when practical;
• treat raw tokens as secrets;
• mark one-time confirmation tokens as used after successful confirmation;
• expire confirmation tokens after a reasonable period;
• keep QR tokens valid only for the intended performance and check-in period where practical.

QR Codes

QR codes must contain only:

• an opaque verification token; or
• a verification URL containing an opaque token.

QR codes must not contain:

• name;
• email;
• phone;
• notes;
• reservation metadata that identifies the visitor.

The check-in endpoint resolves the token server-side and returns only the minimum information staff need.

Authentication and Authorization

Required controls:

• Django admin requires authenticated staff accounts;
• check-in verification requires authenticated staff or an authenticated scanning client;
• staff permissions should separate content management from operational check-in when practical;
• public APIs must not allow clients to set protected fields such as reservation status, token values, or check-in state.

Input Validation

Public booking endpoints must validate:

• required fields;
• email format;
• maximum field lengths;
• positive party size;
• booking status for the selected performance;
• capacity availability;
• unexpected fields.

Validation must happen server-side even when the frontend also validates input.

Anti-Overbooking

The backend must enforce capacity server-side.

Capacity calculation:

available seats =
  room capacity
  + additional seats
  - manually occupied seats
  - confirmed reservations

Controls:

• use database transactions for confirmation;
• lock the performance row or use an equivalent consistency control;
• recalculate availability inside the transaction;
• confirm the reservation only when enough seats remain;
• ensure duplicate confirmation requests are idempotent or rejected safely;
• do not rely on frontend availability values.

Secrets

Secrets must not be committed to the repository.

Expected secret configuration:

• Django SECRET_KEY;
• database password;
• SMTP credentials;
• TLS private keys or certificate automation credentials, if used.

Use environment variables, Docker secrets, or deployment-managed secret injection. Documentation and example configuration should use placeholders only.

Deployment Security

Deployment should follow least privilege:

• expose only nginx publicly;
• keep backend and database on an internal Docker network;
• avoid privileged containers;
• use explicit image tags rather than latest;
• persist PostgreSQL data in a named volume;
• configure TLS for production;
• serve static and media files without exposing private files.

Logging

Logs should help diagnose operational issues without exposing sensitive data.

Do not log:

• raw confirmation tokens;
• raw QR tokens;
• full booking payloads;
• passwords;
• session cookies;
• authorization headers;
• SMTP credentials.

Residual Risks

Initial residual risks:

• synchronous email can make booking responses depend on SMTP availability;
• QR codes can be copied, so duplicate check-in prevention must be reliable;
• staff account compromise would expose admin and check-in functionality;
• retention and deletion rules for personal data still need a project policy.