Login returnsFlow with 2FA

1. User logs in → POST /api/v1/auth/login { email, password }
   ← 200 OK + { requires2FA: true, tempToken }

2. User enters code → POST /api/v1/auth/2fa/login { tempToken, code }
   ← Access token + Refresh token

Backup Codes

Generate 10 single-use codes,backup bcrypt-codes during 2FA setup:

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

3. Authorization (RBAC)

3.1Roles

Permission Matrix

3.2Implementation (Middleware)

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 (IDORJMBG, Prevention)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

// InjectedSAFE by— Prisma 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 limiting on auth middlewareendpoints (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 allevery endpoint
• Organization-scoped queries (middleware)
• No direct object reference (use UUIDs, not auto-increment IDs)

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

// AppliedApply to every Prisma queryqueries
await prisma.invoice.findMany({ where: { ...req.prismaWhere } });

6. Security Misconfiguration

UUIDMitigations:

keys
• Helmet.js throughoutsecurity —headers
• CORS whitelist (no sequential* IDin enumerationproduction)
possible.
• Error

  ---

  messages

  4.sanitized Encryption

  (no

  4.1stack Intraces Transit:in TLSproduction)

1.3
• Disable X-Powered-By header

Full Security Headers Configuration

All trafficsecurity HTTPS.headers Cloudflareapplied TLSvia 1.3Helmet.js aton edge,the re-encryptedExpress toAPI. Railway.The HSTS:Next.js frontend applies equivalent headers via max-age=63072000; includeSubDomains; preloadnext.config.js.

4.2

import Athelmet Rest:from AES-256

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. 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)

6. Rate Limiting

Prevent brute force and abuse:

Implementation

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.

7. 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:

Allowed File Types

• Receipts: 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.* MIME1024 +* extension1024 validation.}, Stored// in10MB
  CloudflarefileFilter: R2(req, EU.file, 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 scanning.for virus scanning before upload to R2.

9.Audit Trail

LoggedAction Table (Immutable)

All mutations logged:

• Table name
• Action (INSERT, UPDATE, DELETE)
• User ID
• Timestamp
• Old values (UPDATE/DELETE)
• New values (INSERT/UPDATE)
• Client IP
• SQL query

Example Audit TrailLog Entry

{
  "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"
}

Audit Queries

// 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' },
  },
})

Data Retention & Deletion

User Data Deletion (GDPR Right to Erasure)

Process:

1. User requests deletion → POST /api/v1/account/delete
2. Soft delete user record (mark deletedAt)
3. Anonymize LoggedAction entries (replace user ID with "deleted-user")
4. Delete PII (email, name)
5. Keep financial records (required by law, minimum 5 years)

Soft Delete Implementation:

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

Security Testing

Static Analysis

• ESLint: Security rules enabled (no-eval, no-unsafe-regex)
• TypeScript: Strict mode (catches type errors)

Dependency Scanning

• npm audit: Weekly checks
• Dependabot: Automatic PRs for vulnerabilities

Penetration Testing Plan

Frequency: Annual + after significant architecture changes Provider: External certified firm (OSCP or CREST certified) Environment: Staging only (staging.bilko.io) — LoggedActionnever (APPEND-ONLY)production without explicit CEO approval

Scope

On

Pre-Engagement GDPRChecklist

userId
• →Statement "deleted-user".of Financial entries retained 11 yearsWork (law).SoW) LoggedActionsigned neverwith deleted.pentest firm
•  Staging environment set up with production-equivalent configuration
•  Test data (fake organizations, fake invoices) loaded — no real customer data
•  Bilko DBA grants read-only DB access to pentest firm for review (not write)
•  Confirm staging SEF/FINA integrations are in test mode
•  Legal: pentest authorization letter from CEO on file

Acceptance Criteria

• Zero Critical or High findings unmitigated before production launch
• Medium findings: each assessed, documented, and either fixed or accepted with justification
• Remediation SLAs:
  • CRITICAL: 48 hours
  • HIGH: 7 days
  • MEDIUM: 30 days
  • LOW: Next sprint boundary

Pentest Report Requirements

The pentest report must include:

1. Executive summary (risk level, critical findings)
2. Technical findings: CVSS score, proof of concept, affected endpoints
3. Business impact statement for each finding
4. Remediation recommendations
5. Re-test results (confirm fixes for Critical and High)

10.Incident SecurityResponse HeadersPlan

Detection

• Monitor error rates (Helmet.js)Sentry)
• Monitor
failedloginattempts(>10in1hour=alert)(CPUspike,memoryleak)Whatisthebreach?(dataleak,DDoS,unauthorizedaccess)
• Contain:
BlockattackerIP,revokecompromised

Header	Value
Strict-Transport-Security	max-age=63072000; Railway includeSubDomains;metrics preload
Content-Security-Policy	default-src 'self'; Response script-src 'self' Identify: 'unsafe-inline'
X-Content-Type-Options	nosniff
X-Frame-Options	DENY
X-Powered-By	Removed

tokens
• Eradicate: Fix vulnerability, patch code
• Recover: Restore from backup if needed
• Document: Write post-mortem, update security docs

Notification

• Internal: Slack alert to #security channel
• External: Email users if PII compromised (GDPR 72h requirement)

---

11. Pre-Launch Security Checklist (Pre-Launch)

• JWT_SECRETJWT secrets generated (32+ chars, CSPRNG) — Railway env secret
•  JWT_REFRESH_SECRET separate key (32+ chars)
• FIELD_ENCRYPTION_KEYHTTPS generatedenforced (32no bytesHTTP hex) — for PIB/JMBG/OIB/JIB + IBANallowed)
• HTTPSCORS enforced
whitelist
• configured CORS:(no bilko.io only*)
• Rate limiting testedenabled (auth endpoints)
• Helmet.js security headers verifiedconfigured
• bcrypt roundspassword =hashing (12 rounds)
• All Prisma queries useparameterized org-scoped(no WHEREraw SQL)
• ZodInput validation on(Zod all endpointsschemas)
• LoggedActionFile triggerupload activerestrictions on(type, allsize)
tables
•  Audit trail enabled (LoggedAction)
• Error responsesmessages sanitized (no stack traces)
• Dependabot alerts enabled
• RailwayBackup regionstrategy = EU West confirmedtested
• DPAsIncident signedresponse (Railway,plan Vercel, Cloudflare, SendGrid)documented
• DataSecurity deletionreview workflow testedcompleted

---

Related Documents

• Compliance Framework:Compliance: compliance-framework.COMPLIANCE.md
• Data Encryption Policy:Deployment: data-encryption-policy.../infrastructure/DEPLOYMENT.md
• Key Management Policy: key-management-policy.md
• DPIA: data-protection-impact-assessment.md
• Breach Response: data-breach-response-plan.md
• Security Testing: security-testing-policy.md
• Bilko Security Docs: ../../products/Bilko/docs/security/testing/TESTING-GUIDE.md

---

Approval

Last

Updated: 25Status:FinalCompliance:OWASPTop10,GDPRArticle32(SecurityofProcessing)

Role	Name	Date	Signature
Author	Compliance Architect	2026-02-23
CTO
DPO
Engineering Lead