Security Architecture and Compliance in Stay Sidekick

Stay Sidekick applies multiple independent security layers so that a weakness in one does not compromise the entire system. Authentication, request integrity, password storage, rate limiting, transport, encrypted storage, and GDPR compliance are all addressed at separate implementation points across the stack. This page documents each layer with its implementation location so you know exactly where to look when auditing or extending the platform.

Security controls at a glance

Layer	Mechanism	Implementation
Authentication	JWT HS256, configurable TTL	`app/auth/routes.py`, `app/security/jwt.py`
Request integrity	CSRF Double-Submit Cookie	`app/security/csrf.py`
Password storage	BCrypt with random salt	`app/auth/passwords.py`
Rate limiting	Flask-Limiter, per-IP	`app/extensions.py`, individual blueprints
Cross-origin access	CORS allow-list	App factory
Credential storage	Fernet symmetric encryption	`app/common/crypto.py`
Guest data	In-memory only, never persisted	All operational modules
Public forms	Cloudflare Turnstile + honeypot	`app/contact/`, `app/security/`
Security headers	Nginx (HSTS, CSP, X-Frame-Options…)	`nginx/nginx.conf`

Authentication — JWT HS256

Every protected endpoint in the platform requires a valid JSON Web Token signed with HMAC-SHA256.

Obtain a token

POST /api/auth/login with valid credentials. The server verifies the password with BCrypt, then issues a signed JWT.

curl -X POST http://localhost/api/auth/login \
  -H "Content-Type: application/json" \
  -H "X-CSRF-Token: <csrf_token>" \
  -d '{
    "email": "julia@coastalstays.com",
    "password": "MyNewSecure#99"
  }'

Response 200:

{
  "ok": true,
  "token": "<jwt>",
  "debe_cambiar_password": false
}

Send the token with every request

Pass the token in the Authorization header on all protected endpoints:

curl http://localhost/api/perfil \
  -H "Authorization: Bearer $TOKEN"

Token expiry

The TTL is controlled by the JWT_ACCESS_TOKEN_HOURS environment variable (default: 1 hour). After expiry, the client must re-authenticate. There is no refresh token — the login flow is the only way to obtain a new token.

The debe_cambiar_password: true field in the login response signals that an admin has reset this user’s password and they are using a system-generated temporary credential. The frontend should route the user to the password change screen immediately after login when this flag is true.

Nginx auth_request subrequest

GET /api/auth/validacion is used internally by Nginx as an auth_request subrequest. It returns 200 if the JWT is valid and the iat claim is not in the future (with a 5-second tolerance for clock drift between containers). It returns 401 for any invalid or missing token. This endpoint is not intended to be called directly from client code.

All state-changing requests (POST, PUT, PATCH, DELETE) must carry a valid CSRF token. Stay Sidekick uses the Double-Submit Cookie pattern — a stateless approach that requires no server-side session storage.

Fetch a CSRF token

Call GET /api/csrf-token before making any write request. The backend generates a 256-bit cryptographically random token, sets it as a csrf_token cookie (SameSite=Strict, HttpOnly=false, max_age=3600), and returns it in the JSON body.

curl -c cookies.txt http://localhost/api/csrf-token

{ "csrf_token": "yK3r...NpQx" }

Echo the token in the header

Read the token value from the cookie and include it in the X-CSRF-Token header on every write request:

curl -X POST http://localhost/api/empresas \
  -b cookies.txt \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-CSRF-Token: yK3r...NpQx" \
  -H "Content-Type: application/json" \
  -d '{"nombre": "...", "email": "..."}'

Server validation

The @csrf_protect decorator in app/security/csrf.py compares the csrf_token cookie value with the X-CSRF-Token header using secrets.compare_digest (constant-time comparison). If either is absent or they do not match, the request is rejected with 403.

The cookie is set with SameSite=Strict so that cross-site requests cannot attach it automatically. HttpOnly=false is intentional — JavaScript must be able to read the cookie value to populate the request header. An attacker on a different origin is blocked by SameSite and CORS combined, not by cookie inaccessibility.

Password hashing — BCrypt

All passwords stored in the database (company admin passwords and individual user passwords) are hashed with BCrypt.

BCrypt automatically generates a random salt on every call to hash_password, so two identical passwords produce different hash strings — this is correct and expected behavior.
Verification (verify_password) calls bcrypt.checkpw, which is a constant-time comparison implementation that prevents timing side-channel attacks.
The cost factor is configurable and baked into the hash string, meaning future rounds can be increased without invalidating existing hashes.

# app/auth/passwords.py
hash_str = hash_password("MyNewSecure#99")   # → store in DB
ok       = verify_password("MyNewSecure#99", hash_str)  # → verify at login

Never compare password hashes with == or any string equality operator. Always go through verify_password to benefit from the constant-time comparison and prevent timing attacks.

Rate limiting

Stay Sidekick uses Flask-Limiter to enforce per-IP request limits on all sensitive or potentially abused endpoints.

Endpoint	Limit	Notes
`POST /api/auth/login`	10 / hour	Mitigates brute-force password attacks
Contact form	5 / hour (configurable via `RATE_LIMIT_CONTACT`)	Configurable via environment variable
Smoobu sync	10 / hour	Prevents runaway PMS polling
XLSX import	20–30 / hour	Varies by operation type

When a limit is exceeded the server returns 429 Too Many Requests. The client should back off and retry after the reset window.

CORS

The platform restricts cross-origin requests to an explicit allow-list defined by the ALLOWED_ORIGINS environment variable. Only origins on that list may include credentials in cross-origin requests. Any request from an unlisted origin will be rejected at the CORS preflight stage — the protected API endpoint is never reached. This means that even if an attacker can trick a victim’s browser into making a request, the response will not be readable unless the origin matches.

Encrypted storage

PMS API keys (Smoobu) and AI provider API keys are stored in the database encrypted, never in plaintext. Encryption and decryption are handled by app/common/crypto.py using Fernet symmetric encryption from the cryptography library.

The Fernet key is loaded from the FERNET_KEY environment variable at runtime.
encrypt(plaintext) returns a URL-safe base64-encoded token that is safe to store in a TEXT column.
decrypt(token) returns None if the token is invalid or was encrypted with a different key — preventing silent data corruption.
The decrypted key material is never serialized into any API response. Integration endpoints only report a connected/disconnected boolean status.

# Generate a new Fernet key (run once, store in environment)
python -c "from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())"

If FERNET_KEY is rotated after API keys have been stored, all existing encrypted values will fail to decrypt (decrypt() returns None). Plan key rotations carefully — decrypt and re-encrypt all stored keys before swapping the environment variable in production.

Stay Sidekick processes guest reservation data in several operational modules (heat map, late check-in notifications, Google Contacts sync). In every case, this data is handled in memory only and is never written to the database.

Heat map

Reservation date ranges from the PMS or XLSX are aggregated in memory to produce daily load counts. No individual reservation record is persisted.

Late check-in

Today’s arrivals are fetched from the PMS or loaded from an uploaded XLSX, filtered in memory against the cutoff hour, and discarded after the response is sent.

Google Contacts sync

Guest names and phone numbers are processed in memory to build the contact upsert payload. They are not stored in Stay Sidekick’s database.

This architecture means Stay Sidekick holds no guest personal data at rest. The platform is GDPR-compliant by design for these data flows — there is no guest data to report, export, or delete in response to a data subject request.

Anti-spam for public forms

The public contact form and company signup form are protected by three independent anti-spam layers applied in sequence:

Cloudflare Turnstile

A Turnstile challenge token is required in every form submission. The backend verifies the token against Cloudflare’s API using TURNSTILE_SECRET_KEY before processing the request. Bot traffic that cannot solve the challenge is rejected immediately.

Honeypot field

A hidden form field (invisible to real users, visible to scrapers and bots) is included in the form schema. Any submission where the honeypot field is populated is silently rejected.

Rate limit by IP

The contact endpoint enforces a rate limit (default: 5 requests / hour per IP, configurable via RATE_LIMIT_CONTACT). Distributed abuse is further constrained by Cloudflare’s edge network.

Nginx security headers

All HTTP responses — regardless of which upstream service generated them — pass through Nginx, which injects the following security headers:

Header	Value / Policy
`Strict-Transport-Security`	`max-age=31536000; includeSubDomains`
`Content-Security-Policy`	Strict per-resource policy defined in `nginx.conf`
`X-Frame-Options`	`SAMEORIGIN`
`X-Content-Type-Options`	`nosniff`
`Referrer-Policy`	`strict-origin-when-cross-origin`

In production, TLS is terminated at the Railway edge — not inside the Nginx container. The Nginx configuration (nginx.railway.conf) therefore listens only on port 80. HSTS and the other headers are still applied by Nginx to all responses; the HTTPS guarantee is enforced by Railway’s edge layer upstream of the container.

Defense-in-depth summary

Each security control is independent. An attacker who bypasses one layer still faces the remaining layers:

No token → JWT middleware rejects the request before it reaches any handler.
Stolen token, different origin → CORS blocks the browser from reading the response.
Valid token, no CSRF cookie → @csrf_protect rejects the write request with 403.
Brute-force login → Rate limiter blocks after 10 attempts per hour per IP.
Compromised database → BCrypt hashes are not reversible without the cost of a full brute-force; Fernet ciphertext is unreadable without FERNET_KEY.
Guest data request → No guest personal data exists at rest to expose.

Get Started

Core Features

Administration

Deployment

Development

Security Architecture and Compliance in Stay Sidekick

Security controls at a glance

Authentication — JWT HS256

Nginx auth_request subrequest

Password hashing — BCrypt

Rate limiting

CORS

Encrypted storage

Heat map

Late check-in

Google Contacts sync

Anti-spam for public forms

Nginx security headers

Defense-in-depth summary

Build docs developers (and LLMs) love

Get Started

Core Features

Administration

Deployment

Development

Documentation Index

​Security controls at a glance

​Authentication — JWT HS256

​Nginx auth_request subrequest

​CSRF — Double-Submit Cookie

​Password hashing — BCrypt

​Rate limiting

​CORS

​Encrypted storage

​GDPR data handling

Heat map

Late check-in

Google Contacts sync

​Anti-spam for public forms

​Nginx security headers

​Defense-in-depth summary

Build docs developers (and LLMs) love

Security controls at a glance

Authentication — JWT HS256

Nginx auth_request subrequest

CSRF — Double-Submit Cookie

Password hashing — BCrypt

Rate limiting

CORS

Encrypted storage

GDPR data handling

Anti-spam for public forms

Nginx security headers

Defense-in-depth summary