Skip to main content

Security Architecture

This document describes the security architecture and best practices for HMP.

Security Overview​

HMP implements multiple layers of security to protect sensitive hospitality data.

Authentication​

JWT-Based Authentication​

HMP uses JSON Web Tokens for API authentication:

// Token structure
{
  "sub": "user_123",
  "email": "user@hotel.com",
  "roles": ["front_desk", "cashier"],
  "property": "htl_001",
  "iat": 1708000000,
  "exp": 1708086400
}

Token Lifecycle​

  1. Login: User authenticates with credentials
  2. Token Issue: Server issues access token (24h) and refresh token (7d)
  3. API Calls: Client includes token in Authorization header
  4. Refresh: Client uses refresh token to get new access token
  5. Logout: Tokens are invalidated

Multi-Factor Authentication​

MFA is supported for sensitive operations:

  • Time-based OTP (TOTP)
  • SMS verification
  • Email verification

Authorization​

Role-Based Access Control (RBAC)​

Predefined roles with specific permissions:

RolePermissions
AdministratorFull system access
ManagerReports, settings, all operations
Front DeskReservations, check-in/out, billing
HousekeepingRoom status updates
CashierBilling and payments
AuditorRead-only access to reports

Permission Matrix​

permissions:
  reservations:
    create: [admin, manager, front_desk]
    read: [admin, manager, front_desk, auditor]
    update: [admin, manager, front_desk]
    delete: [admin, manager]

  billing:
    post_charge: [admin, manager, front_desk, cashier]
    void_charge: [admin, manager]
    refund: [admin, manager]

  reports:
    view: [admin, manager, auditor]
    export: [admin, manager]

Property-Level Isolation​

Users can only access data for their assigned properties:

// Middleware enforces property isolation
const propertyGuard = (req, res, next) => {
  const userProperties = req.user.properties;
  const requestedProperty = req.headers['x-property-id'];

  if (!userProperties.includes(requestedProperty)) {
    return res.status(403).json({ error: 'Access denied' });
  }
  next();
};

Data Protection​

Encryption at Rest​

All sensitive data is encrypted in the database:

-- Encrypted columns for PII
CREATE TABLE guests (
    id UUID PRIMARY KEY,
    first_name VARCHAR(100),
    last_name VARCHAR(100),
    id_number_encrypted BYTEA, -- AES-256 encrypted
    ...
);

Encryption in Transit​

  • All API communication over HTTPS/TLS 1.3
  • Internal service communication encrypted
  • Database connections use SSL

PII Handling​

Personal Identifiable Information is handled with care:

  • ID numbers are encrypted
  • Credit card data is tokenized (PCI DSS compliance)
  • Data masking in logs
  • Right to deletion support (GDPR)

API Security​

Rate Limiting​

Prevents abuse and DoS attacks:

rate_limits:
  default:
    requests: 100
    window: 60s

  auth:
    requests: 10
    window: 60s

  reports:
    requests: 20
    window: 60s

Input Validation​

All API inputs are validated:

const reservationSchema = z.object({
  arrival_date: z.string().datetime(),
  departure_date: z.string().datetime(),
  guest_id: z.string().uuid(),
  rooms: z.array(z.object({
    room_type_id: z.string().uuid(),
    adults: z.number().min(1).max(10),
  })).min(1)
});

SQL Injection Prevention​

  • Parameterized queries only
  • ORM with built-in protection
  • Input sanitization

XSS Prevention​

  • Content Security Policy headers
  • Output encoding
  • HttpOnly cookies

Audit Logging​

All security-relevant events are logged:

{
  "timestamp": "2026-01-22T10:30:00Z",
  "event": "user.login",
  "user_id": "user_123",
  "ip_address": "192.168.1.1",
  "user_agent": "Mozilla/5.0...",
  "property_id": "htl_001",
  "success": true
}

Logged Events​

  • Authentication attempts
  • Authorization failures
  • Data access
  • Configuration changes
  • Payment transactions

Infrastructure Security​

Network Security​

Container Security​

  • Minimal base images
  • No root privileges
  • Read-only file systems
  • Resource limits

Secrets Management​

# Kubernetes secrets
apiVersion: v1
kind: Secret
metadata:
  name: hmp-secrets
type: Opaque
data:
  database-url: <base64-encoded>
  jwt-secret: <base64-encoded>

Compliance​

PCI DSS​

  • Card data tokenization
  • Secure payment processing
  • Regular security assessments

GDPR​

  • Data minimization
  • Consent management
  • Right to access/delete
  • Data portability

SOC 2​

  • Access controls
  • Encryption
  • Monitoring
  • Incident response

Security Best Practices​

  1. Regular Updates - Keep all dependencies updated
  2. Penetration Testing - Annual third-party assessments
  3. Security Training - Staff awareness programs
  4. Incident Response - Documented procedures
  5. Backup & Recovery - Regular tested backups