Field-levelIn addition to Railway disk encryption is applied to JMBG and OIB BEFORE writing to the database. The database column stores only ciphertext. The application decrypts on read.

Algorithm

• Algorithm: AES-256-GCM (authenticated encryption — provides confidentiality + integrity)
• IV: 12 bytes, randomly generated per encryption operation
• Key: 32 bytes (256 bits), stored in FIELD_ENCRYPTION_KEY environment variable (Railway secret)
• Output format: base64(iv):base64(authTag):base64(ciphertext) stored as TEXT column

Implementation

import { createCipheriv, createDecipheriv, randomBytes }crypto from 'crypto';

const ALGORITHM = 'aes-256-gcm'async function getKey(): Buffer {
  const hex = process.env.FIELD_ENCRYPTION_KEY
  if (!hex || hex.length !== 64) {
    throw new Error('FIELD_ENCRYPTION_KEY must be a 64-character hex string (32 bytes)')
  }
  return Buffer.from(hex, 'hex')
}

export function encryptField(encryptRestrictedField(plaintext: string): Promise<string> {
  const key = getKey(Buffer.from(process.env.FIELD_ENCRYPTION_KEY!, 'hex'); // 32 bytes
  const iv = crypto.randomBytes(12); // 96-bit IV for GCM
  const cipher = crypto.createCipheriv(ALGORITHM,'aes-256-gcm', key, iv);
  const encryptedciphertext = Buffer.concat([cipher.update(plaintext, 'utf8'), cipher.final()]);
  const authTagtag = cipher.getAuthTag();
  // Store: base64(iv || tag || ciphertext)
  return Buffer.concat([iv, authTag,tag, encrypted]ciphertext]).map((b) => b.toString('base64')).join(':');
}

exportasync function decryptField(ciphertext:decryptRestrictedField(stored: string): Promise<string> {
  const key = getKey(Buffer.from(process.env.FIELD_ENCRYPTION_KEY!, 'hex');
  const [ivB64, tagB64, encB64]buf = ciphertext.split(Buffer.from(stored, ':'base64');
  const iv = Buffer.from(ivB64,buf.subarray(0, 'base64')12);
  const authTagtag = Buffer.from(tagB64,buf.subarray(12, 'base64')28);
  const encryptedciphertext = Buffer.from(encB64, 'base64')buf.subarray(28);
  const decipher = crypto.createDecipheriv(ALGORITHM,'aes-256-gcm', key, iv);
  decipher.setAuthTag(authTag)tag);
  return Buffer.concat([decipher.update(encrypted),ciphertext) + decipher.final()]).toString('utf8');
}

Fields3.2 SubjectFile to Field-LevelStorage Encryption (L4-A)

Fields3.3 NOTBackup SubjectEncryption

Railway provides automatic daily PostgreSQL backups, encrypted with AES-256. Backup retention: 30 days (Railway default). Custom backup strategy to be implemented in Phase 2 with separate backup encryption key stored in Railway environment secrets.

4. Encryption in Transit

4.1 TLS Configuration

Minimum TLS version:

• External-facing (api.bilko.io, bilko.io): TLS 1.3 (enforced via Cloudflare)
• Railway internal: TLS 1.3

Approved cipher suites (TLS 1.3):

TLS_AES_256_GCM_SHA384
TLS_CHACHA20_POLY1305_SHA256
TLS_AES_128_GCM_SHA256 (minimum)

HSTS configuration:

Strict-Transport-Security: max-age=63072000; includeSubDomains; preload

HTTP redirect: All HTTP traffic redirected to HTTPS (301). No HTTP allowed in production.

Prohibited:

• TLS 1.0 and TLS 1.1 — prohibited
• SSL 2.0 / SSL 3.0 — prohibited
• RC4 cipher suites — prohibited

4.2 Cookie Security

All session cookies set with:

res.cookie('refreshToken', token, {
  httpOnly: true,    // Not accessible to JavaScript
  secure: true,      // HTTPS only
  sameSite: 'strict', // CSRF protection
  maxAge: 7 * 24 * 60 * 60 * 1000, // 7 days
});

4.3 API Security Headers (Helmet.js)

app.use(helmet({
  hsts: { maxAge: 63072000, includeSubDomains: true, preload: true },
  contentSecurityPolicy: {
    directives: {
      defaultSrc: ["'self'"],
      scriptSrc: ["'self'", "'unsafe-inline'"],
      styleSrc: ["'self'", "'unsafe-inline'"],
      imgSrc: ["'self'", "data:", "https:"],
    },
  },
}));

5. Application-Level Encryption

5.1 Field-Level Encryption (L4-B — Disk-Level + Controls)Requirements

PerRequired ADR-014,for the followingall L4 fieldsRestricted are protected by disk-level encryption (Railway AES-256) plus application-layer controls rather than field-level encryption. Field-level encryption for these fields is disproportionate: PIB and JIB are publicly searchable on government registries; IBAN is routinely shared for payment.fields:

Searchability5.2 JWT Token Encryption

L4-AJWTs encrypted fields (JMBG, OIB) cannot be searchedsigned with SQLHMAC-SHA-256 LIKE(HS256) orusing equality. Exact-match lookup uses HMAC hash columns:JWT_SECRET:

• StoreJWT_SECRET: a32+ deterministiccharacter random string (CSPRNG), stored in Railway secrets
• JWT_REFRESH_SECRET: Separate 32+ character key — never same as JWT_SECRET
• Access token payload: { sub: userId, org: organizationId, role, iat, exp }
• NO PII in JWT payload — no email, name, tax ID

Refresh tokens stored as HMAC-SHA256SHA-256 hash in database — raw token never stored.

5.3 Password Hashing

jmbgHashimport bcrypt from 'bcrypt';

// oibHashRegistration
column (separate FIELD_HMAC_KEY)
Search is performed on theconst hash column
= 
Fullawait plaintextbcrypt.hash(plainPassword, is12);

decrypted// onlyLogin whenverification
displayingconst toisValid an= authorizedawait user
bcrypt.compare(plainPassword,