• Stored bcrypt-hashed (bcrypt)
• Used when authenticator unavailable
• Marked as used after redemption

3. Authorization (RBAC)

Roles

Permission Matrix

Implementation3.2 Organization Scoping (Middleware)IDOR Prevention)

import { Request, Response, NextFunction } from 'express'

function requireRole(roles: string[]) {
  return (req: Request, res: Response, next: NextFunction) => {
    if (!roles.includes(req.user.role)) {
      return res.status(403).json({ error: 'Forbidden' })
    }
    next()
  }
}

// Usage
app.post('/api/v1/invoices', requireRole(['owner', 'admin']), createInvoice)

Data Classification

L4 Restricted fields use a hybrid encryption approach per ADR-014: personal identifiers (JMBG, OIB) receive AES-256-GCM field-level encryption before persistence because they are irrevocable and high-impact on breach. Business tax IDs (PIB, JIB) and IBAN rely on disk-level encryption plus application-layer controls — field-level encryption for publicly available identifiers would be disproportionate to the risk per GDPR Article 32.

Encryption

In Transit: TLS 1.3

All traffic encrypted via HTTPS:

• Frontend (Vercel): Automatic HTTPS
• Backend (Railway): Automatic HTTPS
• Certificate: Let's Encrypt (auto-renewed)

TLS Configuration:

• Minimum version: TLS 1.3
• Cipher suites: Modern only (no legacy ciphers)
• HSTS enabled (Strict-Transport-Security header)

At Rest: Database Encryption

PostgreSQL (Railway):

• Disk encryption: AES-256 (Railway default)
• Backup encryption: AES-256
• Column-level encryption: Hybrid approach per ADR-014 — JMBG and OIB fields use AES-256-GCM field-level encryption via prisma-field-encryption (Tier 1). PIB, JIB, and IBAN rely on disk-level encryption + application controls (Tier 2). Disk-level encryption alone is insufficient for personal identifiers (JMBG/OIB) due to their irrevocability and high breach impact. (See ADR-014)

Cloudflare R2 (Files):

• Server-side encryption: AES-256 (default)
• No client-side encryption needed (files are receipts/invoices, not PII)

Secrets Management

NEVER commit secrets to git:

• .env files in .gitignore
• Use platform-provided secrets (Vercel, Railway)
• Rotate JWT secrets quarterly
• Rotate API keys annually

OWASP Top 10 Mitigations

1. Injection (SQL Injection)

Mitigation: Prisma ORM parameterized queries

// SAFEInjected —by Prismaauth auto-escapes
await prisma.invoice.findMany({
  where: { customerId: req.params.id },
})

// UNSAFE — Never use raw SQL for user input
await prisma.$queryRaw`SELECT * FROM invoices WHERE customer_id = ${req.params.id}`

2. Broken Authentication

Mitigations:

• bcrypt password hashing (12 rounds)
• JWT with short expiry (15 min)
• Refresh token rotation
• 2FA (TOTP)
• Rate limitingmiddleware on authall endpoints/api/v1/* (5 req/min)

3. Sensitive Data Exposure

Mitigations:

• TLS 1.3 in transit
• AES-256 at rest
• No PII in JWTs (only user ID)
• No passwords in logs
• No sensitive data in URLs (use POST body)

4. XML External Entities (XXE)

Not applicable — Bilko does not parse XML.

5. Broken Access Control

Mitigations:

• RBAC enforced on every endpoint
• Organization-scoped queries (middleware)
• No direct object reference (use UUIDs, not auto-increment IDs)

// Organization scoping middlewareroutes
app.use('/api/v1/*', (req, res, next) => {
  req.prismaWhere = { organizationId: req.user.organizationId };
  next();
});

// ApplyApplied to queriesevery Prisma query
await prisma.invoice.findMany({ where: { ...req.prismaWhere } });

UUID primary keys throughout — no sequential ID enumeration possible.

4. Encryption

6.4.1 SecurityIn MisconfigurationTransit: TLS 1.3

Mitigations:

• Helmet.js security headers
• CORS whitelist (no * in production)
• Error messages sanitized (no stack traces in production)
• Disable X-Powered-By header

Full Security Headers Configuration

All securitytraffic headersHTTPS. appliedCloudflare viaTLS Helmet.js1.3 onat theedge, Expressre-encrypted API.to TheRailway. Next.js frontend applies equivalent headers viaHSTS: next.config.jsmax-age=63072000; includeSubDomains; preload.

import
4.2 helmetAt fromRest: 'helmet'

// Express API — full security headers
app.use(
  helmet({
    // Content-Security-Policy — prevent XSS
    contentSecurityPolicy: {
      directives: {
        defaultSrc: ["'self'"],
        scriptSrc: ["'self'"], // No unsafe-inline needed on API
        styleSrc: ["'self'"],
        imgSrc: ["'self'", 'data:'],
        connectSrc: ["'self'"],
        frameSrc: ["'none'"], // No iframes from this API
        objectSrc: ["'none'"],
        upgradeInsecureRequests: [],
      },
      useDefaults: false,
    },
    // Strict-Transport-Security — force HTTPS for 1 year, include subdomains
    hsts: {
      maxAge: 31536000, // 1 year in seconds
      includeSubDomains: true,
      preload: true, // Eligible for browser HSTS preload list
    },
    // X-Frame-Options — prevent clickjacking
    frameguard: {
      action: 'deny', // DENY: no framing at all
    },
    // X-Content-Type-Options — prevent MIME sniffing
    noSniff: true,
    // X-XSS-Protection — legacy header for older browsers
    xssFilter: true,
    // Referrer-Policy — don't leak URL in Referer header
    referrerPolicy: {
      policy: 'strict-origin-when-cross-origin',
    },
    // Permissions-Policy — disable browser features not needed by Bilko
    permittedCrossDomainPolicies: { permittedPolicies: 'none' },
    // X-DNS-Prefetch-Control
    dnsPrefetchControl: { allow: false },
    // X-Powered-By removed by default in Helmet
    hidePoweredBy: true,
  }),
)

// Permissions-Policy header (not yet in Helmet — set manually)
app.use((req, res, next) => {
  res.setHeader(
    'Permissions-Policy',
    'camera=(), microphone=(), geolocation=(), payment=(), usb=()',
  )
  next()
})

// CORS — whitelist only known origins
app.use(
  cors({
    origin: (origin, callback) => {
      const allowed = [
        'https://bilko.io',
        'https://www.bilko.io',
        'https://app.bilko.io',
        'https://staging.bilko.io',
        'https://bilko.rs', // Serbia redirect domain
      ]
      if (!origin || allowed.includes(origin)) {
        callback(null, true)
      } else {
        callback(new Error(`CORS: origin ${origin} not allowed`))
      }
    },
    credentials: true, // Required for httpOnly cookie (refresh token)
    methods: ['GET', 'POST', 'PUT', 'PATCH', 'DELETE', 'OPTIONS'],
    allowedHeaders: ['Content-Type', 'Authorization'],
  }),
)

Next.js Frontend Security Headers (next.config.js)

// next.config.js
const securityHeaders = [
  {
    key: 'Content-Security-Policy',
    value: [
      "default-src 'self'",
      "script-src 'self' 'unsafe-inline' 'unsafe-eval'", // Next.js requires these
      "style-src 'self' 'unsafe-inline'", // Tailwind requires unsafe-inline
      "img-src 'self' data: https:",
      "connect-src 'self' https://api.bilko.io wss://api.bilko.io",
      "font-src 'self' https://fonts.gstatic.com",
      "frame-ancestors 'none'",
      'upgrade-insecure-requests',
    ].join('; '),
  },
  { key: 'Strict-Transport-Security', value: 'max-age=31536000; includeSubDomains; preload' },
  { key: 'X-Frame-Options', value: 'DENY' },
  { key: 'X-Content-Type-Options', value: 'nosniff' },
  { key: 'Referrer-Policy', value: 'strict-origin-when-cross-origin' },
  { key: 'Permissions-Policy', value: 'camera=(), microphone=(), geolocation=(), payment=()' },
  { key: 'X-DNS-Prefetch-Control', value: 'off' },
]

module.exports = {
  headers: async () => [{ source: '/:path*', headers: securityHeaders }],
}

Headers Verification

Use securityheaders.com to verify. Target grade: A+.

4.3 Password Security

bcrypt, 12 salt rounds. Min 8 chars. Block top 10K common passwords. Last 5 hashes retained.

4.4 Financial Data Precision

All monetary amounts: NUMERIC(19,4) — never float. Exchange rates locked at transaction date.

5. OWASP Top 10 Mitigations

7.

6. Cross-Site Scripting (XSS)

Mitigations:

• React auto-escapes output (default safe)
• CSP headers (Content-Security-Policy)
• Sanitize user input (Zod validation)
• No dangerouslySetInnerHTML without sanitization

// SAFE — React escapes by default
<p>{invoice.description}</p>

// UNSAFE — Only use with sanitized HTML
<div dangerouslySetInnerHTML={{ __html: sanitizedHTML }} />

8. Insecure Deserialization

Not applicable — Bilko does not deserialize untrusted data.

9. Using Components with Known Vulnerabilities

Mitigations:

• Dependabot alerts enabled (GitHub)
• Weekly npm audit checks
• Automated security updates (Dependabot PRs)
• Lock file committed (package-lock.json)

10. Insufficient Logging & Monitoring

Mitigations:

• Audit trail (LoggedAction table)
• Error tracking (Sentry recommended)
• Access logs (Railway built-in)
• Failed login attempts logged
• Anomaly detection (future: alert on 10+ failed logins)

Rate Limiting

Prevent brute force and abuse:

Implementation

7. Input Validation (Zod)

import rateLimit from 'express-rate-limit'
import RedisStore from 'rate-limit-redis'

// Auth limiter — strict (applied to /auth/login and /auth/register)
const authLimiter = rateLimit({
  windowMs: 60 * 1000, // 1 minute
  max: 5,
  skipSuccessfulRequests: true, // Don't count successful logins
  standardHeaders: true,
  legacyHeaders: false,
  message: {
    error: 'Too many authentication attempts',
    code: 'RATE_LIMIT_EXCEEDED',
    retryAfter: 60,
  },
  keyGenerator: (req) => req.ip || 'unknown',
})

// General API limiter (applied to all /api/v1/* routes)
const generalLimiter = rateLimit({
  windowMs: 60 * 1000, // 1 minute
  max: 100,
  standardHeaders: true,
  legacyHeaders: false,
  handler: (_req, res) =>
    res.status(429).json({
      error: 'Too many requests',
      code: 'RATE_LIMIT_EXCEEDED',
      retryAfter: 60,
    }),
})

app.post('/api/v1/auth/login', authLimiter, loginHandler)
app.use('/api/v1/', generalLimiter)

IP Whitelisting for Webhooks

Webhooks from SEF (Serbian e-invoice portal) and FINA (Croatian HR-FISK) must bypass general rate limiting but are restricted to known IP ranges:

// Known webhook source IP ranges
const SEF_WEBHOOK_IPS = [
  '185.54.144.0/24', // efaktura.mfin.gov.rs — verify with SEF portal docs
]

const FINA_WEBHOOK_IPS = [
  '195.29.61.0/24', // FINA PKI infrastructure — verify with FINA
]

function isWebhookRequest(req: Request): boolean {
  const clientIp = req.ip ?? req.socket.remoteAddress
  return [...SEF_WEBHOOK_IPS, ...FINA_WEBHOOK_IPS].some((range) => ipRangeContains(range, clientIp))
}

// Webhook endpoint — IP-restricted, no general rate limit
app.post(
  '/api/v1/webhooks/sef',
  requireWebhookIp(SEF_WEBHOOK_IPS),
  verifyWebhookSignature,
  handleSefWebhook,
)

app.post(
  '/api/v1/webhooks/fina',
  requireWebhookIp(FINA_WEBHOOK_IPS),
  verifyWebhookSignature,
  handleFinaWebhook,
)

function requireWebhookIp(allowedRanges: string[]) {
  return (req: Request, res: Response, next: NextFunction) => {
    const clientIp = req.ip ?? req.socket.remoteAddress
    const allowed = allowedRanges.some((range) => ipRangeContains(range, clientIp))
    if (!allowed) {
      return res.status(403).json({ error: 'Webhook source IP not allowed' })
    }
    next()
  }
}

Note: Confirm exact SEF and FINA IP ranges from their integration documentation before deployment. Update SEF_WEBHOOK_IPS and FINA_WEBHOOK_IPS accordingly.

Input Validation

All inputs validated with Zod schemas:

Example: Invoice Validation

import { z } from 'zod'

const createInvoiceSchema = z.object({
  customerId: z.string().uuid(),
  invoiceDate: z.string().regex(/^\d{4}-\d{2}-\d{2}$/),
  dueDate: z.string().regex(/^\d{4}-\d{2}-\d{2}$/),
  currencyCode: z.enum(['EUR', 'RSD', 'BAM', 'HRK']),
  items: z.array(
    z.object({
    description: z.string().min(1).max(500),
    quantity: z.number().positive(),
    unitPrice: z.number().nonnegative(),
    taxRate: z.number().min(0).max(100),
  }),
  ),
})

// Middleware
function validate(schema: z.ZodSchema) {
  return (req, res, next) => {
    try {
      req.body = schema.parse(req.body)
      next()
    } catch (error) {
      res.status(400).json({ error: error.errors })
    }
  }
}

// Usage
app.post('/api/v1/invoices', validate(createInvoiceSchema), createInvoice);

8. File Upload Security

Allowed File Types

• Receipts:

  Allowed: JPG, PNG, PDF

PDF.
• Max size: 10MB per file

Validation

import multer from 'multer'
import path from 'path'

const upload = multer({
  limits: { fileSize: 10 *MB. 1024MIME *+ 1024extension },validation. //Stored 10MBin fileFilter:Cloudflare (req,R2 file,EU. cb) => {
    const allowedTypes = ['.jpg', '.jpeg', '.png', '.pdf']
    const ext = path.extname(file.originalname).toLowerCase()
    if (allowedTypes.includes(ext)) {
      cb(null, true)
    } else {
      cb(new Error('Invalid file type'))
    }
  },
})

Virus Scanning (Planned)

Phase 2: Integrate ClamAV for virus scanning before upload to R2.scanning.

{
  "eventId": 12345,
  "tableName": "invoices",
  "action": "UPDATE",
  "userId": "user-uuid",
  "actionTimestamp": "2026-02-20T10:30:00Z",
  "rowData": { "id": "invoice-uuid", "status": "draft" },
  "changedFields": { "status": { "old": "draft", "new": "sent" } },
  "clientIp": "192.168.1.10"
}

// Get user activity
await prisma.loggedAction.findMany({
  where: { userId: 'user-uuid' },
  orderBy: { actionTimestamp: 'desc' },
  take: 100,
})

// Get invoice history
await prisma.loggedAction.findMany({
  where: {
    tableName: 'invoices',
    rowData: { path: ['id'], equals: 'invoice-uuid' },
  },
})

await prisma.user.update({
  where: { id: userId },
  data: {
    email: `deleted-${userId}@example.com`,
    fullName: 'Deleted User',
    passwordHash: '',
    deletedAt: new Date(),
  },
})