Security & Compliance

Security architecture, RBAC, encryption, GDPR compliance

Security Architecture

Bilko — Security Architecture

Status: PLANNED (backend not built yet, security measures documented for implementation)

This document defines the security architecture for Bilko, a financial SaaS handling sensitive accounting data.

Security Principles

  1. Defense in Depth — Multiple layers of security (network, application, database)
  2. Least Privilege — Users and services get minimum necessary permissions
  3. Zero Trust — Verify every request, never assume trust
  4. Encryption Everywhere — Data encrypted in transit and at rest
  5. Immutable Audit Trail — All actions logged, tamper-proof

Security Layers Diagram

graph TD
    CLIENT["Client Browser / PWA"]

    subgraph NETWORK["Network Layer"]
        CF["Cloudflare\nDDoS Protection\nTLS 1.3 termination\nHSTS"]
    end

    subgraph APP_LAYER["Application Layer"]
        HELMET["Helmet.js\nCSP + X-Frame + HSTS\nno X-Powered-By"]
        CORS["CORS Whitelist\nbilko.io only\nno wildcard *"]
        RATE["Rate Limiter\nexpress-rate-limit\n5 req/min auth\n100 req/min general"]
        AUTH_MW["Auth Middleware\nJWT verify\norg-scope injection"]
        RBAC_MW["RBAC Middleware\nrole check\nowner / admin / accountant / viewer"]
        ZOD["Zod Validation\nall request bodies\ntype-safe parsing"]
    end

    subgraph DATA_LAYER["Data Layer"]
        PRISMA_ORM["Prisma ORM\nparameterized queries\nno raw SQL for user input\norg-scoped WHERE"]
        PG_ENC["PostgreSQL Railway\nAES-256 disk encryption\nbackup encryption"]
    end

    subgraph AUDIT["Audit Layer"]
        LOG["LoggedAction table\nAPPEND-ONLY\nIP + user + timestamp\nold/new values"]
    end

    CLIENT --> CF --> HELMET --> CORS --> RATE --> AUTH_MW --> RBAC_MW --> ZOD --> PRISMA_ORM --> PG_ENC
    PRISMA_ORM --> LOG

Authentication

Strategy: JWT (JSON Web Tokens)

Why JWT?

Token Types

Access Token

Refresh Token

JWT Payload Example

{
  "sub": "user-uuid",
  "org": "org-uuid",
  "role": "admin",
  "iat": 1640000000,
  "exp": 1640000900
}

Token Flow

1. User logs in → POST /api/v1/auth/login
   ← Access token (header) + Refresh token (httpOnly cookie)

2. User makes request → GET /api/v1/invoices (Authorization: Bearer <access>)
   ← Protected resource

3. Access token expires (15 min) → POST /api/v1/auth/refresh (httpOnly cookie)
   ← New access token + New refresh token

4. User logs out → POST /api/v1/auth/logout
   → Delete refresh token from DB
   ← 204 No Content

JWT Auth Flow (Sequence)

sequenceDiagram
    actor User
    participant FE as Frontend (bilko.io)
    participant API as Express API (api.bilko.io)
    participant DB as PostgreSQL

    User->>FE: Enter email + password
    FE->>API: POST /api/v1/auth/login
    API->>DB: SELECT user WHERE email = ?
    DB-->>API: User record (passwordHash)
    API->>API: bcrypt.compare(password, hash)
    alt Password valid
        API->>API: jwt.sign({sub, org, role}, JWT_SECRET, 15m)
        API->>API: jwt.sign({sub}, JWT_REFRESH_SECRET, 7d)
        API->>DB: INSERT refreshToken (hashed, expiresAt)
        API-->>FE: 200 { accessToken } + Set-Cookie: refreshToken (httpOnly)
        FE->>FE: Store accessToken in memory
    else Password invalid
        API-->>FE: 401 Unauthorized
    end

    Note over FE,API: 15 minutes later — access token expires
    FE->>API: POST /api/v1/auth/refresh (Cookie: refreshToken)
    API->>DB: SELECT refreshToken WHERE token = ? AND expiresAt > NOW()
    DB-->>API: Valid token record
    API->>API: Rotate: delete old, issue new refresh token
    API->>DB: DELETE old refreshToken, INSERT new refreshToken
    API-->>FE: 200 { newAccessToken } + Set-Cookie: newRefreshToken

    Note over User,DB: User logs out
    User->>FE: Click logout
    FE->>API: POST /api/v1/auth/logout
    API->>DB: DELETE refreshToken WHERE userId = ?
    API-->>FE: 204 No Content
    FE->>FE: Clear accessToken from memory

Implementation (Backend)

import jwt from 'jsonwebtoken';
import bcrypt from 'bcrypt';

// Generate access token
const accessToken = jwt.sign(
  { sub: user.id, org: user.organizationId, role: user.role },
  process.env.JWT_SECRET!,
  { expiresIn: '15m' }
);

// Generate refresh token
const refreshToken = jwt.sign(
  { sub: user.id },
  process.env.JWT_REFRESH_SECRET!,
  { expiresIn: '7d' }
);

// Store refresh token in DB (for revocation)
await prisma.refreshToken.create({
  data: {
    token: refreshToken,
    userId: user.id,
    expiresAt: new Date(Date.now() + 7 * 24 * 60 * 60 * 1000),
  },
});

Password Security

Hashing: bcrypt

Algorithm: bcrypt with 12 salt rounds

Why bcrypt?

Password Requirements

Implementation

import bcrypt from 'bcrypt';

// Hash password (registration)
const passwordHash = await bcrypt.hash(password, 12);

// Verify password (login)
const isValid = await bcrypt.compare(password, user.passwordHash);

Two-Factor Authentication (2FA)

Strategy: TOTP (Time-based One-Time Password)

Compatible with:

Setup Flow

1. User enables 2FA → POST /api/v1/auth/2fa/setup
   ← QR code + secret (base32)

2. User scans QR code in authenticator app
   → Generates 6-digit code

3. User verifies code → POST /api/v1/auth/2fa/verify { code }
   ← 200 OK (2FA enabled)

Login Flow 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 backup codes during 2FA setup:

Authorization (RBAC)

RBAC Permission Model

classDiagram
    class Owner {
        +createInvoice()
        +editInvoice()
        +deleteInvoice()
        +viewInvoice()
        +approveExpense()
        +generateReport()
        +inviteUser()
        +editOrgSettings()
        +deleteOrg()
    }
    class Admin {
        +createInvoice()
        +editInvoice()
        +viewInvoice()
        +approveExpense()
        +generateReport()
        -deleteInvoice()
        -inviteUser()
        -editOrgSettings()
    }
    class Accountant {
        +viewInvoice()
        +viewExpense()
        +generateReport()
        -createInvoice()
        -editInvoice()
        -approveExpense()
        -inviteUser()
    }
    class Viewer {
        +viewDashboard()
        +viewReports()
        -createInvoice()
        -editInvoice()
        -generateReport()
        -inviteUser()
    }

    Owner --|> Admin : inherits all Admin permissions
    Admin --|> Accountant : inherits read access
    Accountant --|> Viewer : inherits view access

Roles

Role Permissions
owner Full access (edit org settings, invite users, delete data)
admin Manage invoices, expenses, contacts, reports (no org settings)
accountant Read invoices/expenses, create reports (no edit)
viewer Read-only access (dashboard, reports)

Permission Matrix

Action owner admin accountant viewer
Create invoice ✅ ✅ ❌ ❌
Edit invoice ✅ ✅ ❌ ❌
Delete invoice ✅ ❌ ❌ ❌
View invoice ✅ ✅ ✅ ✅
Approve expense ✅ ✅ ❌ ❌
Generate report ✅ ✅ ✅ ❌
Invite user ✅ ❌ ❌ ❌
Edit org settings ✅ ❌ ❌ ❌

Implementation (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);

Encryption

In Transit: TLS 1.3

All traffic encrypted via HTTPS:

TLS Configuration:

At Rest: Database Encryption

PostgreSQL (Railway):

Cloudflare R2 (Files):

Secrets Management

NEVER commit secrets to git:

OWASP Top 10 Mitigations

1. Injection (SQL Injection)

Mitigation: Prisma ORM parameterized queries

// SAFE — 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:

3. Sensitive Data Exposure

Mitigations:

4. XML External Entities (XXE)

Not applicable — Bilko does not parse XML.

5. Broken Access Control

Mitigations:

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

// Apply to queries
await prisma.invoice.findMany({ where: req.prismaWhere });

6. Security Misconfiguration

Mitigations:

import helmet from 'helmet';

app.use(helmet({
  contentSecurityPolicy: {
    directives: {
      defaultSrc: ["'self'"],
      scriptSrc: ["'self'", "'unsafe-inline'"], // Next.js requires unsafe-inline
      styleSrc: ["'self'", "'unsafe-inline'"],
      imgSrc: ["'self'", "data:", "https:"],
    },
  },
}));

7. Cross-Site Scripting (XSS)

Mitigations:

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

10. Insufficient Logging & Monitoring

Mitigations:

Rate Limiting

Rate Limiting Flow

flowchart TD
    REQ["Incoming Request"]
    ENDPOINT{{"Endpoint?"}}

    AUTH_CHECK{{"IP count\n≤5 per 15min?"}}
    REG_CHECK{{"IP count\n≤3 per 60min?"}}
    REFRESH_CHECK{{"IP count\n≤10 per 15min?"}}
    REPORT_CHECK{{"User count\n≤10 per 15min?"}}
    GENERAL_CHECK{{"IP count\n≤100 per 15min?"}}

    PASS["Pass to route handler"]
    BLOCK["429 Too Many Requests\n'Try again later'"]

    REQ --> ENDPOINT
    ENDPOINT -->|"/auth/login"| AUTH_CHECK
    ENDPOINT -->|"/auth/register"| REG_CHECK
    ENDPOINT -->|"/auth/refresh"| REFRESH_CHECK
    ENDPOINT -->|"/reports/*"| REPORT_CHECK
    ENDPOINT -->|"all other /api/*"| GENERAL_CHECK

    AUTH_CHECK -->|Yes| PASS
    AUTH_CHECK -->|No| BLOCK
    REG_CHECK -->|Yes| PASS
    REG_CHECK -->|No| BLOCK
    REFRESH_CHECK -->|Yes| PASS
    REFRESH_CHECK -->|No| BLOCK
    REPORT_CHECK -->|Yes| PASS
    REPORT_CHECK -->|No| BLOCK
    GENERAL_CHECK -->|Yes| PASS
    GENERAL_CHECK -->|No| BLOCK

Prevent brute force and abuse:

Endpoint Limit Window
/api/v1/auth/login 5 requests 15 minutes
/api/v1/auth/register 3 requests 60 minutes
/api/v1/auth/refresh 10 requests 15 minutes
/api/v1/* (general) 100 requests 15 minutes
/api/v1/reports/* 10 requests 15 minutes

Implementation

import rateLimit from 'express-rate-limit';

const authLimiter = rateLimit({
  windowMs: 15 * 60 * 1000, // 15 minutes
  max: 5,
  message: 'Too many login attempts, try again later',
});

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

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

File Upload Security

Allowed File Types

Validation

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

const upload = multer({
  limits: { fileSize: 10 * 1024 * 1024 }, // 10MB
  fileFilter: (req, 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 for virus scanning before upload to R2.

Audit Trail

LoggedAction Table (Immutable)

All mutations logged:

Example Audit Log 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

Dependency Scanning

Penetration Testing (Future)

Incident Response Plan

Detection

Response

  1. Identify: What is the breach? (data leak, DDoS, unauthorized access)
  2. Contain: Block attacker IP, revoke compromised tokens
  3. Eradicate: Fix vulnerability, patch code
  4. Recover: Restore from backup if needed
  5. Document: Write post-mortem, update security docs

Notification

Security Checklist (Pre-Launch)

Last Updated: 2026-02-20 Status: PLANNED — Backend not built yet, security measures to be implemented Compliance: OWASP Top 10, GDPR Article 32 (Security of Processing)

GDPR & Compliance

Bilko — Regulatory Compliance

Status: NOT COMPLIANT — Requires legal review and implementation (Phase 2)

This document outlines regulatory compliance requirements for Bilko as a Balkan accounting SaaS.

Compliance Scope

Bilko operates in a highly regulated space:

Region Regulations
EU/EEA GDPR (General Data Protection Regulation)
Serbia Zakon o računovodstvu, SEF (Sistem E-Faktura)
Bosnia & Herzegovina Zakon o PDV-u, Electronic bookkeeping requirements
Croatia Zakon o fiskalizaciji, eRačun (public sector invoicing)

Current Status: MVP focuses on GDPR compliance. Balkan-specific regulations deferred to Phase 2.

Compliance Roadmap by Phase

graph LR
    subgraph P1["Phase 1 — MVP (pre-launch)"]
        GDPR["GDPR\nData minimization\nEncryption TLS+AES-256\nUser rights endpoints\nDPA with processors"]
    end

    subgraph P2["Phase 2 — Serbia Launch (3-6mo)"]
        RS_COA["Serbian CoA\n(Kontni plan template)"]
        RS_VAT["VAT 20%\nReporting"]
        RS_REP["Financial Reports\nBilans stanja\nBilans uspeha"]
        RS_SEF["SEF Integration\nB2G e-invoicing\n(optional at MVP)"]
    end

    subgraph P3["Phase 3 — Regional (12-18mo)"]
        BIH["BiH\nVAT 17%\nPDV prijava"]
        HR["Croatia\nVAT 25%\nFiskalizacija 2.0\neRačun B2G\nDigital signature"]
    end

    P1 --> P2 --> P3

GDPR (General Data Protection Regulation)

Applicability

Data We Collect

Data Type Purpose Legal Basis Retention
Email Account authentication Contract performance Until account deletion
Full name User identification Contract performance Until account deletion
IP address Security audit trail Legitimate interest 30 days
Password (hashed) Authentication Contract performance Until account deletion
Organization name Service delivery Contract performance 5 years (accounting law)
Financial records Service delivery Legal obligation 5-10 years (varies by country)

GDPR Principles Compliance

1. Lawfulness, Fairness, Transparency (Article 5(1)(a))

Implementation:

Status: PLANNED — Privacy policy to be drafted

2. Purpose Limitation (Article 5(1)(b))

Implementation:

Status: COMPLIANT (by design)

3. Data Minimization (Article 5(1)(c))

Implementation:

Status: COMPLIANT (by design)

4. Accuracy (Article 5(1)(d))

Implementation:

Status: COMPLIANT (by design)

5. Storage Limitation (Article 5(1)(e))

Implementation:

Status: PLANNED — Deletion workflow to be implemented

6. Integrity & Confidentiality (Article 5(1)(f))

Implementation:

Status: PLANNED — See SECURITY-ARCHITECTURE.md

GDPR Data Flow Diagram

flowchart TD
    USER["User (Data Subject)"]
    REG["Registration\nPOST /api/v1/auth/register"]
    STORE_PII["Store PII\nRailway EU West (Frankfurt)\nAES-256 at rest\nemail, name, passwordHash (bcrypt)"]
    PROCESS["Service Processing\nInvoices, Expenses, Reports\nOrganization data"]
    LOG["Audit Trail\nLoggedAction table\nIP + timestamp (30 days)"]
    FILE["File Storage\nCloudflare R2 EU\nReceipts + PDFs\nAES-256"]

    subgraph THIRD["Third-Party Processors (DPA Required)"]
        RAILWAY["Railway EU West\n(DB hosting)"]
        VERCEL["Vercel\n(Frontend hosting)"]
        CF_R2["Cloudflare R2 EU\n(File storage)"]
        SG["SendGrid\n(Transactional email)"]
    end

    USER -->|"Consent via ToS"| REG --> STORE_PII
    STORE_PII --> PROCESS --> LOG
    PROCESS --> FILE

    STORE_PII --> RAILWAY
    REG --> VERCEL
    FILE --> CF_R2
    PROCESS -->|"Invoice emails"| SG

GDPR Rights (Articles 12-22)

Right to Access (Article 15)

User can request:

Implementation:

// Endpoint: GET /api/v1/account/data
await prisma.user.findUnique({
  where: { id: userId },
  include: { organization: true, auditLogs: true },
});

Status: PLANNED

Right to Rectification (Article 16)

User can:

Implementation:

// Endpoint: PATCH /api/v1/account/profile
await prisma.user.update({
  where: { id: userId },
  data: { email, fullName },
});

Status: PLANNED

Right to Erasure (Article 17)

Exceptions:

Implementation:

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

Status: PLANNED

Right to Data Portability (Article 20)

User can:

Implementation:

// Endpoint: GET /api/v1/account/export
const data = {
  user: await prisma.user.findUnique({ where: { id: userId } }),
  invoices: await prisma.invoice.findMany({ where: { organizationId } }),
  expenses: await prisma.expense.findMany({ where: { organizationId } }),
};
res.json(data);

Status: PLANNED

Right to Object (Article 21)

Not applicable — Bilko does not use profiling or automated decision-making.

Data Processing Agreement (DPA)

Required when Bilko processes customer data on behalf of organizations.

Third-Party Processors:

Service Purpose DPA Available? GDPR Compliant?
Railway Database hosting Yes Yes (EU region)
Vercel Frontend hosting Yes Yes
Cloudflare R2 storage, DNS Yes Yes
SendGrid Transactional email Yes Yes

Action Required: Sign DPAs with all processors before launch.

Status: PENDING

Data Breach Notification (Article 33)

Requirement:

Process:

  1. Detect breach (monitoring, user report)
  2. Assess impact (how many users, what data)
  3. Contain breach (block attacker, revoke tokens)
  4. Notify authority (within 72h)
  5. Notify users (if high risk)
  6. Document incident (post-mortem)

Breach Notification Flow

sequenceDiagram
    participant MON as Monitoring (Sentry / Railway)
    participant JOHN as John (AI Director)
    participant ALEM as Alem (CEO)
    participant AUTH as Supervisory Authority
    participant USERS as Affected Users

    MON->>JOHN: Alert: anomaly detected
    JOHN->>JOHN: Assess impact\n(data type, user count)
    JOHN->>JOHN: Contain: revoke tokens\nblock attacker IP
    JOHN->>ALEM: Breach report + impact summary

    alt High risk to users
        ALEM->>AUTH: Notify within 72h (GDPR Art. 33)
        ALEM->>USERS: Email notification\n(nature of breach, data affected,\nsteps taken)
    else Low risk
        ALEM->>AUTH: Optional notification
        Note over USERS: No user notification required
    end

    JOHN->>JOHN: Post-mortem\nUpdate security docs\nPatch vulnerability

Status: PLANNED — Incident response plan documented in SECURITY-ARCHITECTURE.md

Data Protection Officer (DPO)

Required? No — Bilko does not meet GDPR Article 37 criteria:

Threshold: DPO required if >250 employees or large-scale processing. Bilko is small startup.

Status: NOT REQUIRED (as of 2026-02-20)

Data Residency

Requirement: Store EU user data within EU/EEA (GDPR Article 44-50)

Implementation:

Status: PLANNED — Configure Railway to EU region on deployment

Serbia — Zakon o računovodstvu (Accounting Law)

Applicability

Requirements

1. Chart of Accounts

Regulation: Companies must use standardized chart of accounts (Kontni plan)

Implementation:

Status: PLANNED — Create Serbian CoA seed data

2. Double-Entry Bookkeeping

Regulation: All transactions must use double-entry (debit + credit)

Implementation:

Status: COMPLIANT (by design)

3. Financial Reporting

Required reports:

Implementation:

Status: PLANNED — Backend report generation

4. Data Retention

Regulation: Financial records must be kept minimum 5 years

Implementation:

Status: PLANNED

SEF (Sistem E-Faktura) — Electronic Invoicing

Requirement: B2G (business-to-government) invoices must be submitted electronically via SEF portal.

Applicability:

Implementation (Phase 2):

Status: NOT IMPLEMENTED — Deferred to Phase 2

Bosnia & Herzegovina — Zakon o PDV-u (VAT Law)

VAT Rates

Requirements

1. VAT Calculation

Implementation:

Status: COMPLIANT (by design)

2. VAT Reporting

Required report:

Implementation:

Status: PLANNED — Backend report generation

3. Electronic Bookkeeping

Regulation: Companies with revenue >50,000 BAM must maintain electronic records.

Implementation:

Status: PLANNED (Phase 2)

Croatia — Zakon o fiskalizaciji (Fiscalization Law)

Applicability

Requirements

1. Fiscalization (Fiskalizacija 2.0)

Regulation: All invoices must be registered with tax authority in real-time.

Implementation (Phase 2):

Status: NOT IMPLEMENTED — Deferred to Phase 2

2. eRačun (Public Sector Invoicing)

Requirement: B2G invoices must be submitted via eRačun system.

Implementation (Phase 2):

Status: NOT IMPLEMENTED — Deferred to Phase 2

Multi-Country Compliance Matrix

Requirement Serbia BiH Croatia Implementation Status
Double-entry bookkeeping ✅ Required ✅ Required ✅ Required ✅ Compliant (Prisma schema)
VAT calculation 20% 17% 25% ✅ Compliant (configurable)
VAT reporting ✅ Required ✅ Required ✅ Required ⏳ Planned
Financial reports ✅ Required ✅ Required ✅ Required ⏳ Planned
Data retention (5 years) ✅ Required ✅ Required ✅ Required ⏳ Planned
Electronic invoicing (B2G) ✅ SEF ❌ Optional ✅ eRačun ❌ Phase 2
Real-time fiscalization ❌ Not required ❌ Not required ✅ Required ❌ Phase 2
Digital signature ❌ Not required ❌ Not required ✅ Required ❌ Phase 2

Data Retention Lifecycle

stateDiagram-v2
    [*] --> Active : User registers

    Active --> DeletionRequested : POST /api/v1/account/delete
    Active --> Active : Normal usage\n(invoices, expenses, reports)

    DeletionRequested --> SoftDeleted : Anonymize PII\nemail → deleted-{uuid}@example.com\nname → "Deleted User"\npasswordHash → ""

    SoftDeleted --> AuditAnonymized : Replace userId\nin LoggedAction\nwith "deleted-user"

    AuditAnonymized --> FinancialRetained : Financial records\nKEPT for 5 years\n(legal obligation Serbia/BiH/HR)

    FinancialRetained --> PermanentDelete : After 5-year\nretention period

    PermanentDelete --> [*]

    note right of Active
        IP logs: 30 days
        Audit trail: 30 days
        Financial data: indefinite (legal)
    end note

    note right of FinancialRetained
        Invoices, expenses,\ntransactions, reports\nretained per Zakon o računovodstvu
        User PII already anonymized
    end note

Compliance Roadmap

Phase 1 (MVP) — GDPR Only

Timeline: Pre-launch (before first customer)

Phase 2 (Serbia Launch)

Timeline: 3-6 months after MVP

Phase 3 (Regional Expansion)

Timeline: 12-18 months after MVP

Compliance Checklist (Pre-Launch)

GDPR

Serbia (Phase 2)

BiH (Phase 3)

Croatia (Phase 3)

Risk Assessment

Risk Likelihood Impact Mitigation
GDPR fine Low (if compliant) High (€20M) Implement all GDPR requirements pre-launch
Data breach Medium High Encryption, rate limiting, security audit
Serbian non-compliance Medium Medium Hire local accountant as advisor
Croatian fiscalization failure Low (Phase 3) High Partner with Croatian accounting firm
User data loss Low High Daily backups, test restore process

IMPORTANT: This document is for internal planning only. It is NOT legal advice.

Before launch:

Last Updated: 2026-02-20 Status: NOT COMPLIANT — Requires implementation and legal review Next Review: Before first paying customer Compliance Officer: TBD (hire accounting advisor in Phase 2)

Bilko CIAM abuse-gate fix — checkBefore moved outside SERIALIZABLE tx (MC #104069, root-cause of #103245)

Bilko CIAM abuse-gate fix — checkBefore moved outside SERIALIZABLE tx

MC #104069 | Root-cause of MC #103245 | Fixed 2026-06-20

1. THE BUG (root cause)

MC #103245 [H1-PRE-PUBLIC-LAUNCH] CIAM abuse gate was marked done 2026-06-09 16:35, but the actual fix was committed 17:27 and NEVER merged. In origin/main, CiamAbuseGate.checkBefore() ran ONLY inside UserProvisioningService.kt (called from inside the SERIALIZABLE transaction{} block in AuthService.createSessionFromEntraIdToken, line 334).

Exposed's SERIALIZABLE transaction retry handler caught/swallowed DisposableEmailException and TooManyRequestsException → disposable-email accounts (e.g. guerrillamailblock.com) and over-rate-limit requests got provisioned with HTTP 200 despite the gate. The disposable-email + rate-limit abuse gate was effectively defeated on the JIT/Entra provisioning path.

2. THE FIX

Commit: a862355a → rebased deb1621d
Branch: fix/abuse-gate-tx-swallow-103245
PR: #3

Changes:

3. VERIFICATION

4. PROCESS LESSON

A parent MC was closed before its fix was merged → the fix sat unmerged in a worktree for ~11 days.

Lesson: Do not mark a security MC done until the fix is verified merged on main. Link this to the broader "no fake DONE" rule.

References